Overview | Package | Class | Tree | Deprecated | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.jdo.spi
Interface PersistenceCapable

public interface PersistenceCapable

A class that can be managed by a JDO implementation must implement this interface.

Every class whose instances can be managed by a JDO PersistenceManager must implement the PersistenceCapable interface.

This interface defines methods that allow the implementation to manage the instances. It also defines methods that allow a JDO aware application to examine the runtime state of instances. For example, an application can discover whether the instance is persistent, transactional, dirty, new, or deleted; and to get its associated PersistenceManager if it has one.

In the Reference Implementation, the JDO Enhancer modifies the class to implement PersistenceCapable prior to loading the class into the runtime environment. The Reference Enhancer also adds code to implement the methods defined by PersistenceCapable.

The extra methods in the PersistenceCapable interface might be generated by pre-processing a .java file, or might be generated from a tool directly. The exact technique for generating the extra methods is not specified by JDO.

The PersistenceCapable interface is designed to avoid name conflicts in the scope of user-defined classes. All of its declared method names are prefixed with 'jdo'.

Nested Class Summary
`static interface` | `PersistenceCapable.ObjectIdFieldConsumer` This interface is used to store fields from the Object id instance.
`static interface` | `PersistenceCapable.ObjectIdFieldManager` This interface is a convenience interface that allows an instance to implement both ObjectIdFieldSupplier and ObjectIdFieldConsumer.
`static interface` | `PersistenceCapable.ObjectIdFieldSupplier` This interface is used to provide fields to the Object id instance.

Field Summary
`static byte` | `CHECK_READ` If jdoFieldFlags for a field includes CHECK_READ, then the field has been enhanced to call the jdoStateManager on read if the jdoFlags setting is not READ_OK or READ_WRITE_OK.
`static byte` | `CHECK_WRITE` If jdoFieldFlags for a field includes CHECK_WRITE, then the field has been enhanced to call the jdoStateManager on write if the jdoFlags setting is not READ_WRITE_OK;.
`static byte` | `LOAD_REQUIRED` If jdoFlags is set to LOAD_REQUIRED, then the fields in the default fetch group cannot be accessed for read or write without notifying the StateManager.
`static byte` | `MEDIATE_READ` If jdoFieldFlags for a field includes MEDIATE_READ, then the field has been enhanced to always call the jdoStateManager on all reads.
`static byte` | `MEDIATE_WRITE` If jdoFieldFlags for a field includes MEDIATE_WRITE, then the field has been enhanced to always call the jdoStateManager on all writes.
`static byte` | `READ_OK` If jdoFlags is set to READ_OK, then the fields in the default fetch group can be accessed for read without notifying the StateManager.
`static byte` | `READ_WRITE_OK` If jdoFlags is set to READ_WRITE_OK, then the fields in the default fetch group can be accessed for read or write without notifying the StateManager.
`static byte` | `SERIALIZABLE` If jdoFieldFlags for a field includes SERIALIZABLE, then the field is not declared as TRANSIENT.

Method Summary
`void` | `jdoCopyFields(java.lang.Object other, int[] fieldNumbers)` Copy field values from another instance of the same class to this instance.
`void` | `jdoCopyKeyFieldsFromObjectId(PersistenceCapable.ObjectIdFieldConsumer fm, java.lang.Object oid)` Copy fields to an outside source from the key fields in the ObjectId.
`void` | `jdoCopyKeyFieldsToObjectId(java.lang.Object oid)` Copy fields from this PersistenceCapable instance to the Object Id instance.
`void` | `jdoCopyKeyFieldsToObjectId(PersistenceCapable.ObjectIdFieldSupplier fm, java.lang.Object oid)` Copy fields from an outside source to the key fields in the ObjectId.
`java.lang.Object` | `jdoGetObjectId()` Return a copy of the JDO identity associated with this instance.
`PersistenceManager` | `jdoGetPersistenceManager()` Return the associated PersistenceManager if there is one.
`java.lang.Object` | `jdoGetTransactionalObjectId()` Return a copy of the JDO identity associated with this instance.
`boolean` | `jdoIsDeleted()` Tests whether this object has been deleted.
`boolean` | `jdoIsDirty()` Tests whether this object is dirty.
`boolean` | `jdoIsNew()` Tests whether this object has been newly made persistent.
`boolean` | `jdoIsPersistent()` Tests whether this object is persistent.
`boolean` | `jdoIsTransactional()` Tests whether this object is transactional.
`void` | `jdoMakeDirty(java.lang.String fieldName)` Explicitly mark this instance and this field dirty.
`PersistenceCapable` | `jdoNewInstance(StateManager sm)` Return a new instance of this class, with the jdoStateManager set to the parameter, and jdoFlags set to LOAD_REQUIRED.
`PersistenceCapable` | `jdoNewInstance(StateManager sm, java.lang.Object oid)` Return a new instance of this class, with the jdoStateManager set to the parameter, key fields initialized to the values in the oid, and jdoFlags set to LOAD_REQUIRED.
`java.lang.Object` | `jdoNewObjectIdInstance()` Create a new instance of the ObjectId class for this PersistenceCapable class.
`java.lang.Object` | `jdoNewObjectIdInstance(java.lang.String str)` Create a new instance of the ObjectId class for this PersistenceCapable class, using the String form of the constructor.
`void` | `jdoProvideField(int fieldNumber)` The owning StateManager uses this method to ask the instance to provide the value of the single field identified by fieldNumber.
`void` | `jdoProvideFields(int[] fieldNumbers)` The owning StateManager uses this method to ask the instance to provide the values of the multiple fields identified by fieldNumbers.
`void` | `jdoReplaceField(int fieldNumber)` The owning StateManager uses this method to ask the instance to replace the value of the single field identified by number.
`void` | `jdoReplaceFields(int[] fieldNumbers)` The owning StateManager uses this method to ask the instance to replace the values of the multiple fields identified by number.
`void` | `jdoReplaceFlags()` The owning StateManager uses this method to ask the instance to replace the value of the flags by calling back the StateManager replacingFlags method.
`void` | `jdoReplaceStateManager(StateManager sm)` This method sets the StateManager instance that manages the state of this instance.

