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

4.1.21, June 07, 2012

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.