5.2 JDO Interfaces and Classes

Chapter 3 provides a simplified overview of the key JDO classes and interfaces. Figures 5-2 and 5-3 show all the JDO classes and interfaces defined in the javax.jdo and javax.jdo.spi packages.

Figure 5-2. JDO class diagram.

Figure 5-3. JDO exceptions class diagram.

The javax.jdo package contains the classes and interfaces that a developer would use to build an application using JDO. The javax.jdo.spi package contains the classes and interfaces that would be used to actually implement a JDO compliant interface to a datastore.

A PersistenceManagerFactory is used to get a PersistenceManager instance. There is a one-to-many relationship between PersistenceManagerFactory and PersistenceManager . A PersistenceManagerFactory can create and manage many PersistenceManager instances and even implement pooling of PersistenceManager instances.

A PersistenceManager embodies a connection to a datastore and a cache of in-memory persistent objects that implement the PersistenceCapable interface. The PersistenceManager interface is the primary means by which an application interacts with the underlying datastore and persistent objects.

From a PersistenceManager , an application can get one or more Query instances. A Query is the how an application can find persistent objects by their field values.

In addition to a Query , an application can get an Extent from a PersistenceManager . An Extent represents all persistent objects of a specified class (and optionally subclasses) in the datastore and can be used as input to a Query or iterated through in its own right.

A Transaction allows an application to control the transaction boundaries in the underlying datastore. There is a one-to-one correlation between a Transaction and a PersistenceManager (there can be only one ongoing Transaction per PersistenceManager instance). Transactions must be begun and either committed or aborted.

The InstanceCallbacks interface can be implemented by a PersistenceCapable class and, if implemented the PersistenceManager , invokes the relevant callback methods as a persistent object's lifecycle state changes.

JDOHelper can be used to create a PersistenceManagerFactory from a set of properties and provides convenience methods to interrogate the state of instances of classes that implement PersistenceCapable .

Every persistent object has an associated instance of StateManager . This instance manages the persistent fields and lifecycle state of the in-memory persistent object.

JDOImplHelper is used by the JDO implementations to get metadata on persistence-capable classes; it is not supposed to be used by an application. JDOImplHelper.Meta contains the metadata for a given class. To receive notification when a persistence-capable class is loaded, a JDO implementation registers a RegisterClassListener with the JDOImplHelper . For every persistence-capable class that is loaded, the registered listeners are invoked using a RegisterClassEvent .

JDOPermission contains the access privileges that restrict what can call certain methods on JDOImplHelper and persistence-capable classes that deal with metatdata and modification of the state of a persistent object.

I18Nhelper is used by the JDO classes to get localized messages from a resource bundle. A default resource bundle ( Bundle.properties ) is provided in the JDO JAR.

JDOException is the superclass for all JDO exceptions and extends java.lang.RuntimeException . JDO classifies exceptions broadly into fatal or non-fatal exceptions. JDOFatalException is the superclass for all fatal exceptions, and JDOCanRetryException is the superclass for all non-fatal exceptions.

Non-fatal exceptions indicate that an operation failed but can be retried. JDODataStoreException indicates a problem with the datastore. JDOUserException indicates invalid or incorrect application behavior, and JDOUnsupportedOptionException indicates that an application has tried to use a JDO optional feature that isn't supported by the JDO implementation being used. JDOObjectNotFoundException indicates that a persistent object could not be found in the datastore; this exception was added in the JDO 1.0.1 maintenance revision of the specification.

Fatal exceptions indicate that the only recourse is to start again. JDOFatalDatastoreException indicates a serious problem with the datastore. JDOFatalInternalException indicates a serious problem within the JDO runtime, and JDOFatalUserException indicates a serious problem caused by incorrect application behavior. JDOOptimisticVerificationException indicates that the completion of an optimistic transaction failed due to a conflicting update; this exception was added in the JDO 1.0.1 maintenance revision of the specification.

The rest of this chapter provides a detailed overview of the JDO classes and interfaces. The classes and interfaces are grouped as follows :

Basic APIs

 PersistenceManagerFactory PersistenceManager Transaction Query Extent InstanceCallbacks 

Exception Classes

 JDOException JDOCanRetryException JDODataStoreException JDOUserException JDOUnsupportedOptionException JDOFatalException JDOFatalDatastoreException JDOFatalInternalException JDOOptimisticVerificationException JDOFatalUserException 

Additional APIs

 JDOHelper I18NHelper 

Service Provider APIs

 PersistenceCapable StateManager JDOImplHelper JDOPermission 

The following classes are used internally by the JDO classes themselves and are not covered here:

 JDOImplHelper.Meta RegisterClassListener RegisterClassEvent