2.0.90, October 25, 2005
These installation notes describe:
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.
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:
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.JE_HOME/lib/je.jar
To uninstall, just remove the directory that you unzipped into.
The JE distribution comes with examples that illustrate the basic database engine, the collections API, and scenarios from the Getting Started Guide.
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/je
Assuming you have installed the J2SE JDK and have verified that you
have a
working Java compiler, you can build SimpleExample
as
follows.
JE_HOME/examplesdirectory.
JE_HOME/lib/je.jarand the
JE_HOME/examplesdirectory.
SimpleExample.java
with the following
command:
javac je/SimpleExample.javaor 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:
For example, usingjava je.SimpleExample <environment directory> insert 10 0
"."
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:
and so on. To retrieve and print all records:java je.SimpleExample <environment directory> insert 10 10
While this is not a very entertaining program, it is enough to test that you have installed JE correctly.java je.SimpleExample <environment directory> retrieve
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.
com.sleepycat.je
classes directly, or indirectly using the
standard Java Collections API. A number of examples in the
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:
The first time this example is run it will print:javac collections/hello/HelloDatabaseWorld.javajava collections.hello.HelloDatabaseWorld
If run again, it will not printWriting data
Reading data
0 Hello
1 Database
2 World
"Writing data"
since the
data will
already exist.
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."./tmp"
so that
directory must exist prior to running the example. To compile and run
the
basic
example:
The sample will add shipment records to the database and print their contents.javac collections/ship/basic/Sample.javajava 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.
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:
JE_HOME/examplesdirectory.
JE_HOME/lib/je.jarand the
JE_HOME/examplesdirectories.
javac je/gettingStarted/*.javaor on Windows:
javac je\gettingStarted\*.java
mkdir gsgEnv
java je.gettingStarted.ExampleDatabasePut -h gsgEnv -i je/gettingStarted/inventory.txt -v je/gettingStarted/vendors.txt
java je.gettingStarted.ExampleInventoryRead -h gsgEnvTo perform a query based on an inventory item's name, use:
java je.gettingStarted.ExampleInventoryRead -h gsgEnv -s Upo
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:
The je.jar file will appear in JE_HOME/build/lib/je.jar.cd JE_HOMEant clean jar
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_HOMEant 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".
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.
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
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.