Chapter 3. JDO Architecture
Prev | Part II. Java Data Objects | Next

## Chapter 3. JDO Architecture

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 `PersistenceManager`s.

- `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`. `PersistenceManager`s 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`. `Transaction`s 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. `Extent`s can be configured to also include subclasses. `Extent`s 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.

## 3.1. JDO Exceptions

The diagram below depicts the JDO exception architecture. Runtime exceptions such as `NullPointerException`s and `IllegalArgumentException`s aside, JDO components throw nothing but `JDOException`s of one type or another.

The JDO exception hierarchy should be self-explanatory. Consult the JDO Javadoc for details.

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