6.1 Enhancement Approaches

You may not be familiar with class enhancement, but it is not JDO-specific and it has been applied in other software technologies. There are several approaches that can be used to enhance a class. Enhancement can be performed by:

Implementing enhancement yourself manually
Using a source-code enhancer
Using a byte-code enhancer

Each enhancement approach requires access to the JDO metadata you have defined.

You may explicitly declare that your class implements PersistenceCapable. In this case, you need to implement the PersistenceCapable contract fully, as specified by the JDO specification. An enhancer ignores a class if you have explicitly declared that it implements PersistenceCapable. We do not recommend this approach; it is tedious and error-prone.

A source-code enhancer reads your original source code and adds the source necessary to support the JDO enhancement contract. The revised source is compiled and is then ready for execution in a JDO environment. At the time this book was written, only one vendor supported a source-code enhancer; the vender also supported a byte-code enhancer.

The most common approach for enhancing a class is to use a JDO byte-code enhancer. It reads a class file produced by the Java compiler and generates a new class file that has been enhanced. With a byte-code enhancer, you can make classes persistent even if you do not have the source code. Figure 6-1 illustrates the process of using a byte-code enhancer to enhance the Movie class.

Figure 6-1. Byte-code enhancement process

All persistent and persistence-aware classes need to be enhanced before they can be used in a JDO runtime environment. They must be enhanced before or during their loading into the JVM at runtime. Some implementations may enhance classes in the class loader itself during the class-loading process. Class enhancement is often performed as an additional step in the build process. Most vendors provide an Ant task you can use to enhance your classes in an Ant build file.

Consult your implementation's documentation to determine which technique they use for class enhancement; this will ensure your classes implement the PersistenceCapable interface. At the time this book was written, most JDO implementations supported a byte-code enhancer, so we assume that you are using one.

6.1.1 Reference Enhancer

The JDO reference implementation, implemented by Sun Microsystems, includes a reference enhancer that enhances class files according to the reference-enhancement contract.

The following command uses the reference enhancer to enhance the persistent classes in the Media Mania object model:

java com.sun.jdori.enhancer.Main -d enhanced -s classes \
     classes/com/mediamania/content/Studio.class \
     classes/com/mediamania/content/MediaContent.class \
     classes/com/mediamania/content/Movie.class \
     classes/com/mediamania/content/Game.class \
     classes/com/mediamania/content/Role.class \
     classes/com/mediamania/content/MediaPerson.class \
     classes/com/mediamania/store/MediaItem.class \
     classes/com/mediamania/store/RentalItem.class \
     classes/com/mediamania/store/RentalCode.class \
     classes/com/mediamania/store/Customer.class \
     classes/com/mediamania/store/Address.class \
     classes/com/mediamania/store/Transaction.class \
     classes/com/mediamania/store/Purchase.class \
     classes/com/mediamania/store/Rental.class

This command places the enhanced class files in a separate directory hierarchy named enhanced. You can also enhance the class files in place, replacing your original class file with the enhanced form by using the -f command option. Another useful option is -v, which produces verbose output indicating the actions performed by the enhancer.

6.1.2 Vendor-Specific Enhancement

A JDO vendor can use Sun's reference enhancer directly with their implementation, or they can implement their own enhancer that performs the same function. A vendor can extend the enhancements required in the reference-enhancement contract by adding their own methods and fields to be used in their runtime environment. However, these additional implementation-specific enhancements cannot conflict with the reference-enhancement contract.

The reference-enhancement contract establishes guidelines for how a vendor can add enhancements, so the enhanced classes are usable with any other JDO implementation's runtime environment. The reference-enhancement contract adds fields and methods whose names begin with "jdo". Any methods and fields added by another vendor's enhancer do not have a name that begins with "jdo"; they begin with some other string that has a vendor-identifying name followed by the string "jdo".