PersistenceCapable
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'.
- Since:
- JDO 1.0
Public Methods
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 copiedfieldNumbers
- the field numbers to be copied into this instance
- Since:
- JDO 1.0
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.
- Parameters:
oid
- the ObjectId source of the copy.fm
- the field manager that receives the field values.
- Since:
- JDO 1.0
JDOUserException
. - Parameters:
oid
- the ObjectId target of the key fields
- Since:
- JDO 1.0
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
.
- Parameters:
oid
- the ObjectId target of the copy.fm
- the field supplier that supplies the field values.
- Since:
- JDO 1.0
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.
- Return:
- 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)
- Since:
- JDO 1.0
Transient non-transactional instances return null.
This method always delegates to the StateManager if it is non-null.
- Return:
- the PersistenceManager associated with this instance.
- Since:
- JDO 1.0
If the JDO identity is being changed in the transaction, this method returns the current object id as modified in the current transaction.
- Return:
- 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)
- Since:
- JDO 1.0
- Return:
- the version
- Since:
- JDO 2.0
Transient instances return false.
- Return:
- true if this instance was deleted in the current transaction.
- See Also:
javax.jdo.JDOHelper.isDeleted(Object pc)
PersistenceManager.deletePersistent(Object pc)
- Since:
- JDO 1.0
Transient instances return false.
- Return:
- true if this instance is detached.
- See Also:
javax.jdo.JDOHelper.isDetached(Object pc)
- Since:
- JDO 2.0
Transient instances return false.
- Return:
- true if this instance has been modified in the current transaction.
- See Also:
javax.jdo.JDOHelper.isDirty(Object pc)
javax.jdo.JDOHelper.makeDirty(Object pc,String fieldName)
jdoMakeDirty(String fieldName)
- Since:
- JDO 1.0
Transient instances return false.
- Return:
- true if this instance was made persistent in the current transaction.
- See Also:
javax.jdo.JDOHelper.isNew(Object pc)
PersistenceManager.makePersistent(Object pc)
- Since:
- JDO 1.0
- Return:
- true if this instance is persistent.
- See Also:
javax.jdo.JDOHelper.isPersistent(Object pc)
PersistenceManager.makePersistent(Object pc)
- Since:
- JDO 1.0
Transient instances return false.
- Return:
- true if this instance is transactional.
- See Also:
javax.jdo.JDOHelper.isTransactional(Object pc)
PersistenceManager.makeTransactional(Object pc)
- Since:
- JDO 1.0
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.
- Since:
- JDO 1.0
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.
- Return:
- a new instance of this class.
- See Also:
JDOImplHelper.newInstance(Class pcClass,StateManager sm)
- Since:
- JDO 1.0
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).
- Return:
- a new instance of this class.
- See Also:
JDOImplHelper.newInstance(Class pcClass,StateManager sm)
- Since:
- JDO 1.0
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.
- Return:
- the new instance created.
- Since:
- JDO 1.0
For classes that use single field identity, if the parameter is of one of the following types, the behavior must be as specified:
Number
orCharacter
: 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 constructorObjectIdFieldSupplier
: the field value is fetched from theObjectIdFieldSupplier
and passed to the single field identity constructorString
: the String is passed to the single field identity constructor
- Parameters:
o
- the object identity constructor parameter
- Return:
- the new instance created.
- Since:
- JDO 2.0
- Parameters:
fieldNumber
- the field whose value is to be provided by a callback to the StateManager's providedXXXField method
- Since:
- JDO 1.0
- Parameters:
fieldNumbers
- the fields whose values are to be provided by multiple callbacks to the StateManager's providedXXXField method
- Since:
- JDO 1.0
- Parameters:
fieldNumber
- the field whose value is to be replaced by a callback to the StateManager's replacingXXXField method
- Since:
- JDO 1.0
- Parameters:
fieldNumbers
- the fields whose values are to be replaced by multiple callbacks to the StateManager's replacingXXXField method
- Since:
- JDO 1.0
- Since:
- JDO 1.0
- Parameters:
sm
- The StateManager which will own this instance, or null to reset the instance to transient state
- Throws:
- SecurityExceptionif the caller does not have JDOPermission
- See Also:
JDOPermission
- Since:
- JDO 1.0