Berkeley DB Java Edition
Installation Notes

3.2.76, April 09, 2008

These installation notes describe:

• Installing JE
• Using JE
• Uninstalling JE
• Building and running JE examples
• Basic Examples
• Collections Example
• Getting Started Examples
• Writing Transactional Applications Examples
• Building JE
• Building with the Unit Tests
• Build Options
• Using JE with J2EE/JCA
• Using JE with JMX

Installing JE

JE requires J2SE JDK version 1.4.2 or later. You can download this from:

J2SE 1.4.2

JE may also be used with BEA's JRockit JVM. Version 1.4.1_01-b01 has been tested. Note that you must pass -Xmx parameter to JRockit when using JE.

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

Uninstalling JE

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

Examples

The JE distribution comes with examples that illustrate the basic database engine, the collections API, and scenarios from the Getting Started Guide and Transactional Applications Guide.

Building and Running the Basic Examples

• SimpleExample does basic data insertion and retrieval.
• BindingExample shows how to use com.sleepycat.bind to convert between Java objects and JE data records.
• SecondaryExample illustrates the use of secondary indices.
• SequenceExample demonstrates the use of Sequence objects.
• ToManyExample shows how to use multi-key secondary indices to support many-many and one-many primary/secondary key relationships.

These examples can also serve as a sanity check of the installation. You can find the source for these examples at:

JE_HOME/examples/je

Assuming you have installed the J2SE JDK and have verified that you have a working Java compiler, you can build SimpleExample as follows.

1. Change to the

   JE_HOME/examples

   directory.


2. Set your CLASSPATH to include both

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

   and the

   JE_HOME/examples

   directory.


3. Compile SimpleExample.java with the following command:

   javac je/SimpleExample.java

   or on Windows:

   javac je\SimpleExample.java

SimpleExample can either add records to or retrieve records from a database. To insert records into a database, use the following command, specifying an environment directory for the data generated by the example:

java je.SimpleExample <environment directory> insert 10 0

This command above inserted 10 records starting with key "0". To insert more records, specify a count and a key value starting point. For example:

java je.SimpleExample <environment directory> insert 10 10

java je.SimpleExample <environment directory> retrieve

Running the Java Collections Examples

The collections examples can be compiled in the same way as is described for SimpleExample above. However, by default these collections examples use "./tmp" as the environment home directory. You should create the tmp directory before running the example. To compile and run the HelloDatabaseWorld example:

javac collections/hello/HelloDatabaseWorld.java

java collections.hello.HelloDatabaseWorld

Writing data
Reading data
0 Hello
1 Database
2 World

A series of examples based on a shipment database can be found in the examples/collections/ship directory. Each of these examples is compiled and run in the same way. They build on each other to illustrate the use of different types of object-to-database bindings.

• basic - The shipment program.
• index - Secondary indices.
• entity - Combining the key and value in a single object.
• tuple - Compact ordered keys.
• sentity - (Serializable Entity) One serializable class for entities and values.
• marshal - Internal bindings in the key and value classes.
• factory - The marshaled tuple-serial factory.

javac collections/ship/basic/Sample.java

java collections.ship.basic.Sample

The other shipment examples are compiled and run in the same way. However, all shipment examples use the same database name, and therefore the database must be cleared in between running different examples. Clear the database by deleting the contents of the "./tmp" directory.

Running the Getting Started Examples

As described in the Berkeley DB Java Edition Getting Started Guide, the final examples in every chapter exist in the JE package. You can build and run these examples as follows:

• Change to the

  JE_HOME/examples

  directory.


• Set your CLASSPATH to include both

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

  and the

  JE_HOME/examples

  directories.


• Compile the Getting Started examples with the following commands:

  javac je/gettingStarted/*.java

  or on Windows:

  javac je\gettingStarted\*.java

• Make a directory to contain your database environment:

  mkdir gsgEnv

• Load your sample database:

  java je.gettingStarted.ExampleDatabasePut -h gsgEnv -i je/gettingStarted/inventory.txt  -v je/gettingStarted/vendors.txt

• Perform queries against your database. To see everything in the database, use:

  java je.gettingStarted.ExampleInventoryRead -h gsgEnv

  To perform a query based on an inventory item's name, use:

  java je.gettingStarted.ExampleInventoryRead -h gsgEnv -s Upo

Running the Writing Transactional Applications Examples

The examples in Writing Transactional Applications with Berkeley DB, Java Edition guide, the exist in the JE package. You can build and run these examples as follows:

• Change to the

  JE_HOME/examples

  directory.


• Set your CLASSPATH to include both

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

  and the

  JE_HOME/examples

  directories.


• Compile the Transactional Applications examples with the following commands:

  javac je/txn/*.java

  or on Windows:

  javac je\txn\*.java

• Make a directory to contain your database environment:

  mkdir txnEx

• Run the transactional example.

  java je.txn.TxnGuide -h txnEx

Building JE

JE must be built with Java 1.5, but will produce a .jar file compatible with both Java 1.4 and Java 1.5. To build JE from the provided source, you need to download and install ant 1.6.0 or later and JUnit:

Apache Ant

See the next section for downloading JUnit. Once ant and JUnit are installed, you can build JE using the following command:

cd JE_HOME

ant clean jar

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.

If you are running the unit tests with JRockit, the DatabaseConfigTest.testComparator() test will fail with a NullPointerException. This is due to a known problem in JRockit that has been fixed in JRockit version 1.4.2_04 and later. You will also need to pass a -Xmx value to JRockit. In the build.xml, uncomment the -Xmx256M "jvmarg".

Build Options

You can use the following build options when building JE:

   /usr/lib/JE.<major>.<minor>

  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 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-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 support for adding JE monitoring to an application's custom MBean. See JE_HOME/examples/jmx/README.txt.

Copyright 1996,2008 Oracle. All rights reserved.