Berkeley DB Java Edition Installation Notes

# Berkeley DB Java Edition
Installation Notes

6.2.31, 2014-12-17 02:32:26 UTC

These installation notes describe:

- Installing JE
- Using JE
- Uninstalling JE
- Building JE
- Building with the Unit Tests
- Using JE with J2EE/JCA
- Using JE with JMX

## Installing JE

The release notes document the Java versions that JE is compatible with and that have been used for certification.

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:

>     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.

## Uninstalling JE

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

## Building JE

You need Apache Ant version 1.8.0 or later in order to do builds. You can download Ant from:

> http://ant.apache.org/

You also need Apache Ivy for loading dependencies. You can download Ivy from:

> http://ant.apache.org/ivy/

Make sure to add the ivy JAR file to your `~/.ant/lib` directory or specify the ivy directory using the ant `-lib` option.

JE must be built with the version of Java specified as the compatibility requirement in the release notes.

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.jar.

## Building and Running the Unit Tests

You can run the unit tests using the command: `"ant test"`.

The ant 'test' target will automatically download a junit jar into the extlib directory, and this jar is needed for compiling the tests. If this command hangs when attempting to download the jar, due to a VPN for example, you may need to additionally specify an HTTP proxy host and/or port. This can be specified using the proxy.host and proxy.port properties, for example: `"ant test -Dproxy.host=my.proxy"`. By default, proxy.port is 80.

On 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`.

## 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) 1996, 2014 Oracle and/or its affiliates. All rights reserved.