7.2 Acquiring a PersistenceManager

Once you have configured a PersistenceManagerFactory with the appropriate property settings, you can call one of the following PersistenceManagerFactory methods to construct a PersistenceManager instance:

PersistenceManager getPersistenceManager(  );
PersistenceManager getPersistenceManager(String userid, String password);

The returned instance may come from a pool of PersistenceManager instances, but the property values in the returned PersistenceManager instance are equal to their values in the PersistenceManagerFactory instance.

After your first call to getPersistenceManager( ), none of the set methods in the PersistenceManagerFactory will succeed. You may be able to modify the setting of operational parameters dynamically using a vendor-specific interface.

If you acquire the PersistenceManager by calling the getPersistenceManager( ) method that has the userid and password parameters, all of the manager's accesses to get a connection from the connection factory use the provided userid and password. If PersistenceManager instances are pooled, then getPersistenceManager( ) returns only a PersistenceManager instance with the same userid and password.

You may need to access the PersistenceManagerFactory that was used to create a PersistenceManager. You can call the following PersistenceManager method to access it:

PersistenceManagerFactory  getPersistenceManagerFactory(  );

If a PersistenceManagerFactory instance was not used to create the PersistenceManager instance (e.g., a call to a vendor-specific PersistenceManager constructor was used), this method returns null.

7.2.1 User Object

Your application may use multiple PersistenceManager instances concurrently. You may find it useful to define a class that is responsible for managing and tracking the set of PersistenceManager instances. In such circumstances, it is useful to associate the manager object responsible for each PersistenceManager instance and be able to access the manager object from the PersistenceManager instance. The following PersistenceManager methods allow you to set and get an instance to be associated with a PersistenceManager instance:

void setUserObject(Object object);
Object getUserObject(  );

You have complete freedom in how this user object is used. The implementation does not inspect or use it in any way.

7.2.2 Closing a PersistenceManager

A PersistenceManager maintains a set of resources that it uses to manage persistent instances. If you are finished using a PersistenceManager, you can close it to free up its resources by calling its close( ) method:

void 
close(  );

After you call close( ), all methods on the PersistenceManager instance (except isClosed( )) throw a JDOFatalUserException. If the current transaction is active when you call close( ), a JDOUserException is thrown.

When the PersistenceManager instance is closed, it might be returned to a pool of PersistenceManager instances or garbage-collected, at the choice of the implementation. Before it can be used to satisfy another getPersistenceManager( ) request, its properties are reset to the values specified in its associated PersistenceManagerFactory instance.

You can call the following PersistenceManager method to determine whether a PersistenceManager is closed:

boolean isClosed(  );

Once the PersistenceManager instance has been constructed or retrieved from a pool, it returns false. It returns true only after close( ) has successfully closed the instance.

7.2.3 Closing a PersistenceManagerFactory

A PersistenceManagerFactory also maintains significant resources. If you no longer need a PersistenceManagerFactory, you can close it with the following method:

void close(  );

This method disables the PersistenceManagerFactory and relinquishes its associated resources.

Closing a PersistenceManagerFactory prematurely can have a significant impact on the operation of the JDO environment. Therefore, a security check is made for JDOPermission("closePersistenceManagerFactory") to determine whether the caller has been granted permission to close a PersistenceManagerFactory. If the permission check fails, close( ) does not close the PersistenceManagerFactory and throws a SecurityException.

This close( ) method automatically closes all PersistenceManager instances that are still open and do not have an active Transaction. If some PersistenceManager instances do have active Transaction instances, a JDOUserException is thrown. The JDOUserException instance thrown to the caller of close( ) does not have a failed instance. It has a nested exception array that contains a JDOUserException for each PersistenceManager that could not be closed. Each nested JDOUserException references a PersistenceManager as the failed instance.