Field Detail

### READ_WRITE_OK

    public static final byte READ_WRITE_OK

  If jdoFlags is set to READ_WRITE_OK, then the fields in the default fetch group can be accessed for read or write without notifying the StateManager.

  See Also:
    Constant Field Values

### LOAD_REQUIRED

    public static final byte LOAD_REQUIRED

  If jdoFlags is set to LOAD_REQUIRED, then the fields in the default fetch group cannot be accessed for read or write without notifying the StateManager.

  See Also:
    Constant Field Values

### READ_OK

    public static final byte READ_OK

  If jdoFlags is set to READ_OK, then the fields in the default fetch group can be accessed for read without notifying the StateManager.

  See Also:
    Constant Field Values

### CHECK_READ

    public static final byte CHECK_READ

  If jdoFieldFlags for a field includes CHECK_READ, then the field has been enhanced to call the jdoStateManager on read if the jdoFlags setting is not READ_OK or READ_WRITE_OK.

  See Also:
    Constant Field Values

### MEDIATE_READ

    public static final byte MEDIATE_READ

  If jdoFieldFlags for a field includes MEDIATE_READ, then the field has been enhanced to always call the jdoStateManager on all reads.

  See Also:
    Constant Field Values

### CHECK_WRITE

    public static final byte CHECK_WRITE

  If jdoFieldFlags for a field includes CHECK_WRITE, then the field has been enhanced to call the jdoStateManager on write if the jdoFlags setting is not READ_WRITE_OK;.

  See Also:
    Constant Field Values

### MEDIATE_WRITE

    public static final byte MEDIATE_WRITE

  If jdoFieldFlags for a field includes MEDIATE_WRITE, then the field has been enhanced to always call the jdoStateManager on all writes.

  See Also:
    Constant Field Values

### SERIALIZABLE

    public static final byte SERIALIZABLE

  If jdoFieldFlags for a field includes SERIALIZABLE, then the field is not declared as TRANSIENT.

  See Also:
    Constant Field Values

Method Detail

### jdoGetPersistenceManager

    public PersistenceManager jdoGetPersistenceManager()

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

  Transient non-transactional instances return null.

  This method always delegates to the StateManager if it is non-null.

  Returns:
    the PersistenceManager associated with this instance.

### jdoReplaceStateManager

    public void jdoReplaceStateManager(StateManager sm)
                                throws java.lang.SecurityException

  This method sets the StateManager instance that manages the state of this instance. This method is normally used by the StateManager during the process of making an instance persistent, transient, or transactional. The caller of this method must have JDOPermission for the instance, if the instance is not already owned by a StateManager. If the parameter is null, and the StateManager approves the change, then the jdoFlags field will be reset to READ_WRITE_OK. If the parameter is not null, and the security manager approves the change, then the jdoFlags field will be reset to LOAD_REQUIRED.

  Parameters:
    `sm` - The StateManager which will own this instance, or null to reset the instance to transient state
  Throws:
    `java.lang.SecurityException` - if the caller does not have JDOPermission
  See Also:
    `JDOPermission`

