javax.jdo.spi
Interface StateInterrogation

public interface StateInterrogation

This interface is implemented by a non-binary-compatible JDO implementation to provide state interrogation for non-enhanced persistent classes.

A call to JDOHelper to get the status of an instance is handled internally if the parameter instance implements PersistenceCapable. For non-binary-compatible implementations, there is no requirement that persistent instances implement PersistenceCapable. Therefore, if the parameter does not implement PersistenceCapable, JDOHelper delegates to all registered instances of StateInterrogation until an instance can handle the request.

For JDOHelper isXXX methods, which return boolean, the corresponding method in StateInterrogation returns Boolean. If the return value is null then the StateInterrogation does not recognize the parameter as being handled by it. A non-null return value indicates that the implementation has determined the answer.

For JDOHelper getXXX methods, which return an Object, each registered StateInterrogation is given the parameter until one of them returns a non-null value, which is passed to the caller.

For JDOHelper makeDirty, each registered StateInterrogation is given the parameter until one of them returns true, indicating that it has handled the call. An instance that implements this interface must be registered with the JDOImplHelper.

Since:

2.0

Version:

2.0

Method Summary

java.lang.Object	getObjectId(java.lang.Object pc) Return a copy of the JDO identity associated with the parameter instance.
PersistenceManager	getPersistenceManager(java.lang.Object pc) Return the associated PersistenceManager if there is one.
java.lang.Object	getTransactionalObjectId(java.lang.Object pc) Return a copy of the JDO identity associated with the parameter instance.
java.lang.Object	getVersion(java.lang.Object pc) Return the version of the parameter instance.
java.lang.Boolean	isDeleted(java.lang.Object pc) Tests whether the parameter instance has been deleted.
java.lang.Boolean	isDetached(java.lang.Object pc) Tests whether the parameter instance is detached.
java.lang.Boolean	isDirty(java.lang.Object pc) Tests whether the parameter instance is dirty.
java.lang.Boolean	isNew(java.lang.Object pc) Tests whether the parameter instance has been newly made persistent.
java.lang.Boolean	isPersistent(java.lang.Object pc) Tests whether the parameter instance is persistent.
java.lang.Boolean	isTransactional(java.lang.Object pc) Tests whether the parameter instance is transactional.
boolean	makeDirty(java.lang.Object pc, java.lang.String fieldName) Explicitly mark the parameter instance and field dirty.

Method Detail

isPersistent

java.lang.Boolean isPersistent(java.lang.Object pc)

Tests whether the parameter instance is persistent. Instances that represent persistent objects in the data store return Boolean.TRUE.

Instances known by the implementation to be non-persistent return Boolean.FALSE.

Instances not recognized by the implementation return null.

Parameters:

pc - the instance.

Returns:

Boolean.TRUE if the parameter instance is persistent.

See Also:

PersistenceManager.makePersistent(Object pc), PersistenceCapable.jdoIsPersistent()

isTransactional

java.lang.Boolean isTransactional(java.lang.Object pc)

Tests whether the parameter instance is transactional. Instances whose state is associated with the current transaction return Boolean.TRUE.

Instances known by the implementation to be non-transactional return Boolean.FALSE.

Instances not recognized by the implementation return null.

Parameters:

pc - the instance.

Returns:

Boolean.TRUE if the parameter instance is transactional.

See Also:

PersistenceCapable.jdoIsTransactional()

isDirty

java.lang.Boolean isDirty(java.lang.Object pc)

Tests whether the parameter instance is dirty. Instances that have been modified, deleted, newly made persistent in the current transaction, or modified while detached return Boolean.TRUE.

Instances known by the implementation to be non-dirty return Boolean.FALSE.

Instances not recognized by the implementation return null.

Parameters:

pc - the instance.

Returns:

Boolean.TRUE if the parameter instance has been modified in the current transaction, or while detached.

See Also:

StateManager.makeDirty(PersistenceCapable pc, String fieldName), PersistenceCapable.jdoIsDirty()

isNew

java.lang.Boolean isNew(java.lang.Object pc)

Tests whether the parameter instance has been newly made persistent. Instances that have been made persistent in the current transaction return Boolean.TRUE.

