# A Simple HOWTO for Using
Berkeley DB Java Edition
on the
Android Platform

4.0.103, April 28, 2010

## Overview

JE can be used with the Google Android platform. This document discusses how to create a simple program and UI which will allow a user to do trivial JE "gets" and "puts" from within Android.

## Installation

- Start by downloading and installing the Android SDK. Put the Android "tools" directory in your path so that you pick up the command line tools.
- Locate the je-android-x.y.z.jar file in the `JE_HOME/lib` directory of the release you are using.
- Review `<android-home>/docs/guide/tutorials/hello-world.html` for instructions on how to install the SDK and the Android plugin (if you're using Eclipse).

## Steps With Android Eclipse Plugin

- Go to `"File->New->Project->Android->Android Project->Next Project"`. Then provide a Project name (JEExample), application name (JEExample), package name (`com.sleepycat.je`), and activity name (`JEExample`). Click Finish.
- Add the je-android-x.y.z.jar file to the project libs directory: `<eclipse-je-android-dir>/libs`. You may have to create the `libs` directory.
- Copy
  `JEExample.java` to `<eclipse-je-android-dir>/src/com/sleepycat/je`,
  `main.xml` to `res/layout/main.xml` and
  `strings.xml` to `res/values/strings.xml`
  These files are shown at the bottom of this page.
- Build a new Configure Launch for this project, then run it as an Android project.

## Steps Without Android Eclipse Plugin

- If you haven't already made an AVD, do
  `android create avd --target 2 --name my_avd`
  Target 2 is Android 1.6, but you can "android list target" to see a list of available targets. Then, with your current directory being a place where you want to create your project, do
  `android create project --path JEExample --package com.sleepycat.je --name JEExample --activity JEExample --target 2`
  This creates `JEExample/src/com/sleepycat/je/JEExample.java`
- Copy the je-android-x.y.z.jar file to the project libs directory: `JEExample/libs`
- Replace the generated contents of `JEExample/src/com/sleepycat/je/JEExample.java`, `JEExample/res/layout/main.xml`, `JEExample/res/values/strings.xml` with the source code for `JEExample.java`, `main.xml` and `strings.xml` shown at the bottom of this page.
- Go to the `<android-installation-home>/platforms/android-1.6/tools`, open and edit the `dx.bat` file, and change the line which says "`REM set javaOpts=-Xmx256M`" to "`set javaOpts=-Xmx512M`".
- Run the Android emulator.
- In the `JEExample` directory, do
  `ant install`
  This will compile `JEExample.java` as well as convert the resulting class files to dex files. This also creates `JEExample/bin/JEExample-debug.apk` and installs this application on the emulator.

## Run the test

- Create the JE environment directory by doing:
  `adb shell mkdir /data/local/je`
  You can remove the JE Environment files by doing:
  `adb shell rm /data/local/je/*`
- Run the JEExample application in the emulator by clicking on the Home icon, then the uparrow button above the Menu button, then JEExample icon. A screen titled "JEExample" should appear with a TextEdit box, a "Put Data" button, and a "Get Data" button.
- Put some key/data pairs into the JE database by entering (e.g.)
  `k1/data1`
  and pressing the "Put Data" button.
- Retrieve ("get") key/data pairs from the JE database by entering (e.g.)
  `k1`
  and pressing the "Get Data" button.

## Source Code

- JEExample.java

      package com.sleepycat.je;

      import android.app.Activity;
      import android.app.AlertDialog;
      import android.content.DialogInterface;
      import android.util.Log;
      import android.os.Bundle;
      import android.view.View;
      import android.widget.Button;
      import android.widget.EditText;
      import android.widget.TextView;

      import java.io.File;

      import com.sleepycat.je.Database;
      import com.sleepycat.je.DatabaseConfig;
      import com.sleepycat.je.DatabaseEntry;
      import com.sleepycat.je.DatabaseException;
      import com.sleepycat.je.Environment;
      import com.sleepycat.je.EnvironmentConfig;
      import com.sleepycat.je.OperationStatus;
      import com.sleepycat.je.Transaction;

      public class JEExample extends Activity {

          @Override
          public void onCreate(Bundle icicle) {
              super.onCreate(icicle);

              try {
                  final File envDir = new File("/data/local/je");
                  final EnvironmentConfig envConfig = new EnvironmentConfig();
                  envConfig.setTransactional(true);
                  envConfig.setAllowCreate(true);
                  final Environment env = new Environment(envDir, envConfig);
                  final DatabaseConfig dbConfig = new DatabaseConfig();
                  dbConfig.setTransactional(true);
                  dbConfig.setAllowCreate(true);
                  dbConfig.setSortedDuplicates(true);
                  final Database db = env.openDatabase(null, "exampledb", dbConfig);

                  setContentView(R.layout.main);
                  final Button button1 = (Button) findViewById(R.id.do_put);
                  button1.setOnClickListener(new Button.OnClickListener() {
                      public void onClick(View v) {

                          final EditText editText =
                              (EditText) findViewById(R.id.entry);
                          final String keyData = editText.getText().toString();
                          final int idx = keyData.indexOf("/");
                          String key = null;
                          String data = null;
                          String result = null;
                          if (idx < 0) {
                              result = "enter key/data to put";
                          } else {
                              key = keyData.substring(0, idx);
                              data = keyData.substring(idx + 1);
                              result = key + "/" + data;
                              final DatabaseEntry keyEntry =
                                  new DatabaseEntry(key.getBytes());
                              final DatabaseEntry dataEntry =
                                  new DatabaseEntry(data.getBytes());

                              try {
                                  final Transaction txn =
                                      env.beginTransaction(null, null);
                                  final OperationStatus res =
                                      db.put(txn, keyEntry, dataEntry);
                                  if (res != OperationStatus.SUCCESS) {
                                      result = "Error: " + res.toString();
                                  }
                                  txn.commit();
                              } catch (DatabaseException DE) {
                                  result = "Caught exception: " + DE.toString();
                              }
                          }
                          Log.d("JE", "did put of: " + result);

                          if (result.contains("Caught exception:")) {
                          	new AlertDialog.Builder(JEExample.this).
                          	    setTitle("Put Data").setMessage(result).
                          	    setPositiveButton("Quit", new DialogInterface.OnClickListener() {
                          		    public void onClick(DialogInterface dialog, int whichButton) {
                          		    }
                          		}).show();
                          } else {
                          	new AlertDialog.Builder(JEExample.this).
                      	        setTitle("Put Data").setMessage("You put the key/data pair: " + result).
                      	        setPositiveButton("Confirm", new DialogInterface.OnClickListener() {
                      		        public void onClick(DialogInterface dialog, int whichButton) {
                      		        }
                      		    }).show();
                          }
                      }
                  });

                  final Button button2 = (Button) findViewById(R.id.do_get);
                  button2.setOnClickListener(new Button.OnClickListener() {
                      public void onClick(View v) {

                          final EditText editText =
                              (EditText) findViewById(R.id.entry);
                          final String key = editText.getText().toString();
                          final DatabaseEntry keyEntry =
                              new DatabaseEntry(key.getBytes());
                          final DatabaseEntry dataEntry = new DatabaseEntry();
                          String result = null;
                          try {
                              final Transaction txn =
                                  env.beginTransaction(null, null);
                              final OperationStatus res =
                                  db.get(txn, keyEntry, dataEntry, null);
                              if (res != OperationStatus.SUCCESS) {
                                  result = "Error: " + res.toString();
                              } else {
                                  result = new String(dataEntry.getData());
                              }
                              txn.commit();
                          } catch (DatabaseException DE) {
                              result = "Caught exception: " + DE.toString();
                          }
                          Log.d("JE", "did get of: " + result);
                          if (result.contains("Caught exception:")) {
                          	new AlertDialog.Builder(JEExample.this).
                      	        setTitle("Get Data").setMessage(result).
                      	        setPositiveButton("Quit", new DialogInterface.OnClickListener() {
                      		        public void onClick(DialogInterface dialog, int whichButton) {
                      		        }
                      		    }).show();
                          } else {
                          	new AlertDialog.Builder(JEExample.this).
                      	        setTitle("Get Data").setMessage("Get result: " + result).
                      	        setPositiveButton("Confirm", new DialogInterface.OnClickListener() {
                      		        public void onClick(DialogInterface dialog, int whichButton) {
                      		        }
                      		    }).show();
                          }
                      }
                  });
              } catch (Exception DE) {
                  TextView tv = new TextView(this);
                  tv.setText("blew chunks " + DE);
                  setContentView(tv);
              }
          }
      }

- res/layout/main.xml

      <?xml version="1.0" encoding="utf-8"?>
      <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
          android:orientation="vertical"
          android:layout_width="fill_parent"
          android:layout_height="fill_parent"
          >

        <TextView android:id="@+id/label"
          android:layout_width="fill_parent"
          android:layout_height="wrap_content"
          android:text="JEExample"
          />

        <EditText android:id="@+id/entry"
                  android:layout_width="fill_parent"
                  android:layout_height="wrap_content"
                  android:background="@android:drawable/editbox_background"
                  android:layout_below="@id/label"
          />

        <Button android:id="@+id/do_put"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:text="@string/button_put"
          />

        <Button android:id="@+id/do_get"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:text="@string/button_get"
          />
      </LinearLayout>

- res/values/strings.xml

      <?xml version="1.0" encoding="utf-8"?>
      <resources>
          <string name="app_name">JEExample</string>
          <string name="button_put">Put Data</string>
          <string name="button_get">Get Data</string>
      </resources>

Please report bugs to the Berkeley DB Java Edition OTN forum.