Interface COM.odi.IPersistent

public interface IPersistent

When you run the class file postprocessor (osjcfp), the postprocessor annotates the appropriate class (the top-level class in your hierarchy) to ensure that IPersistent is implemented. You do not need to put anything special in the class definition for the class to be persistence-capable. You just need to run the postprocessor on the class. Information for running the postprocessor is in the ObjectStore Java API User Guide, Chapter 8, Automatically Generating Persistence-Capable Classes. If you run the postprocessor, which is the typical way to use ObjectStore, the rest of the information provided here is background information.

In unusual circumstances, you might choose to completely or partially manually annotate a class so that it is persistence-capable. If you do this, the requirements for implementing the IPersistent interface are described here. Additional information is in the ObjectStore Java API User Guide, Chapter 9, Manually Generating Persistence-Capable Classes.

Some Java-supplied classes are persistence-capable. Others are not and cannot be made persistence-capable, while others can be made persistence-capable, but there are important issues to consider when you do so.

In previous releases, the COM.odi.Persistent class implemented IPersistent and the class file postprocessor (osjcfp) ensured that a class extended the Persistent class. Now, the postprocessor ensures that a class implements COM.odi.IPersistent without using COM.odi.Persistent. The Persistent class is deprecated in this release and will be removed in a future release.

The IPersistent interface provides two kinds of methods.

The first group of methods handles the creation of the persistent object and the initialization of the contents of the persistent object. These are the xxxxContents() methods.

The second group of methods allows ObjectStore to retrieve and modify two fields in your class definition. If you run the postprocessor, it adds these fields to your definition. If you do not run the postprocessor, you must insert the following code in your class definition:

 transient private COM.odi.imp.ObjectReference ODIRef;
 transient public byte ODIObjectState;

The two fields are the ODIRef field, which stores a reference, and the ODIObjectState field, which holds some object state bits. The underlying runtime classes in ObjectStore access these fields through the IPersistent accessor methods as needed.

If you define a clone() method in your class, you must ensure that it correctly initializes and checks these fields when it performs a clone operation. Typically, for new cloned objects, your application should initialize ODIRef to null and ODIObjectState to zero.

The IPersistent interface supplies accessor methods (get and set) so that the classes in the COM.odi.imp package can use the ODIRef and ODIObjectState fields in a generic way without class-specific knowledge. If you do not run the postprocessor, you must add the following code to your class definition. If you run the postprocessor, it adds this code for you.

 public COM.odi.imp.ObjectReference ODIgetRef() {
    return ODIRef;
 }
 public void ODIsetRef(COM.odi.imp.ObjectReference objRef) {
    ODIRef = objRef;
 }
 public byte ODIgetState() {
    return ODIObjectState;
  }
 public void ODIsetState(byte state) {
    ODIObjectState = state;
 }
  

• In your class definition, do not specify that it implements IPersistent and do not define any IPersistent methods. Run the postprocessor on the class file. The postprocessor annotates the class so that it implements IPersistent and defines the required methods.

• In your class definition, do not specify that it implements IPersistent, but define those IPersistent methods that you want to define. For example, you might define a hook method such as preFlushContents(). Run the postprocessor on the class file. The postprocessor annotates the class so that it implements IPersistent and defines the IPersistent methods that you did not explicitly define, in addition to the methods that you did explicitly define.

• In your class definition, explicitly implement IPersistent. You must define every method defined by IPersistent. If you do not, you receive a compilation error.

In previous releases, the HashPersistent class was the superclass for classes that needed a hashCode() method based on identity. The HashPersistent class is deprecated in this release and will be removed in a future release.

clearContents()

Resets the values of the fields of an active persistent object to the default initial values of that class of object.

flushContents(GenericObject)

Stores the values of the fields of an active persistent object in an instance of GenericObject.

initializeContents(GenericObject)

Initializes the values of the fields of a hollow persistent object from data contained in an instance of GenericObject.

ODIgetRef()

Returns the value of the ODIRef field.

ODIgetState()

Returns the value of the ODIObjectState field.

ODIsetRef(ObjectReference)

Updates the value of the ODIRef field.

ODIsetState(byte)

Updates the value of the ODIObjectState field.

postInitializeContents()

Called by ObjectStore immediately after calling the initializeContents() method, which changes the state of a persistent object from hollow to active and clean.

preClearContents()

Called by ObjectStore immediately before calling the clearContents() method, which changes the state of an object from active and clean to hollow.

preDestroyPersistent()

Called by ObjectStore.destroy(object) before destruction of the specified object.

preFlushContents()

Called by ObjectStore immediately before calling the flushContents() method, which changes the state of a persistent object from active and clean or dirty to active and clean.

  public abstract void initializeContents(GenericObject genObj)

Initializes the values of the fields of a hollow persistent object from data contained in an instance of GenericObject. In other words, hollow objects become active objects with an internal clean state. ObjectStore arranges to call this method when an application calls ObjectStore.fetch() or ObjectStore.dirty() on a persistent object. Note that the postprocessor inserts these fetch() and dirty() calls where required.