### jdoProvideField

    public void jdoProvideField(int fieldNumber)

  The owning StateManager uses this method to ask the instance to provide the value of the single field identified by fieldNumber.

  Parameters:
    `fieldNumber` - the field whose value is to be provided by a callback to the StateManager's providedXXXField method

### jdoProvideFields

    public void jdoProvideFields(int[] fieldNumbers)

  The owning StateManager uses this method to ask the instance to provide the values of the multiple fields identified by fieldNumbers.

  Parameters:
    `fieldNumbers` - the fields whose values are to be provided by multiple callbacks to the StateManager's providedXXXField method

### jdoReplaceField

    public void jdoReplaceField(int fieldNumber)

  The owning StateManager uses this method to ask the instance to replace the value of the single field identified by number.

  Parameters:
    `fieldNumber` - the field whose value is to be replaced by a callback to the StateManager's replacingXXXField method

### jdoReplaceFields

    public void jdoReplaceFields(int[] fieldNumbers)

  The owning StateManager uses this method to ask the instance to replace the values of the multiple fields identified by number.

  Parameters:
    `fieldNumbers` - the fields whose values are to be replaced by multiple callbacks to the StateManager's replacingXXXField method

### jdoReplaceFlags

    public void jdoReplaceFlags()

  The owning StateManager uses this method to ask the instance to replace the value of the flags by calling back the StateManager replacingFlags method.

### jdoCopyFields

    public void jdoCopyFields(java.lang.Object other,
                              int[] fieldNumbers)

  Copy field values from another instance of the same class to this instance.

  This method will throw an exception if the other instance is not managed by the same StateManager as this instance.

  Parameters:
    `other` - the PC instance from which field values are to be copied
    `fieldNumbers` - the field numbers to be copied into this instance

### jdoMakeDirty

    public void jdoMakeDirty(java.lang.String fieldName)

  Explicitly mark this instance and this 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.

  The field name should be the fully qualified name, including package name and class name of the class declaring the field. This allows unambiguous identification of the field to be marked dirty. If multiple classes declare the same field, and if the package and class name are not provided by the parameter in this API, then the field marked dirty is the field declared by the most derived class.

  Transient instances ignore this method.

  Parameters:
    `fieldName` - the name of the field to be marked dirty.

### jdoGetObjectId

    public java.lang.Object jdoGetObjectId()

  Return a copy of the JDO identity associated with this 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.

  Transient instances 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.

  If the JDO identity is being changed in the transaction, this method returns the object id as of the beginning of the current transaction.

  Returns:
    a copy of the ObjectId of this instance as of the beginning of the transaction.
  See Also:
    `PersistenceManager.getObjectId(Object pc)`, `PersistenceManager.getObjectById(Object oid, boolean validate)`

### jdoGetTransactionalObjectId

    public java.lang.Object jdoGetTransactionalObjectId()

  Return a copy of the JDO identity associated with this instance. This method is the same as jdoGetObjectId if the identity of the instance has not changed in the current transaction.

  If the JDO identity is being changed in the transaction, this method returns the current object id as modified in the current transaction.

  Returns:
    a copy of the ObjectId of this instance as modified in the transaction.
  See Also:
    `jdoGetObjectId()`, `PersistenceManager.getObjectId(Object pc)`, `PersistenceManager.getObjectById(Object oid, boolean validate)`

### jdoIsDirty

    public boolean jdoIsDirty()

  Tests whether this object is dirty. Instances that have been modified, deleted, or newly made persistent in the current transaction return true.

  Transient instances return false.

  Returns:
    true if this instance has been modified in the current transaction.
  See Also:
    `JDOHelper.isDirty(Object pc)`, `JDOHelper.makeDirty(Object pc, String fieldName)`, `jdoMakeDirty(String fieldName)`

### jdoIsTransactional

    public boolean jdoIsTransactional()

  Tests whether this object is transactional. Instances whose state is associated with the current transaction return true.

  Transient instances return false.

  Returns:
    true if this instance is transactional.
  See Also:
    `JDOHelper.isTransactional(Object pc)`, `PersistenceManager.makeTransactional(Object pc)`

### jdoIsPersistent

    public boolean jdoIsPersistent()

  Tests whether this object is persistent. Instances that represent persistent objects in the data store return true.

  Returns:
    true if this instance is persistent.
  See Also:
    `JDOHelper.isPersistent(Object pc)`, `PersistenceManager.makePersistent(Object pc)`

### jdoIsNew

    public boolean jdoIsNew()

  Tests whether this object has been newly made persistent. Instances that have been made persistent in the current transaction return true.

  Transient instances return false.

  Returns:
    true if this instance was made persistent in the current transaction.
  See Also:
    `JDOHelper.isNew(Object pc)`, `PersistenceManager.makePersistent(Object pc)`

