5.0.58, July 17, 2012
These installation notes describe:
JE requires Java SE version 1.5.0_10 or later. You can download the latest Java SE from:
http://www.oracle.com/technetwork/java/javase/downloads/index.html
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-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.
For using JE with Android, see the Android HOWTO.
To uninstall, just remove the directory that you unzipped into.
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 from the Apache Ant download site and JUnit from JUnit/SourceForge. Note that the JE test suite works with JUnit 3.8.1 (at the previous link), but not with JUnit 4.0 or later.
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".
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.
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 the JE jar file in build/lib/je-M.N.P.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 |
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.
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) 2002-2010 Oracle. All rights reserved.