Berkeley DB Java Edition
Installation Notes

3.3.82, May 07, 2009

These installation notes describe:

• Installing JE
• Using JE
• Uninstalling JE
• Building and running JE examples
• Basic Example
• Getting Started Examples
• Writing Transactional Applications Examples
• Translating SQL Queries
• 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.5.0_10 or later. You can download the latest J2SE 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.

For using JE with Android, see the Android HOWTO.

Uninstalling JE

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

Examples

The JE distribution comes with examples that illustrate:

• using the JE programming interfaces to perform basic database operations
• scenarios from the Getting Started Guide and Writing Transactional Applications
• using the Direct Persistence Layer to implement common SQL queries

The complete list of examples follows.

Building and Running a Basic Example

Compiling and running a simple example can serve as a sanity check of the installation. Follow the instructions below to compile and run the PersonExample.

You can find the source for this example at:

JE_HOME/examples/persist/PersonExample.java

Assuming you have installed the J2SE JDK and have verified that you have a working Java compiler, you can build PersonExample 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 PersonExample.java with the following command:

   javac persist/PersonExample.java

   or on Windows:

   javac persist\PersonExample.java

To run PersonExample , use the following command, specifying an environment directory for the data generated by the example:

java persist.PersonExample -h <environment directory>

For example, using "." for the second parameter will write the database files into the current directory. You'll notice that a 00000000.jdb file and and je.lck file are created. This is the first log file in the environment and a lock file. If you need to delete the environment for running a different example, simply delete these two files.

When you run the program you'll see the following output. While this is not a very entertaining program, it is enough to test that you have installed JE correctly.

222-22-2222 Jack Smith
333-33-3333 Mary Smith

The other JE examples are compiled and run similarly. How to the run examples from the Getting Started Guide and Writing Transactional Applications is described in the sections below, as well as how to run the Translating SQL Queries examples. Instructions for running other examples are contained in the example's source file.

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

Running the Translating SQL Query Examples

This example shows how some common SQL queries can be implemented using the Direct Persistence Layer. It's meant to help users who are more familiar with SQL translate those approaches to the DPL. These queries include:

Basic data retrieval:

SELECT * FROM tab ORDER BY col ASC;

A prefix query:

SELECT * FROM tab WHERE col LIKE 'prefix%';

A range query, where the data type of A (as well as B) may be an int, a float, a String, etc:

SELECT * FROM tab WHERE col gt;= A AND col <= B;

An equi-join on a single primary database:

SELECT * FROM tab WHERE col1 = A AND col2 =B;

An equi-join on two primary databases combined with a filtering on "t2.col2". Note that if "t2.col2" is a secondary key, the filtering does a index lookup. Otherwise the filtering is done through database scanning:

SELECT t1.* FROM table1 t1, table2 t2 WHERE t1.col1 = t2.col1 AND t2.col2 = A;

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 SQL query examples with the following commands:

  javac persist/sqlapp/*.java

  or on Windows:

  javac persist\sqlapp\*.java

• Make a directory to contain your database environment:

  mkdir sqlEnv

• Run the SQL query examples:

  java persist.sqlapp.SQLApp -h sqlEnv

  To delete database files after the example exits, do:

  java persist.sqlapp.SQLApp -h sqlEnv -d

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

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:

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

Copyright (c) 2002,2009 Oracle. All rights reserved.