### jdoIsDeleted

    public boolean jdoIsDeleted()

  Tests whether this object has been deleted. Instances that have been deleted in the current transaction return true.

  Transient instances return false.

  Returns:
    true if this instance was deleted in the current transaction.
  See Also:
    `JDOHelper.isDeleted(Object pc)`, `PersistenceManager.deletePersistent(Object pc)`

### jdoNewInstance

    public PersistenceCapable jdoNewInstance(StateManager sm)

  Return a new instance of this class, with the jdoStateManager set to the parameter, and jdoFlags set to LOAD_REQUIRED.

  This method is used as a performance optimization as an alternative to using reflection to construct a new instance. It is used by the JDOImplHelper class method newInstance.

  Parameters:
    `sm` - the StateManager that will own the new instance.
  Returns:
    a new instance of this class.
  See Also:
    `JDOImplHelper.newInstance(Class pcClass, StateManager sm)`

### jdoNewInstance

    public PersistenceCapable jdoNewInstance(StateManager sm,
                                             java.lang.Object oid)

  Return a new instance of this class, with the jdoStateManager set to the parameter, key fields initialized to the values in the oid, and jdoFlags set to LOAD_REQUIRED.

  This method is used as a performance optimization as an alternative to using reflection to construct a new instance of a class that uses application identity. It is used by the JDOImplHelper class method newInstance.

  Parameters:
    `sm` - the StateManager that will own the new instance.
    `oid` - an instance of the object id class (application identity).
  Returns:
    a new instance of this class.
  See Also:
    `JDOImplHelper.newInstance(Class pcClass, StateManager sm)`

### jdoNewObjectIdInstance

    public java.lang.Object jdoNewObjectIdInstance()

  Create a new instance of the ObjectId class for this PersistenceCapable class. The fields will have their Java default values.

  Returns:
    the new instance created.

### jdoNewObjectIdInstance

    public java.lang.Object jdoNewObjectIdInstance(java.lang.String str)

  Create a new instance of the ObjectId class for this PersistenceCapable class, using the String form of the constructor. The fields will have their Java default values.

  Parameters:
    `str` - the String form of the object identity instance
  Returns:
    the new instance created.

### jdoCopyKeyFieldsToObjectId

    public void jdoCopyKeyFieldsToObjectId(java.lang.Object oid)

  Copy fields from this PersistenceCapable instance to the Object Id instance.

  Parameters:
    `oid` - the ObjectId target of the key fields

### jdoCopyKeyFieldsToObjectId

    public void jdoCopyKeyFieldsToObjectId(PersistenceCapable.ObjectIdFieldSupplier fm,
                                           java.lang.Object oid)

  Copy fields from an outside source to the key fields in the ObjectId. This method is generated in the PersistenceCapable class to generate a call to the field manager for each key field in the ObjectId. For example, an ObjectId class that has three key fields (int id, String name, and Float salary) would have the method generated:

  void jdoCopyKeyFieldsToObjectId

  (ObjectIdFieldSupplier fm, Object objectId) {

  EmployeeKey oid = (EmployeeKey)objectId;

  oid.id = fm.fetchIntField (0);

  oid.name = fm.fetchStringField (1);

  oid.salary = fm.fetchObjectField (2);

  }

  The implementation is responsible for implementing the ObjectIdFieldSupplier to produce the values for the key fields.

  Parameters:
    `oid` - the ObjectId target of the copy.
    `fm` - the field supplier that supplies the field values.

### jdoCopyKeyFieldsFromObjectId

    public void jdoCopyKeyFieldsFromObjectId(PersistenceCapable.ObjectIdFieldConsumer fm,
                                             java.lang.Object oid)

  Copy fields to an outside source from the key fields in the ObjectId. This method is generated in the PersistenceCapable class to generate a call to the field manager for each key field in the ObjectId. For example, an ObjectId class that has three key fields (int id, String name, and Float salary) would have the method generated:

  void copyKeyFieldsFromObjectId

  (ObjectIdFieldConsumer fm, Object objectId) {

  EmployeeKey oid = (EmployeeKey)objectId;

  fm.storeIntField (0, oid.id);

  fm.storeStringField (1, oid.name);

  fm.storeObjectField (2, oid.salary);

  }

  The implementation is responsible for implementing the ObjectIdFieldManager to store the values for the key fields.

  Parameters:
    `oid` - the ObjectId source of the copy.
    `fm` - the field manager that receives the field values.

Overview | Package | Class | Tree | Deprecated | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD