Oracle

Berkeley DB Java Edition
Installation Notes

4.1.21, June 07, 2012

These installation notes describe:

Installing JE

JE requires Java SE version 1.5.0_10 or later. You can download the latest Java SE from:

http://www.oracle.com/technetwork/java/javase/downloads/index.html

To install JE, use unzip or tar to unpack the JE distribution. If you are using unzip, be sure to use the -U option to preserve case in file names. For example:

unzip -U je-M.N.P.zip

or

gunzip je-M.N.P.tar.gz
tar xvf je-M.N.P.tar

Unpacking the distribution creates a je-M.N.P directory on disk, where M.N.P is the release's version number. This directory contains the following contents:

bin/
docs/
examples/
lib/
src/
test/

The remainder of this document refers to the je-M.N.P/ directory created in this step as JE_HOME.

Using JE

To compile and run a program using JE, you only need the je-M.N.P.jar file in your class path. This file can be found at:

JE_HOME/lib/je-M.N.P.jar

When using JE within a web container, note that it is important that the JE jar file and your application jar files -- in particular the classes that are being serialized by SerialBinding -- are loaded under the same class loader. For running in a servlet, this typically means that you would place the JE jar file and your application jars in the same directory.

Additionally, it is important to not place the JE jar file in the extensions directory for your JVM. Instead place the JE jar file in the same location as your application jars. The extensions directory is reserved for privileged library code.

Compiling and running a simple example can serve as a sanity check of the installation. Follow these instructions to compile and run the first basic example, called PersonExample.

For using JE with Android, see the Android HOWTO.

Uninstalling JE

To uninstall, just remove the directory that you unzipped into.

Building JE

JE must be built with Java 1.5.0_10 or later. To build JE from the provided source, you need to download and install Ant 1.7.0 or later from the Apache Ant download site and JUnit from JUnit/SourceForge

Once ant and JUnit are installed, you can build JE using the following command:

cd JE_HOME
ant clean jar

The JE jar file will appear in JE_HOME/build/lib/je-M.N.P.jar.

By default, JE is compiled with both -O for optimization and -g for debug symbols. Compiling without the -g will give you the smallest possible JE jar file. To do so, edit the JE_HOME/ant/compile.xml file and change the build.debug property from "on" to "off".

Building and Running the Unit Tests

If you want to build and run the included unit tests, you must download JUnit:

JUnit/SourceForge

Once JUnit is installed on your system, you must make sure that ant knows about it. The simplest way to do this is to copy the junit.jar file into your ant's lib dir. You then must build JE as follows:

cd JE_HOME
ant clean compile

Once it is compiled, you can run the unit tests using the command: "ant test". The unit tests usually take between 20 to 50 minutes to run, depending on platform. On some platforms, notably Windows, you may see OutOfMemoryErrors while running the unit tests. To avoid this, increase the JVM maximum memory size by setting the ANT_OPTS environment variable so that it includes -Xmx256M.

Build Options

You can use the following build options when building JE:

Option Description
clean Removes any previously built classes and jar files.
compile Compiles JE and the included unit tests. This requires JUnit be downloaded and installed on your system. See Building and Running the Unit Tests for more information.
compile-src Compiles JE. The unit tests are not compiled.
jar
Creates the JE jar file in build/lib/je-M.N.P.jar.
test Runs unit tests.
install Unix systems only. Causes the JE bin, lib, and docs directories to be installed to:
   /usr/lib/JE.<major>.<minor>
where <major> is the JE major release number, and <minor> is the JE minor release number.

If you do not want JE installed into /usr/lib, then you can change the base installation directory using -Dinstalldir. For example:
  ant install -Dinstalldir=/usr/local

Using JE with J2EE/JCA

JE can be used as a J2EE/JCA Resource Adapter. It has been tested with Oracle Application Server (OC4J) 10.1.3.2.0, JBoss 3.2.6 and Sun Java System Application Server 8.1. For cookbook style "HOWTO's" using the JE J2EE/JCA Resource Adapter see JE_HOME/examples/jca/HOWTO-oc4j.txt, JE_HOME/examples/jca/HOWTO-jboss.txt and JE_HOME/examples/jca/HOWTO-sjsas.txt.

Using JE with JMX

JE supplies a ready to install JMX (Java Management Extensions) MBean as well as a JConsole plugin for viewing the mbean. See the JConsole README

Copyright (c) 2002-2010 Oracle. All rights reserved.