1.2 Project Build Environment

In this section, we examine a development environment to compile and run our JDO application. This includes the project directory structure, the jar files necessary to build applications, and the syntax for enhancing persistent classes. We describe class enhancement later in this section. The environment setup partly depends on which JDO implementation you use. Your specific project's development environment and directory structure may differ.

You can use either the Sun JDO reference implementation or another implementation of your choosing. The examples in this book use the JDO reference implementation. You can download the JDO reference implementation by visiting http://www.jcp.org and selecting JSR-12. Once you have installed a JDO implementation, you will need to establish a project directory structure and define a classpath that includes all the directories and jar files necessary to build and run your application.

JDO introduces a new step in your build process, called class enhancement. Each persistent class must be enhanced so that it can be used in a JDO runtime environment. Your persistent classes are compiled using a Java compiler that produces a class file. An enhancer program reads these class files and JDO metadata and creates new class files that have been enhanced to operate in a JDO environment. Your JDO application should load these enhanced class files. The JDO reference implementation includes an enhancer called the reference enhancer.

1.2.1 Jars Needed to Use the JDO Reference Implementation

When using the JDO reference implementation, you should include the following jar files in your classpath during development. At runtime, all of these jar files should be in your classpath.

jdo.jar: The standard interfaces and classes defined in the JDO specification.
jdori.jar: Sun's reference implementation of the JDO specification.
btree.jar: Software used by the JDO reference implementation to manage the storage of data in a file. The reference implementation uses a file for the storage of persistent instances.
jta.jar: The Java Transaction API. The Synchronization interface defined in package javax.transaction is used in the JDO interface and contained in this jar file. Other facilities defined in this file are likely to be useful to a JDO implementation. You can download this jar from http://java.sun.com/products/jta/index.html.
antlr.jar: Parsing technology used in the implementation of the JDO query language. The reference implementation uses Version 2.7.0 of Antlr. You can download it from http://www.antlr.org.
xerces.jar: The reference implementation uses Xerces-J Release 1.4.3 to parse XML. It can be downloaded from http://xml.apache.org/xerces-j/.

The first three jar files are included with the JDO reference implementation; the last three can be downloaded from the specified web sites.

The reference implementation includes an additional jar, jdori-enhancer.jar, that contains the reference enhancer implementation. The classes in jdori-enhancer.jar are also in jdori.jar. In most cases, you will use jdori.jar in both your development and runtime environment, and not need jdori-enhancer.jar. The jdori-enhancer.jar is packaged separately so that you can enhance your classes using the reference enhancer independent of a particular JDO implementation. Some implementations, besides the reference implementation, may distribute this jar for use with their implementation.

If you use a different JDO implementation, its documentation should provide you with a list of all the necessary jars. An implementation usually places all the necessary jars in a particular directory in their installation. The jdo.jar file containing the interfaces defined in JDO should be used with all implementations. This jar file is usually included with a vendor's implementation. JDOcentral.com (http://www.jdocentral.com) provides numerous JDO resources, including free trial downloads of many commercial JDO implementations.

1.2.2 Project Directory Structure

You should use the following directory structure for the Media Mania application development environment. The project must have a root directory placed somewhere in the filesystem. The following directories reside beneath the project's root directory:

src: This directory contains all of the application's source code. Under src, there is a subdirectory hierarchy of com/mediamania/prototype (corresponding to the Java com.mediamania.prototype package). This is where the Movie.java, Actor.java, and Role.java source files reside.
classes: When the Java source files are compiled, their class files are placed in this directory.
enhanced: This is the directory that contains the enhanced class files (produced by the enhancer).
database: This directory contains the files used by the reference implementation to store our persistent data.

Though this particular directory structure is not a requirement of JDO or the reference implementation, you need to understand it to follow our description of the Media Mania application.

When you execute your JDO application, the Java runtime must load the enhanced version of the class files, which are located in our enhanced directory. Therefore, the enhanced directory should be listed prior to the classes directory in your classpath. As an alternative approach, you can also enhance in-place, replacing your unenhanced class file with their enhanced form.

1.2.3 Enhancing Classes for Persistence

A class must be enhanced before its instances can be managed in a JDO environment. A JDO enhancer adds data and methods to your classes that enable their instances to be managed by a JDO implementation. An enhancer reads a class file produced by the Java compiler and, using the JDO metadata, produces a new, enhanced class file that includes the necessary functionality. JDO has standardized the modifications made by enhancers so that enhanced class files are binary-compatible and can be used with any JDO implementation. These enhanced files are also independent of any specific datastore.

As mentioned previously, the enhancer provided with Sun's JDO reference implementation is called the reference enhancer. A JDO vendor may provide its own enhancer; the command-line syntax necessary to execute an enhancer may differ from the syntax shown here. Each implementation should provide you with documentation explaining how to enhance your classes for use with their implementation.

Example 1-5 provides the reference enhancer command for enhancing the persistent classes in our Media Mania application. The -d argument specifies the root directory in which to place the enhanced class files; we have specified our enhanced directory. The enhancer is given a list of JDO metadata files and a set of class files to enhance. The directory separator and line-continuation symbols may vary, depending on your operating system and build environment.

Example 1-5. Enhancing the persistent classes

java com.sun.jdori.enhancer.Main -d enhanced  \
      classes/com/mediamania/prototype/package.jdo  \
      classes/com/mediamania/prototype/Movie.class  \
      classes/com/mediamania/prototype/Actor.class  \
      classes/com/mediamania/prototype/Role.class

Though it is convenient to place the metadata files in the directory with the source code, the JDO specification recommends that the metadata files be available via resources loaded by the same class loader as the class files. The metadata is needed at both build and runtime. So, we have placed the package.jdo metadata file under the classes directory hierarchy in the directory for the prototype package.

The class files for all persistent classes in our object model are listed together in Example 1-5, but you can also enhance each class individually. When this command executes, it places new, enhanced class files in the enhanced directory.