# Berkeley DB Java Edition
Installation Notes

1.7.1, February 18, 2005

These installation notes describe:

- Installing JE
- Using JE
- Uninstalling JE
- Building and running JE examples

- Basic Examples
- Collections Example
- Getting Started Examples

- Building JE

- Building with the Unit Tests
- Build Options

## 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.jar` file in your class path. This file can be found at:

>     JE_HOME/lib/je.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 je.jar 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 je.jar in the same location as your application jars. The extensions directory is reserved for privileged library code.

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

### Building and Running SimpleExample and BindingExample

`SimpleExample` and `BindingExample` programs do basic data insertion and retrieval. SimpleExample illustrates the base DatabaseEntry api while BindingExample shows the use of the object to DatabaseEntry mapping support. These examples can also serve as a sanity check of the installation. You can find the source for these examples at:

>     JE_HOME/examples/com/sleepycat/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.jar

   and the

       JE_HOME/examples

   directory.
3. Compile `SimpleExample.java` with the following command:

       javac com/sleepycat/examples/je/SimpleExample.java

   or on Windows:

       javac com\sleepycat\examples\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 com.sleepycat.examples.je.SimpleExample <environment directory> insert 10 0

For example, using `"."` for the first 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.

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 com.sleepycat.examples.je.SimpleExample <environment directory> insert 10 10

and so on. To retrieve and print all records:

>     java com.sleepycat.examples.je.SimpleExample <environment directory> retrieve

While this is not a very entertaining program, it is enough to test that you have installed JE correctly. `BindingExample` in the same directory is a similar example that shows how to use the Java object-to-database record support supplied in the `com.sleepycat.bind` package. `SecondaryExample` in the same directory shows how to use secondary indices.

### Running the Java Collections Examples

Accessing data in a JE database may be performed using the `com.sleepycat.je` classes directly, or indirectly using the standard Java Collections API. A number of examples in the `examples/com/sleepycat/examples/collections` directory show how to use Java collections with JE.

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 com/sleepycat/examples/collections/helloworld/HelloDatabaseWorld.java

>     java com.sleepycat.examples.collections.helloworld.HelloDatabaseWorld

The first time this example is run it will print:

>     Writing data
>     Reading data
>     0 Hello
>     1 Database
>     2 World

If run again, it will not print `"Writing data"` since the data will already exist.

A series of examples based on a shipment database can be found in the `examples/com/sleepycat/examples/collections/shipment` 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.

As with the prior example, the home directory is `"./tmp"` so that directory must exist prior to running the example. To compile and run the `basic` example:

>     javac com/sleepycat/examples/collections/shipment/basic/Sample.java

>     java com.sleepycat.examples.collections.shipment.basic.Sample

The sample will add shipment records to the database and print their contents.

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

  and the

      JE_HOME/examples

  directories.
- Compile the Getting Started examples with the following commands:

      javac com/sleepycat/examples/je/gettingStarted/*.java

  or on Windows:

      javac com\sleepycat\examples\je\gettingStarted\*.java

- Make a directory to contain your database environment:

      mkdir gsgEnv

- Load your sample database:

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

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

      java com.sleepycat.examples.je.gettingStarted.ExampleInventoryRead -h gsgEnv

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

      java com.sleepycat.examples.je.gettingStarted.ExampleInventoryRead -h gsgEnv -s Upo

## Building JE

To build JE from the provided source, you need to download and install ant:

> Apache Ant

Once ant is 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.
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 build.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`.

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:

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 je.jar file in build/lib/je.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

Copyright (c) 1996-2005 Sleepycat Software, Inc. - All rights reserved.