javax.jdo.spi
Interface PersistenceCapable
public interface PersistenceCapable
A class that can be managed by a binary-compatible JDO implementation
must implement this 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, deleted, or detached; and to get its associated
PersistenceManager, object identity, and version 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'.
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.
|
void | jdoCopyFields(Object other, int[] fieldNumbers) - Copy field values from another instance of the same class
to this instance.
|
void | jdoCopyKeyFieldsFromObjectId(PersistenceCapable.ObjectIdFieldConsumer fm, Object oid) - Copy fields to an outside consumer from the key fields in the ObjectId.
|
void | jdoCopyKeyFieldsToObjectId(Object oid) - Copy fields from this PersistenceCapable instance to the Object Id
instance.
|
void | jdoCopyKeyFieldsToObjectId(PersistenceCapable.ObjectIdFieldSupplier fm, Object oid) - Copy fields from an outside source to the key fields in the ObjectId.
|
Object | jdoGetObjectId() - Return a copy of the JDO identity associated with this instance.
|
PersistenceManager | jdoGetPersistenceManager() - Return the associated PersistenceManager if there is one.
|
Object | jdoGetTransactionalObjectId() - Return a copy of the JDO identity associated with this instance.
|
Object | jdoGetVersion() - Return the version of this instance.
|
boolean | jdoIsDeleted() - Tests whether this object has been deleted.
|
boolean | jdoIsDetached() - Tests whether this object has been detached.
|
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(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, 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.
|
Object | jdoNewObjectIdInstance() - Create a new instance of the
ObjectId class for this PersistenceCapable class and initialize
the key fields from the instance on which this method is called.
|
Object | jdoNewObjectIdInstance(Object o) - Create a new instance of the class used for JDO identity, using the
key constructor of the object id class.
|
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.
|
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.
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;.
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.
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.
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.
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.
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.
SERIALIZABLE
public static final byte SERIALIZABLE
If jdoFieldFlags for a field includes SERIALIZABLE,
then the field is not declared as TRANSIENT.
jdoCopyFields
public void jdoCopyFields(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.
other
- the PC instance from which field values are to be copiedfieldNumbers
- the field numbers to be copied into this instance
jdoCopyKeyFieldsFromObjectId
public void jdoCopyKeyFieldsFromObjectId(PersistenceCapable.ObjectIdFieldConsumer fm,
Object oid)
Copy fields to an outside consumer 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
ObjectIdFieldConsumer
to store the values for the
key fields.
fm
- the field manager that receives the field values.oid
- the ObjectId source of the copy.
jdoCopyKeyFieldsToObjectId
public void jdoCopyKeyFieldsToObjectId(Object oid)
Copy fields from this PersistenceCapable instance to the Object Id
instance. For classes using single field identity, this method always
throws JDOUserException
.
oid
- the ObjectId target of the key fields
jdoCopyKeyFieldsToObjectId
public void jdoCopyKeyFieldsToObjectId(PersistenceCapable.ObjectIdFieldSupplier fm,
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.
For classes using single field identity, this method always
throws
JDOUserException
.
fm
- the field supplier that supplies the field values.oid
- the ObjectId target of the copy.
jdoGetObjectId
public 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.
- a copy of the ObjectId of this instance as of the beginning of the transaction.
PersistenceManager.getObjectId(Object pc)
, PersistenceManager.getObjectById(Object oid, boolean validate)
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.
- the PersistenceManager associated with this instance.
jdoGetTransactionalObjectId
public 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.
- a copy of the ObjectId of this instance as modified in the transaction.
jdoGetObjectId()
, PersistenceManager.getObjectId(Object pc)
, PersistenceManager.getObjectById(Object oid, boolean validate)
jdoGetVersion
public Object jdoGetVersion()
Return the version of this instance.
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.
- true if this instance was deleted
in the current transaction.
javax.jdo.JDOHelper.isDeleted(Object pc)
, PersistenceManager.deletePersistent(Object pc)
jdoIsDetached
public boolean jdoIsDetached()
Tests whether this object has been detached.
Instances that have been detached return true.
Transient instances return false.
- true if this instance is detached.
javax.jdo.JDOHelper.isDetached(Object pc)
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.
- true if this instance has been modified in the current transaction.
javax.jdo.JDOHelper.isDirty(Object pc)
, javax.jdo.JDOHelper.makeDirty(Object pc, String fieldName)
, jdoMakeDirty(String fieldName)
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.
- true if this instance was made persistent
in the current transaction.
javax.jdo.JDOHelper.isNew(Object pc)
, PersistenceManager.makePersistent(Object pc)
jdoIsPersistent
public boolean jdoIsPersistent()
Tests whether this object is persistent.
Instances that represent persistent objects in the data store
return true.
- true if this instance is persistent.
javax.jdo.JDOHelper.isPersistent(Object pc)
, PersistenceManager.makePersistent(Object pc)
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.
- true if this instance is transactional.
javax.jdo.JDOHelper.isTransactional(Object pc)
, PersistenceManager.makeTransactional(Object pc)
jdoMakeDirty
public void jdoMakeDirty(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.
fieldName
- the name of the field to be marked dirty.
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.
sm
- the StateManager that will own the new instance.
- a new instance of this class.
JDOImplHelper.newInstance(Class pcClass, StateManager sm)
jdoNewInstance
public PersistenceCapable jdoNewInstance(StateManager sm,
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.
sm
- the StateManager that will own the new instance.oid
- an instance of the object id class (application identity).
- a new instance of this class.
JDOImplHelper.newInstance(Class pcClass, StateManager sm)
jdoNewObjectIdInstance
public Object jdoNewObjectIdInstance()
Create a new instance of the
ObjectId class for this PersistenceCapable class and initialize
the key fields from the instance on which this method is called.
This method creates a new instance of the class used for JDO identity.
It is intended only for application identity. If the class has been
enhanced for datastore identity, or if the class is abstract,
null is returned.
For classes using single field identity, this method must be called
on an instance of a persistence-capable class with its primary key
field initialized (not null), or a
JDONullIdentityException
is thrown.
The instance returned is initialized with the value(s) of the
primary key field(s) of the instance on which the method is called.
- the new instance created.
jdoNewObjectIdInstance
public Object jdoNewObjectIdInstance(Object o)
Create a new instance of the class used for JDO identity, using the
key constructor of the object id class. It is intended for single
field identity. The identity
instance returned has no relationship with the values of the primary key
fields of the persistence-capable instance on which the method is called.
If the key is the wrong class for the object id class, null is returned.
For classes that use single field identity, if the parameter is
of one of the following types, the behavior must be as specified:
Number
or Character
: the
parameter must be the single field
type or the wrapper class of the primitive field type; the parameter
is passed to the single field identity constructor
ObjectIdFieldSupplier
: the field value
is fetched from the ObjectIdFieldSupplier
and passed to the
single field identity constructor
String
: the String is passed to the
single field identity constructor
o
- the object identity constructor parameter
- the new instance created.
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.
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.
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.
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.
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.
jdoReplaceStateManager
public void jdoReplaceStateManager(StateManager sm)
throws 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.
sm
- The StateManager which will own this instance, or null
to reset the instance to transient state