2.2 The javax.jdo.spi Package

The javax.jdo.spi package defines interfaces used by JDO implementations. Your application should not use the interfaces in this package. However, a few interfaces in this package are useful for you to be aware of, as they are directly responsible for managing the state of persistent instances.


The PersistenceCapable interface allows an implementation to manage the values of fields and the lifecycle state of persistent instances. Every instance managed by a PersistenceManager needs to be of a class that implements PersistenceCapable. When you enhance a persistent class, code is added to the class to implement the PersistenceCapable interface.

You should not directly use the PersistenceCapable methods added by the enhancer. Some of its methods provide information useful to your application; these methods are made accessible to you through the JDOHelper and PersistenceManager interfaces.


Every persistent and transactional instance has a reference to a StateManager instance. (Chapter 13 covers transactional instances.) A StateManager interfaces with the PersistenceManager and is responsible for managing the values of fields and state transitions of an instance. (Chapter 11 covers state transitions.)


The JDOPermission class is used to grant the JDO implementation permission to perform privileged operations if you have a Java security manager in your Java runtime environment. JDOPermission extends java.security.BasicPermission. The following permissions are defined:


This permission allows a StateManager instance to manage an instance of PersistenceCapable, allowing it to access and modify any of the fields in the class that are defined as persistent or transactional. (Chapter 12 covers transactional fields.)


This permission allows a StateManager instance to access the metadata of any registered persistent class.


This permission must be granted to close a PersistenceManagerFactory.

Use of the JDOPermission class allows the security manager to restrict potentially malicious classes from accessing information contained in instances of persistent classes.

Assume that you have placed the jar files for the JDO implementation you are using in the /home/jdoImpl directory. The following sample policy-file entry grants any jars or class files in that directory permission to get metadata and manage the state of persistent instances:

grant codeBase "file:/home/jdoImpl/" {
        permission javax.jdo.spi.JDOPermission "getMetadata";
        permission javax.jdo.spi.JDOPermission "setStateManager";