Obtaining a Persistence Manager

When the application uses JDO, an early and important task is to obtain a persistence manager. A persistence manager can be obtained from an object that implements the PersistenceManagerFactory or the ConnectionFactory interfaces.

Obtaining a Persistence Manager from a Persistence Manager Factory

When obtaining the persistence manager from an object that implements PersistenceManagerFactory, the application uses one of two methods:

 public PersistenceManager getPersistenceManager() public PersistenceManager getPersistenceManager(String userName, String password) 

The method without parameters instructs the persistence manager to use the ConnectionUserName and ConnectionPassword properties configured for the factory when connecting to the datastore. The method with the user name and password parameters instructs the persistence manager to override the factory configuration for user name and password when connecting to the datastore. However the user name and password are determined, the persistence manager uses the same user name and password for every connection that it makes to the datastore.

The persistence manager inherits the configuration of the factory that produced it. It inherits values for its properties IgnoreCache and Multithreaded, and its transaction inherits values for its five properties, Optimistic, RetainValues, RestoreValues, NontransactionalRead, and NontransactionalWrite. When the persistence manager connects to the datastore, it uses the connection properties configured for the factory, with the possible exception that the ConnectionUserName and ConnectionPassword properties may be overriden by the parameters of the getPersistenceManager method.

If the persistence manager is closed, the getPersistenceManager methods throw a JDOUserException.

Obtaining a Persistence Manager from a Connection Factory

The JCA defines a standard way for vendors to design and package their connection-oriented code for use in J2EE application servers. In the case of JDO vendors, they have the option of packaging the entire JDO implementation as a resource adaptor in a Resource Adapter Archive (RAR) file. The RAR file is then deployed with one or more deployment descriptors in the application server. A later section of this chapter, "Obtaining a Connection Factory," explains how to obtain a connection factory.

After obtaining a connection factory, the application obtains a persistence manager from the connection factory as shown in Listing 6-1. All of the properties of the PersistenceManagerFactory are configured in the XML deployment descriptors that are either contained in or accompany the RAR file. The persistence managers that the connection produces inherit their property values from the connection factory's configuration.

Listing 6-1: Getting a PersistenceManager from a Connection Factory

 PersistenceManager pm = null; try    {    // cf is a ConnectionFactory object obtained earlier    pm = (PersistenceManager) cf.getConnection();    } catch (ResourceException e)    {    // handle exception ...    }