Class COM.odi.Persistent

java.lang.Object
   |
   +----COM.odi.Persistent

public class Persistent

extends Object

implements IPersistent

• Subclasses of Persistent and COM.odi.util.HashPersistent. Normally, you run the Class File Postprocessor to annotate your class so that it inherits from one of these classes. In rare situations, you can explicitly define your class to inherit from one of these classes.

• String

• The Java primitive wrapper classes: Boolean, Character, Double, Float, Integer, and Long

Instances of String and of the Java primitive wrapper classes cannot be modified and do not maintain their identity when they are migrated into a database.

Under rare circumstances, you might explicitly define a class that inherits from the Persistent or HashPersistent class in your source code.

Normally, after you compile code that defines a class that you want to store persistently, you run the Class File Postprocessor to make the class persistence-capable. One of the annotations that the postprocessor adds to your code is that it makes your class or a superclass inherit from the COM.odi.Persistent or COM.odi.util.HashPersistent class. The postprocessor chooses the base class by examining the class being updated and any derived classes. If any of these classes are nonabstract and inherit the hashCode() method from java.lang.Object, then the postprocessor makes the COM.odi.util.HashPersistent class the base class. Otherwise, COM.odi.Persistent becomes the base class.

Regardless of how your class comes to inherit it, the Persistent class is an abstract base class. It provides the API for defining classes whose instances you can store in a database. Most of the time it is the postprocessor that implements this API.

If you do explicitly define a class to inherit from Persistent then your subclass must define the initializeContents(), clearContents(), and flushContents() methods. Also you must register a subclass of the ClassInfo class. Additional information about these annotations is available in the user documentation for manually creating persistence-capable classes.

You can often specify null where a persistent object is required.

See Also:

ClassInfo, GenericObject, migrate

clearContents()

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

clone()

Clones the persistence-capable object.

deepFetch(Object)

This method is similar to fetch() in that it obtains the contents of a persistent object and makes them available for read access by the application.

destroy()

Deprecated.

dirty(Object)

Obtains the contents of a persistent object and allows the contents to be modified and saved in the database.

fetch(Object)

Obtains the contents of a persistent object and makes them available for read access by the application.

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.

isDestroyed()

Deprecated.

isStale()

Deprecated.

postInitializeContents()

Called by PSE/PSE Pro immediately after calling the initializeContents method.

preClearContents()

Called by PSE/PSE Pro immediately before calling the clearContents method.

preDestroyPersistent()

Hook for ObjectStore.destroy(object).

preFlushContents()

Called by PSE/PSE Pro immediately before calling the flushContents method.

  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. PSE/PSE Pro arranges to call this method when an application calls fetch() or dirty() on a persistent object. Note that the postprocessor inserts these fetch() and dirty() calls where required.

If you are manually annotating a class then the method that overrides 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.

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 object to become a stale persistent object.

If you are manually annotating a class then the method that overrides 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.

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. PSE/PSE Pro arranges to call this method when a modified persistent object is evicted and when a transaction is committed. A persistent class definition always defines a method to override this one. Normally, the postprocessor defines this method for you. If you write it yourself, ensure that it writes all fields, even fields that were not modified.

If you are manually annotating a class then the method that overrides 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.

Parameters:

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

  public void postInitializeContents()

Called by PSE/PSE Pro immediately after calling the initializeContents method. Implement this method when you want to customize behavior.

  public void preFlushContents()

Called by PSE/PSE Pro immediately before calling the flushContents method. Implement this method when you want to customize behavior.

  public void preClearContents()

Called by PSE/PSE Pro immediately before calling the clearContents method. Implement this method when you want to customize behavior.

  public static void fetch(Object object)

Obtains the contents of a persistent object and makes them available for read access by the application. A program must call this method before it tries to read any fields in the persistent object. If it does not call this method first, the application might be reading uninitialized data. Normally, the Class File Postprocessor inserts these calls. After running your program, you might decide to try to improve performance by inserting some fetch() calls yourself. See "Optimizing Operations That Retrieve Persistent Objects" in Chapter 9 of the API User Guide.

