Chapter 6. Class Enhancement

You need to enhance a persistent class before you can use it in a JDO runtime environment. Class enhancement enables the state of a persistent instance in memory to be synchronized with its representation in the datastore. A persistent class must be enhanced so that it implements the javax.jdo.spi.PersistenceCapable interface. The PersistenceCapable interface defines a set of methods that the JDO implementation uses to manage instances.

You also need to enhance every class that directly accesses a managed field of a persistent class. JDO field-mediation code needs to be inserted to ensure proper access and management of the field. If your persistent class has a managed field that is not private, any class that directly accesses the field needs to be enhanced. Such a class is referred to as a persistence-aware class. This is distinct from a class being JDO-aware, which describes a class that makes direct calls to JDO interfaces at the source level. A persistence-aware class may itself be transient or persistent. So, even though you have a class that is transient, if it directly accesses a managed field, you need to enhance it. You would not list a transient persistence-aware class in the metadata, because any class listed in a metadata file is persistent. So, the only place you identify that a transient class is persistence-aware is in your build files that enhance the class.

We recommend that you declare all of your managed fields to be private; this is considered a best practice in object-oriented development. Independent of the need in JDO to enhance persistence-aware classes, such accesses represent a loss of encapsulation and can often lead to data-integrity issues. Fields declared private cannot be accessed directly by another class. Using private fields thus minimizes the number of persistence-aware classes that need to be enhanced. If a nonmediated access occurs because you forgot to enhance a persistence-aware class, your application will likely behave incorrectly. So, always declare your fields to be private.

The JDO specification defines a standard reference-enhancement contract, which thoroughly specifies all the requirements to enhance a class. Enhanced classes are independent of any particular JDO implementation and datastore.