Instances known by the implementation to be non-new return Boolean.FALSE.

Instances not recognized by the implementation return null.

Parameters:

pc - the instance.

Returns:

Boolean.TRUE if the parameter instance was made persistent in the current transaction.

See Also:

PersistenceManager.makePersistent(Object pc), PersistenceCapable.jdoIsNew()

isDeleted

java.lang.Boolean isDeleted(java.lang.Object pc)

Tests whether the parameter instance has been deleted. Instances that have been deleted in the current transaction return Boolean.TRUE.

Instances known by the implementation to be non-deleted return Boolean.FALSE.

Instances not recognized by the implementation return null.

Parameters:

pc - the instance.

Returns:

Boolean.TRUE if the parameter instance was deleted in the current transaction.

See Also:

PersistenceManager.deletePersistent(Object pc), PersistenceCapable.jdoIsDeleted()

isDetached

java.lang.Boolean isDetached(java.lang.Object pc)

Tests whether the parameter instance is detached. Instances that are detached return Boolean.TRUE.

Instances known by the implementation to be non-detached return Boolean.FALSE.

Instances not recognized by the implementation return null.

Parameters:

pc - the instance.

Returns:

Boolean.TRUE if the parameter instance is detached.

See Also:

PersistenceManager.detachCopy(Object pc), PersistenceCapable.jdoIsDeleted()

getPersistenceManager

PersistenceManager getPersistenceManager(java.lang.Object pc)

Return the associated PersistenceManager if there is one. Transactional and persistent instances return the associated PersistenceManager.

Transient non-transactional instances return null.

Instances unknown by the implementation return null.

Parameters:

pc - the instance.

Returns:

the PersistenceManager associated with the parameter instance.

See Also:

PersistenceCapable.jdoGetPersistenceManager()

getObjectId

java.lang.Object getObjectId(java.lang.Object pc)

Return a copy of the JDO identity associated with the parameter instance.

Persistent instances of PersistenceCapable classes have a JDO identity managed by the PersistenceManager. This method returns a copy of the ObjectId that represents the JDO identity.

Instances unknown by the implementation return null.

The ObjectId may be serialized and later restored, and used with a PersistenceManager from the same JDO implementation to locate a persistent instance with the same data store identity.

If the JDO identity is managed by the application, then the ObjectId may be used with a PersistenceManager from any JDO implementation that supports the PersistenceCapable class.

If the JDO identity is not managed by the application or the data store, then the ObjectId returned is only valid within the current transaction.

Parameters:

pc - the instance.

Returns:

a copy of the ObjectId of the parameter instance as of the beginning of the transaction.

See Also:

PersistenceManager.getObjectId(Object pc), PersistenceCapable.jdoGetObjectId(), PersistenceManager.getObjectById(Object oid, boolean validate)

getTransactionalObjectId

java.lang.Object getTransactionalObjectId(java.lang.Object pc)

Return a copy of the JDO identity associated with the parameter instance.

Instances unknown by the implementation return null.

Parameters:

pc - the instance.

Returns:

a copy of the ObjectId of the parameter instance as modified in this transaction.

See Also:

PersistenceCapable.jdoGetTransactionalObjectId(), PersistenceManager.getObjectById(Object oid, boolean validate)

getVersion

java.lang.Object getVersion(java.lang.Object pc)

Return the version of the parameter instance.

Instances unknown by the implementation return null.

Parameters:

pc - the instance.

Returns:

a copy of the ObjectId of the parameter instance as modified in this transaction.

See Also:

PersistenceCapable.jdoGetVersion()

makeDirty

boolean makeDirty(java.lang.Object pc,
                  java.lang.String fieldName)

Explicitly mark the parameter instance and field dirty. Normally, PersistenceCapable classes are able to detect changes made to their fields. However, if a reference to an array is given to a method outside the class, and the array is modified, then the persistent instance is not aware of the change. This API allows the application to notify the instance that a change was made to a field.

Instances unknown by the implementation are unaffected.

Parameters:

pc - the instance.

fieldName - the name of the field to be marked dirty.

See Also:

PersistenceCapable.jdoMakeDirty(String fieldName)