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

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

- - ### Method Detail

    - #### isPersistent

          Boolean isPersistent(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

          Boolean isTransactional(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

          Boolean isDirty(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

          Boolean isNew(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

          Boolean isDeleted(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

          Boolean isDetached(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(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

          Object getObjectId(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

          Object getTransactionalObjectId(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

          Object getVersion(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(Object pc,
                            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.
      Returns:
        Whether it was made dirty
      See Also:
        `PersistenceCapable.jdoMakeDirty(String fieldName)`

Copyright © 2005–2022 The Apache Software Foundation. All rights reserved.