Obtaining and Closing a Persistence Manager

Chapter 6 describes how to get a PersistenceManager object from the factory methods in the PersistenceManagerFactory interface and the javax.resource.cci.ConnectionFactory interface. When the factory method returns a persistence manager, the persistence manager is open for business. It remains open until it is closed.

Closing a Persistence Manager

The PersistenceManager interface provides one method to close the persistence manager.

 public void close() 

Depending on the design of the application and the environment in which it is deployed, a persistence manager may be a short-lived or long-lived object. After the application has finished using the persistence manager, it should recycle the resources consumed by the persistence manager by calling the close method. When the application closes the persistence manager, it should no longer use the persistence manager or any of the persistent objects that it managed.

Sometimes the application code that uses JDO executes inside an Enterprise JavaBean (EJB) that uses container-managed transactions. In this case, making multiple calls within the same client invocation of the bean to get a persistence manager from a factory method yields multiple references to the same persistence manager. In this environment, the persistence manager is not actually closed until the container completes the open transaction. The application code should be written, however, with the last step of each business method calling the persistence manager's close method. Chapter 6 describes the appropriate designs for using JDO inside various types of EJBs.

On the other hand, when there isn't any container managing transactions, the application code should end the transaction before closing the persistence manager. As JDO 1.0.1 makes clear, when a container is not managing transactions, the close method throws a JDOUserException if the transaction is active. Chapter 4 describes the Transaction interface.

It is very important that the application take care to clean up references to persistent application data objects before closing the persistence manager. JDO does not define the behavior of application data objects that are managed at the time that the persistence manager closes. They may become unmanaged application data objects. They may be recycled in an instance pool controlled by the JDO implementation. The JDO implementation may mark them so that touching them results in a JDOException. Whatever the behavior is, it is likely to cause confusion or errors for your application.

The Read-Only Closed Property

The PersistenceManager interface provides a getter method for the Closed property.

 public boolean isClosed() 

Once the persistence manager is closed, the persistence manager's Closed property is true. After the persistence manager is closed, this is its only method that does not throw a JDOFatalUserException. Likewise, the Transaction object, Query objects, Extent objects, and Iterator objects obtained from query results collections or extents cannot be used, and any attempt to do so throws a JDOFatalUserException. After closing the persistence manager, the application should avoid using any persistent or transactional objects that the closed persistence manager controlled. Any data objects that are unmanaged when the persistence manager closes are not affected by the closing.

The Read-Only PersistenceManagerFactory Property

The PersistenceManager interface provides a better method for the PersistenceManagerFactory property.

 public PersistenceManagerFactory getPersistenceManagerFactory() 

This method returns a reference to the factory that produced the persistence manager. It returns a reference to a PersistenceManagerFactory object even when the persistence manager was obtained from a ConnectionFactory.