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

3.3.62, June 04, 2008

Overview

This release of JE has some changes to allow using it under the Google Android platform. Although extensive tests have not been run, we feel comfortable putting the release out with a "Beta" label on it in order to get feedback. 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.

Detailed Instructions

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.

Create a work directory (referred to as <work-dir> in this document).

Unpack the JE distribution into that directory. If you've already unpacked JE into another location, you can move that directory into the <work-dir> but note that the next step is to remove some files, so your distribution will be missing some files found in the original distribution. In the following text, the "je" directory refers to the je-M.N.P directory, where M, N, and P are the release major, minor, and patch versions.

Remove the <work-dir>/je/examples, <work-dir>/je/src/com/sleepycat/je/jca, <work-dir>/je/src/com/sleepycat/je/jmx, and <work-dir>/je/test directories. This step is necessary because Android will attempt to compile all .java files in the <work-dir>.

Do mkdir -p <work-dir>/je/src/javax/transaction/xa.

Copy the following stubs into the <work-dir>/je/src/javax/transaction/xa directory. JE requires these three J2SE classes for compilation but they are not present in the Android platform.



XAException.java

package javax.transaction.xa;

public class XAException extends Exception {

    public static final int XA_RBBASE = 0;
    public static final int XA_RBROLLBACK = 0;
    public static final int XAER_INVAL = 0;
    public static final int XAER_NOTA = 0;
    public static final int XAER_DUPID = 0;
    public static final int XA_RBPROTO = 0;
    public static final int XAER_PROTO = 0;
    public XAException() {}
    public XAException(String s) {}
    public XAException(int e) {}
}

XAResource.java

package javax.transaction.xa;

public interface XAResource {
    public static final int TMENDRSCAN = 0;
    public static final int TMFAIL = 0;
    public static final int TMJOIN = 0;
    public static final int TMNOFLAGS = 0;
    public static final int TMONEPHASE = 0;
    public static final int TMRESUME = 0;
    public static final int TMSTARTRSCAN = 0;
    public static final int TMSUCCESS = 0;
    public static final int TMSUSPEND = 0;
    public static final int XA_RDONLY = 0;
    public static final int XA_OK = 0;
    boolean setTransactionTimeout(int a)
        throws XAException;
    void start(Xid a, int b)
        throws XAException;
    void end(Xid a, int b)
        throws XAException;
    int prepare(Xid a)
        throws XAException;
    void commit(Xid a, boolean b)
        throws XAException;
    void forget(Xid a)
        throws XAException;
    Xid[] recover(int a)
        throws XAException;
    void rollback(Xid a)
        throws XAException;
    int getTransactionTimeout()
        throws XAException;
    boolean isSameRM(XAResource a)
        throws XAException;
}

Xid.java

package javax.transaction.xa;

public interface Xid {
    int getFormatId();
    byte[] getGlobalTransactionId();
    byte[] getBranchQualifier();
}

Review <android-home>/docs/intro/hello-android.html for instructions on how to create a project. Do

activityCreator --out <work-dir> com.sleepycat.je.JEExample

This creates <work-dir>/src/com/sleepycat/je/JEExample.java

Replace the generated contents of <work-dir>/src/com/sleepycat/je/JEExample.java with the following code:


package com.sleepycat.je;

import android.app.Activity;
import android.app.NotificationManager;
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.R;
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/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);

            final NotificationManager nm = (NotificationManager)
                getSystemService(NOTIFICATION_SERVICE);

	    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);

                        nm.notifyWithText
                            (R.id.do_put, result,
                             NotificationManager.LENGTH_LONG, null);
		    }
		});

	    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);

                        nm.notifyWithText
                            (R.id.do_get, result,
                             NotificationManager.LENGTH_SHORT, null);
		    }
		});

	} catch (Exception DE) {
	    TextView tv = new TextView(this);
	    tv.setText("blew chunks " + DE);
	    setContentView(tv);
	}
    }
}

Replace the generated contents of <work-dir>/res/layout/main.xml with the following 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 id="@+id/label"
    android:layout_width="fill_parent" 
    android:layout_height="wrap_content" 
    android:text="JEExample"
    />

  <EditText 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 id="@+id/do_put"
          android:layout_width="wrap_content"
          android:layout_height="wrap_content"
          android:text="@string/button_put"
    />

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

Replace the generated contents of <work-dir>/res/value/strings.xml with the following 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>

In <work-dir>, do

ant

This should build JE and JEExample.java as well as convert the resulting class files to dex files. This also creates

<work-dir>/bin/JEExample.apk

Run the Android emulator.

Install the JEExample application.

adb install bin/JEExample.apk

Run the JEExample application in the emulator by clicking on the Home icon, then the Applications folder, then the 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.

You can remove the JE Environment files by doing

adb shell rm /data/je/*

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

A Simple HOWTO for Using Berkeley DB Java Editionon theAndroid Platform

Overview

Detailed Instructions

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