531 words

getObjectById(oid, validate) - JDO PersistenceManager's method

Method
javax.jdo.PersistenceManager
Object getObjectById(
  Object oid,
  boolean validate
)

This method locates a persistent instance in the cache of instances managed by this PersistenceManager. The getObjectById method attempts to find an instance in the cache with the specified JDO identity. The oid parameter object might have been returned by an earlier call to getObjectId or getTransactionalObjectId, or might have been constructed by the application.

If the PersistenceManager is unable to resolve the oid parameter to an ObjectId instance, then it throws a JDOUserException.

If the validate flag is false, and there is already an instance in the cache with the same JDO identity as the oid parameter, then this method returns it. There is no change made to the state of the returned instance.

If there is not an instance already in the cache with the same JDO identity as the oid parameter, then this method creates an instance with the specified JDO identity and returns it. If there is no transaction in progress, the returned instance will be hollow or persistent-nontransactional, at the choice of the implementation.

If there is a transaction in progress, the returned instance will be hollow, persistent-nontransactional, or persistent-clean, at the choice of the implementation.

It is an implementation decision whether to access the data store, if required to determine the exact class. This will be the case of inheritance, where multiple PersistenceCapable classes share the same ObjectId class.

If the validate flag is false, and the instance does not exist in the data store, then this method might not fail. It is an implementation choice whether to fail immediately with a JDOObjectNotFoundException. But a subsequent access of the fields of the instance will throw a JDOObjectNotFoundException if the instance does not exist at that time. Further, if a relationship is established to this instance, then the transaction in which the association was made will fail.

If the validate flag is true, and there is already a transactional instance in the cache with the same JDO identity as the oid parameter, then this method returns it. There is no change made to the state of the returned instance.

If there is an instance already in the cache with the same JDO identity as the oid parameter, but the instance is not transactional, then it must be verified in the data store. If the instance does not exist in the datastore, then a JDOObjectNotFoundException is thrown.

If there is not an instance already in the cache with the same JDO identity as the oid parameter, then this method creates an instance with the specified JDO identity, verifies that it exists in the data store, and returns it. If there is no transaction in progress, the returned instance will be hollow or persistent-nontransactional, at the choice of the implementation.

If there is a data store transaction in progress, the returned instance will be persistent-clean. If there is an optimistic transaction in progress, the returned instance will be persistent-nontransactional.

Parameters:
oid - an ObjectId
validate - if the existence of the instance is to be validated
Returns:
the PersistenceCapable instance with the specified ObjectId
Since:
JDO 1.0
See Also:
getObjectId(Object pc)
getTransactionalObjectId(Object pc)

This documentation page is derived (with some adjustments) from the JDO 2.2 API
and is available under the terms of the Apache License, v. 2.0.