Fetching an Application Data Object by Identity

The PersistenceManager interface provides one method to fetch an application data object by identity.

 public Object getObjectById(Object idObject, boolean verifyPersistence) 

When the application has a JDO identity object, it can fetch the corresponding application data object by calling the getObjectById method. This method takes two parameters. The first parameter is the identity object. If the idObject is not an identity object, the method throws a JDOUserException.

The second parameter to this method is a Boolean flag that indicates whether JDO should verify that an object exists in the datastore with the given JDO identity. The setting of the verifyPersistence flag makes a difference when the application data object does not exist in the cache or the datastore. If the flag is false, the JDO implementation is not required to verify that the object exists in the datastore. It is permitted to delay verification until the application data object is used in some way that forces a datastore access. When the flag is true, the method must, with one exception, verify that the persistent state that corresponds to the durable identity exists in the datastore. The exception arises when an object exists in the cache and is transactional. In this case, the method may skip verification even when the flag is true. If, when verifying, this method does not find the persistent object in the datastore, or if, during a later operation, JDO does not find the persistent object in the datastore, then JDO throws a JDODataStoreException in JDO 1.0. Under the same circumstances, JDO throws a JDOObjectNotFoundException in JDO 1.0.1. JDOObjectNotFoundException is a new exception type in JDO 1.0.1 and a subclass of JDODataStoreException. Chapter 7 discusses the JDO exception classes.

The getObjectById method does not change the state of an application data object that it finds in the cache. If the method constructs the application data object, it returns the object in the persistent-clean state when a datastore transaction is active, and in either the hollow or persistent-nontransactional state otherwise. Although the specification is not clear, you should not expect this method to work when a transaction is not active and the transaction's NontransactionalRead property is false. In these circumstances, it will likely throw a JDOUserException.

If the idObject is an application identity object, then none of its key fields may contain the null value. If any do, getObjectById throws a JDOUserException.