If you are manually annotating a class, any implementation of this method must initialize all fields in the hollow persistent object, including any fields defined by superclasses. Initialize superclass fields by invoking initializeContents() on the superclass. This is similar to calls to superclass constructors, although in this case the superclass initialization is not enforced by the compiler.

A persistence-capable Java class can define a field that does not appear in the list of fields returned by the ClassInfo.getFields() method. Such a field is a transient-only field. The initializeContents() method that is associated with the class must initialize transient-only fields.

If you do not define this method, you can run the postprocessor to add a definition of this method for you.

Parameters:

genObj - The representation of the persistent object that the method should read the field values from.

  public abstract void clearContents()

Resets the values of the fields of an active persistent object to the default initial values of that class of object. This causes the clean active object to become a hollow persistent object.

If you are manually annotating a class, any implementation of this method must clear all fields in the persistent object, including any fields defined by superclasses. Clear superclass fields by invoking clearContents() on the superclass.

If you do not define this method, you can run the postprocessor to add a definition of this method for you.

See Also:

create

  public abstract void flushContents(GenericObject genObj)

Stores the values of the fields of an active persistent object in an instance of GenericObject. This changes the internal clean or dirty state of the persistent object to the clean state. ObjectStore arranges to call this method when a modified persistent object is evicted and when a transaction is committed.

If you are manually annotating a class, any implementation of this method must flush all fields in the persistent object, including any fields defined by superclasses. Flush superclass fields by invoking flushContents() on the superclass.

The ClassInfo.getFields() method can return a list of fields that does not include one or more fields that are in the Java class definition. Such a field is a persistent-only field. The flushContents() method associated with the class must initialize persistent-only fields.

If you do not define this method, you can run the postprocessor to add a definition of this method for you. If you define it yourself, ensure that it writes all fields, even fields that were not modified.

Parameters:

genObj - The representation of the persistent object that this method should write the field values into.

  public abstract void postInitializeContents()

Called by ObjectStore immediately after calling the initializeContents() method, which changes the state of a persistent object from hollow to active and clean. Implement this method when you want to customize behavior. For example, you can use this method to copy some persistent fields to transient state.

If you provide an implementation of this method, you should be sure to call super.postInitializeContents() for any super classes.

If you do not define this method, you can run the postprocessor, which inserts a definition of this method as a null operation. Example

  public abstract void preFlushContents()

Called by ObjectStore immediately before calling the flushContents() method, which changes the state of a persistent object from active and clean or dirty to active and clean. Implement this method when you want to customize behavior. For example, you can use this method to to copy any transient state to persistent fields before values are stored in the database as the result of an evict or commit operation.

If you provide an implementation of this method, you should be sure to call super.preFlushContents() for any super classes. If you do not define this method, you can run the postprocessor, which inserts a definition of this method as a null operation. Example

  public abstract void preClearContents()

Called by ObjectStore immediately before calling the clearContents() method, which changes the state of an object from active and clean to hollow. Implement this method when you want to customize behavior. For example, you can use this method to copy any persistent fields to transient state before the persistent state is cleared. Or, you can make transient pointers null so that the referenced objects can be garbage collected.

If you provide an implementation of this method, you should be sure to call super.preClearContents() for any super classes. If you do not define this method, you can run the postprocessor, which inserts a definition of this method as a null operation. Example

  public abstract ObjectReference ODIgetRef()

Returns the value of the ODIRef field. If you define this method, you must also define the ODIsetRef() method. If you do not define these two methods, you can run the postprocessor to insert them.

  public abstract void ODIsetRef(ObjectReference objRef)

Updates the value of the ODIRef field. If you define this method, you must also define the ODIgetRef() method. If you do not define these two methods, you can run the postprocessor to insert them.

Parameters:

objRef - The value returned by ODIgetRef().

  public abstract byte ODIgetState()

Returns the value of the ODIObjectState field. If you define this method, you must also define the ODIsetState() method. If you do not define these two methods, you can run the postprocessor to insert them.

  public abstract void ODIsetState(byte state)

Updates the value of the ODIObjectState field. If you define this method, you must also define the ODIgetState() method. If you do not define these two methods, you can run the postprocessor to insert them.

Parameters:

state - The value returned by ODIgetState().

  public abstract void preDestroyPersistent()

Called by ObjectStore.destroy(object) before destruction of the specified object. A user-defined class can override this method to destroy any internal persistent data structures that it references. For example, if a user "Btree" class has internal persistent types that represent the leaves of the tree that are not visible through its API, the Btree.preDestroyPersistent() method can be defined to remove those leaves from the database. Btree.preDestroyPersistent should not call ObjectStore.destroy(this).

If you do not define this method, you can run the postprocessor, which inserts a definition of this method as a null operation.