The diagram below illustrates the relationships between the primary components of the JDO architecture.
JDOHelper. The javax.jdo.JDOHelper contains static helper methods to query the lifecycle state of persistent objects and to create concrete PersistenceManagerFactory instances in a vendor-neutral fashion.
PersistenceManagerFactory . The javax.jdo.PersistenceManagerFactory is a factory for PersistenceManagers.
PersistenceManager. The javax.jdo.PersistenceManager is the primary JDO interface used by applications. Each PersistenceManager manages a set of persistent objects and has APIs to persist new objects and delete existing persistent objects. There is a one-to-one relationship between a PersistenceManager and a Transaction. PersistenceManagers also act as factories for Extent and Query instances.
PersistenceCapable. User-defined persistent classes must implement the javax.jdo.spi.PersistenceCapable interface. Most JDO implementations provide an enhancer that transparently adds the code to implement this interface to each persistent class. You should never use the PersistenceCapable interface directly.
Transaction. Each PersistenceManager has a one-to-one relation with a single javax.jdo.Transaction. Transactions allow operations on persistent data to be grouped into units of work that either completely succeed or completely fail, leaving the data store in its original state. These all-or-nothing operations are important for maintaining data integrity.
Extent. The javax.jdo.Extent is a logical view of all the objects of a particular class that exist in the data store. Extents can be configured to also include subclasses. Extents are obtained from a PersistenceManager.
Query. The javax.jdo.Query interface is implemented by each JDO vendor to translate expressions in the Java Data Objects Query Language (JDOQL), which is based on Java boolean expressions, into the native query language of the data store. You obtain Query instances from a PersistenceManager.
The example below illustrates how the JDO interfaces interact to execute a query and update persistent objects.
Example 3.1. Interaction of JDO Interfaces
// get a persistence manager factory using the jdo helper
PersistenceManagerFactory factory =
JDOHelper.getPersistenceManagerFactory (System.getProperties ());
// get a persistence manager from the factory
PersistenceManager pm = factory.getPersistenceManager ();
// updates take place within transactions
Transaction tx = pm.currentTransaction ();
tx.begin ();
// query for all employees who work in our research division
// and put in over 40 hours a week average
Extent extent = pm.getExtent (Employee.class, false);
Query query = pm.newQuery ();
query.setCandidates (extent);
query.setFilter ("division.name == 'Research' && avgHours > 40");
Collection results = (Collection) query.execute ();
// give all those hard-working employees a raise
Employee emp;
for (Iterator itr = results.iterator (); itr.hasNext ();)
{
emp = (Employee) itr.next ();
emp.setSalary (emp.getSalary () * 1.1);
}
// commit the updates and free resources
tx.commit ();
pm.close ();
factory.close ();
The remainder of this document explores the JDO interfaces in detail. We present them in roughly the order that you will use them as you develop your application.
The diagram below depicts the JDO exception architecture. Runtime exceptions such as NullPointerExceptions and IllegalArgumentExceptions aside, JDO components throw nothing but JDOExceptions of one type or another.
The JDO exception hierarchy should be self-explanatory. Consult the JDO Javadoc for details.
