12.2 Enhancement

The JDO specification requires every persistent business object to implement the PersistenceCapable interface. Though this seems to contradict what I have been saying about transparency, it does not. JDO leverages a concept called enhancement to enable your business objects to implement PersistenceCapable after the fact.

Before deployment of a JDO application, you use a tool on your compiled Java classes to change their bytecode. Your JDO vendor generally supplies the enhancement tool. No matter what enhancement tool you use, the JDO specification requires that all vendors be able to support the reference JDO contract for enhancement. In other words, you can enhance with Vendor A's tools and deploy in an environment using a JDO implementation from Vendor B.

In truth, bytecode enhancement is not a required aspect of JDO. Your vendor, for example, can provide tools to modify the source code. What is essential to JDO is:

• You are not required to code your business objects to any particular specification dictated by JDO.^[1]

  ^[1] If you intend to use JDO to support a bean-managed EJB, you need to conform to the EJB specification.

• Any bytecode that exists after enhancement can run against any JDO implementation.

12.2.1 Class Metadata

For enhancement to work, you need to tell your enhancement tool about the business object to be made persistent. You accomplish this task through the creation of an XML file that describes the business object class. Example 12-3 is the metadata description for the Book class.

Example 12-3. The Book metadata

<?xml version="1.0" ?>
<!DOCTYPE jdo SYSTEM "jdo.dtd">
   
<jdo>
  <package name="com.imaginary.ora">
    <class name="Book">
      <field name="author"/>
      <field name="isbn"/>
      <field name="title"/>
    </class>
  </package>
</jdo>

This file enables you to identify all persistent business objects and their persistent fields. This example shows only the most basic metadata description. We can make it more complex by pulling in some design elements from previous chapters.

<class name="Book">
  <field name="bookID" primary-key="true"/>
  <field name="author"/>
  <field name="isbn"/>
  <field name="title"/>
</class>

This code adds a persistent field for bookID—a field that happens to be a unique value across all Book instances. We can also add an Author class that has a collection of books:

<class name="Author">
  <field name="authorID" primary-key="true"/>
  <field name="books">
    <collection element-type="com.imaginary.ora.Book"/>
  </field>
  <field name="firstName"/>
  <field name="lastName"/>
</class>

This sample code shows how you can specify a persistent field that is a collection. In this case, it happens to be a collection of other persistent objects.

12.2.2 Running the Enhancer

Once you have written metadata files to describe each persistent object, you run the enhancer on it. The exact syntax of the enhancer depends greatly on what JDO implementation you are using. To run the reference implementation's enhancer, you execute the following command line:

Prompt$ java -classpath jdo.jar;jdori.jar;xerces.jar  options  com.sun.jdori.enhancer.
Main   classes and metadata 

12.2.3 The Database

At some point, you need to create the tables in your database to support your persistent objects. In general, the JDO vendor you are using will provide tools that reuse the metadata for your objects to build relational tables. The JDO specification, however, says nothing about how a relational structure should be created.