Chapter 4. PersistenceCapable

4.1. Enhancer
4.2. Persistence-Capable vs. Persistence-Aware
4.3. Restrictions on Persistent Classes
4.3.1. Default or No-Arg Constructor
4.3.2. Inheritance
4.3.3. Persistent Fields
4.3.4. Conclusions
4.4. Lifecycle Callbacks
4.4.1. InstanceCallbacks
4.4.2. InstanceLifecycleListener
4.5. JDO Identity
4.5.1. Datastore Identity
4.5.2. Application Identity Application Identity Hierarchies
4.5.3. Single Field Identity
4.6. Conclusions

In most JDO implementations, user-defined persistent classes implement a special PersistenceCapable interface. This interface contains many complex methods that enable the JDO implementation to manage the persistent fields of class instances. Fortunately, you do not have to implement this interface yourself. In fact, writing a persistent class in JDO is usually no different than writing any other class. There are no special parent classes to extend from, field types to use, or methods to write. This is one important way in which JDO makes persistence completely transparent to you, the developer.

Example 4.1. PersistenceCapable Class

package org.mag;

 * Example persistent class.  Notice that it looks exactly like any other
 * class.  JDO makes writing persistent classes completely transparent.
public class Magazine
    private String    isbn;
    private String    title;
    private Set       articles = new HashSet ();
    private Article   coverArticle;
    private int       copiesSold;
    private double    price;
    private Company   publisher;

    private Magazine ()

    public Magazine (String title, String isbn)
        this.title = title;
        this.isbn = isbn;

    public void publish (Company publisher, double price)
        this.publisher = publisher;
        publisher.addMagazine (this);
        this.price = price;
    public void sell ()
        publisher.addRevenue (price);

    public void addArticle (Article article)
        articles.add (article);

    // rest of methods omitted

4.1. Enhancer

In order to shield you from the intricacies of the PersistenceCapable interface, JDO implementations typically provide an enhancer. An enhancer is a tool that automatically adds code to your persistent classes after you have written them. Though some vendors may use source enhancers that modify your Java code, enhancers generally operate on .class files. They post-process the bytecode generated by your Java compiler, adding the necessary fields and methods to implement the expected interface. This bytecode modification perfectly preserves the line numbers in stack traces and is compatible with Java debuggers, so enhancement does not affect debugging.

The diagram above illustrates the compilation of a persistent class. JDO implementations typically include an Ant task so that you can make enhancement an automatic part of your build process. Some JDO implementations may also use custom class loaders or Java 5's class loading hooks to perform enhancement transparently at runtime, rather than adding a step to the build process.


Kodo uses bytecode, rather than source code, enhancement. Kodo offers both a compile-time enhancer tool and a runtime enhancement option for Java 5 users. See Section 5.2, “Enhancement” of the Reference Guide.


Skip navigation bar   Back to Top