> Developers Guide for Kodo
Chapter 3. JDO Architecture
Prev Part 3. Java Data Objects Next

Chapter 3. JDO Architecture

3.1. JDO Exceptions

The diagram below illustrates the relationships between the primary components of the JDO architecture.

The example below illustrates how the JDO interfaces interact to execute a JDOQL query and update persistent objects.

Example 3.1. Interaction of JDO Interfaces

// get a PersistenceManagerFactory using the JDOHelper; typically 
// the factory is cached for easy repeated use 
PersistenceManagerFactory factory = 
    JDOHelper.getPersistenceManagerFactory (System.getProperties ());

// get a PersistenceManager 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 (extent);
query.setFilter ("division.name == 'Research' && avgHours > 40");

// we only need to populate the metadata-defined salary fetch group data;
// there might be a lot of employees, so read from store in batches of 100
query.getFetchPlan ().setGroup ("salary");
query.getFetchPlan ().setFetchSize (100);
List results = (List) query.execute ();

// give all those hard-working employees a raise; keep track of hardest worker
Employee emp;
Employee mostHours = null;
for (Iterator itr = results.iterator (); itr.hasNext ();)
{
    emp = (Employee) itr.next ();
    emp.setSalary (emp.getSalary () * 1.1);
    if (mostHours == null || emp.avgHours () > mostHours.avgHours ())
        mostHours = emp;
} 

// we know we're going to be fetching the hardest-working employee a 
// lot in our application, so pin its data to the cache
factory.getDataStoreCache ().pin (JDOHelper.getObjectId (mostHours)); 

// commit the updates and free persistence manager
tx.commit ();
pm.close ();

// if we were ending our application, we'd free the factory too
// 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.

3.1. JDO Exceptions

The diagram above depicts the JDO exception architecture. Runtime exceptions such as NullPointerExceptions and IllegalArgumentExceptions aside, JDO components only throw JDOExceptions.

The JDO exception hierarchy should be self-explanatory. The base JDOException class provides the following useful properties:

  • FailedObject: The failed object is the persistent instance or identity object that caused the exception, if applicable. It is particularly useful for JDOOptimisticVerificationExceptions and JDOObjectNotFoundExceptions.

  • NestedExceptions: An array of nested exceptions that caused the failure. Rather than stop immediately at the first error, many JDO methods collect all errors during execution and throw a single parent exception, nesting the collected exceptions within it. For example, a failed attempt to commit a transaction might result in a JDOFatalDataStoreException with a nested JDOOptimisticVerificationException for each persistent instance that failed the optimsitic concurrency check.

See the Javadoc for additional details on JDO exceptions.

Prev Up Next
Chapter 2. Why JDO? Home Chapter 4. PersistenceCapable

 

Skip navigation bar   Back to Top