# Berkeley DB Java Edition
Installation Notes

4.0.103, April 28, 2010

These installation notes describe:

- Installing JE
- Using JE
- Uninstalling JE
- Building JE

- Building with the Unit Tests
- Build Options

- Using JE with J2EE/JCA
- Using JE with JMX

## Installing JE

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

> http://java.sun.com/javase/downloads/index.jsp

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.