After an object has been fetched in a transaction, it need not have the fetch() method invoked on it again, unless the object has been explicitly evicted by the ObjectStore.evict() method or the transaction has been committed.

An application must be careful not to modify the contents of an object on which it called the fetch() method. PSE/PSE Pro does not prevent an application from modifying a fetched object. However, PSE/PSE Pro does not allow the application to save the modifications in the database. To modify an object, an application must call the dirty() method on that object and have the changes saved by committing the transaction. If an application calls fetch() on a transient object, PSE/PSE Pro ignores the call.

Parameters:

object - The object whose contents must be be fetched. The object must be persistence-capable.

Throws: DatabaseNotFoundException

If the object was accessed through a cross-database reference to a database that is not found.

Throws: NullPointerException

If the object argument is null.

Throws: ObjectNotFoundException

If the object was destroyed, or its segment was destroyed.

Throws: ObjectNotPersistenceCapableException

If the object is not persistence-capable.

  public static void deepFetch(Object object)

This method is similar to fetch() in that it obtains the contents of a persistent object and makes them available for read access by the application. In addition to obtaining the contents of object, this method also fetches all objects reachable from object. object must be persistent. If this method encounters any transient objects, it migrates them to the segment that contains object. This automatic migration is a temporary restriction. In a future release, it will be possible to pass a transient object as an argument and objects will not be migrated as a side-effect of a deepFetch operation. This automatic migration also means that the preFlushContents hooks for a method may be called during a deepFetch.

Parameters:

object - The object at which the deepFetch begins. This object must be persistent.

Throws: ObjectStoreException

If object is transient or ObjectStore is not initialized yet.

Throws: ObjectNotFoundException

If the object was destroyed, or its segment was destroyed.

Throws: ObjectException

If the object is stale.

  public static void dirty(Object object)

Obtains the contents of a persistent object and allows the contents to be modified and saved in the database. An application must call this method on each persistent object that it wants to update in the database. Also, the application must call this method before it tries to access the contents of the object. If it does not, it might be accessing uninitialized data. Normally, the Class File Postprocessor inserts these calls. After running your program, you might decide to try to improve performance by inserting some dirty() calls yourself. See "Optimizing Operations That Retrieve Persistent Objects" in Chapter 9 of the API User Guide.

If an application calls dirty() on a transient object, PSE/PSE Pro ignores the call.

Parameters:

object - The object being accessed for modifications. The object must be persistence-capable and modifiable. That is, it cannot be an instance of a String or an instance of a Java primitive wrapper class.

Throws: DatabaseNotFoundException

If the object was accessed through a cross-database reference to a database that is not found.

Throws: NullPointerException

If the object argument is null.

Throws: ObjectNotFoundException

If the object was destroyed, or its segment was destroyed.

Throws: ObjectNotPersistenceCapableException

If the object is not persistence capable.

Throws: UpdateReadOnlyException

If the database is open read-only or there is a read-only transaction in progress.

  protected Object clone() throws CloneNotSupportedException

Clones the persistence-capable object. The object itself must have been fetched, since it is meaningless to clone an object when it has no contents. The clone is always initially transient, but it can become persistent by means of the usual persistence mechanisms.

Returns:

The cloned object.

Throws: CloneNotSupportedException

If the subclass of Persistent does not implement the Cloneable interface.

Overrides:

clone in class Object

  public void destroy()

Note: destroy() is deprecated. ObjectStore.destroy() should be used instead.

  public void preDestroyPersistent()

Hook for ObjectStore.destroy(object). If ObjectStore.destroy(object) is called on an object, this method is called before the object argument is actually destroyed. A user class may override this method in order to destroy any internal persistent data structures that it references. For example, if a user "Btree" class has internal persistent types representing the leaves of the tree which are not visible via its API, the Btree.preDestroyPersistent method may be defined to remove those leaves from the database. Btree.preDestroyPersistent should not call ObjectStore.destroy(this).

The default implementation of this method does nothing.

  public boolean isStale()

Note: isStale() is deprecated. ObjectStore.isStale() should be used instead.

  public boolean isDestroyed()

Note: isDestroyed() is deprecated. ObjectStore.isDestroyed() should be used instead.