5.6 Service Provider Interface APIs

In addition to the application visible classes contained in the javax.jdo package, a number of classes are in the javax.jdo.spi package. These classes are used by the JDO implementations themselves , and an application should not use them directly. A brief summary of the following classes is provided as background information:

• PersistenceCapable

• JDOPermission

• JDOImplHelper

• StateManager

5.6.1 PersistenceCapable

This is the interface that all persistence-capable classes implement. It defines the methods that a JDO implementation uses to manage the instances of persistence-capable classes in memory. It primarily has methods to get and set the fields of an instance and to interrogate lifecycle state. The implementation of the methods defined by PersistenceCapable delegate to a StateManager instance to actually manage the fields.

An application should use the methods defined on PersistenceManager and JDOHelper to interact with persistent objects in memory.

5.6.2 JDOPermission

JDO defines three privileged operations that a JDO implementation or application requires:

• SetStateManager : Allows an implementation to set the StateManager instance associated with an instance of a persistence-capable class and therefore accesses the fields of that instance.

• getMetaData : Allows an implementation to access the metadata for a persistence-capable class via JDOImplHelper .

• closePersistenceManagerFactory : Allows an application to call the close() method on PersistenceManagerFactory to close a PersistenceManagerFactory instance and any associated PersistenceManager instances. This permission was added in the JDO 1.0.1 maintenance release.

The JDOPermission class is used to determine what can perform a privileged operation. If a JDO application is run using a security manager (perhaps as a applet), then the classes that constitute the JDO implementation need to be granted the setStateManager and getMetaData privileges in a policy file.

5.6.3 JDOImplHelper

This class is a singleton that maintains a registry of metadata for each persistence-capable class. When a persistence-capable class is loaded, it registers itself with JDOImplHelper , and the JDO implementation can then use the metadata directly and avoid using reflection.

5.6.4 StateManager

The StateManager interface defines how a JDO implementation actually interacts with instances of persistence-capable classes and manages the fields. The PersistenceCapable and StateManager interfaces are closely related .