Class COM.odi.ClassInfo

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

public class ClassInfo
extends Object

ClassInfo is an abstract class that PSE/PSE Pro for Java uses to manage the schema information for persistence-capable classes. Normally, the Class File Postprocessor defines the ClassInfo subclass, creates an instance, and inserts calls to ClassInfo methods where required. You run the postprocessor after you compile your source files. However, under exceptional circumstances, you might want to implement this yourself. Unless you do the ClassInfo implementation yourself, you do not need to be familiar with this class.

For each class that inherits from the PSE/PSE Pro Persistent class, there is a class that subclasses the ClassInfo class. Subclasses of the ClassInfo class provide information about the associated persistence-capable class. PSE/PSE Pro needs this schema information to manage the object. If you do implement ClassInfo yourself, here is an example that shows the definition of a Persistent subclass followed by the definition of a ClassInfo subclass for the newly-defined persistence-capable class:

      package COM.odi.demo.people;
	class Person extends Persistent {
	  String name;
	  int age;
	  Person children[];
	  public Person(String name, int age, Person children[])
	  {  this.name = name; this.age = age; this.children = children }
        ...
	}
	class PersonInfo extends ClassInfo {
	  public Persistent create() { return new Person(null, 0, null); }
	  public Object[] createArray(int nDimensions, int sizeOfOuterDimension)
	    throws BadArrayDimensionsException {
	    switch (nDimensions) {
	    case 1:
	      return new Person[sizeOfOuterDimension];
	    case 2:
	      return new Person[sizeOfOuterDimension][];
	    default:
	      throw new BadArrayDimensionsException(nDimensions);
	    }
	  }
        public Class getClassDescriptor() throws ClassNotFoundException {
          return Class.forName("COM.odi.demo.people.Person");
        }
        public Field[] getFields() { return fields; }
	  private static Field[] fields = {
	    Field.createString("name");
	    Field.createInt("age");
	    Field.createClassArray("children", "COM.odi.demo.people.Person", 1);
	  }
	}

The user guide provides additional information for defining a subclass of ClassInfo.

See Also:: Persistent, Field

create(): Creates a default instance of the persistence-capable class associated with this instance of ClassInfo.
createArray(int, int): Creates an array of references to instances of the persistence-capable class associated with this instance of ClassInfo.
get(String): Obtains the class-specific information for the specified Persistent subclass.
getClassDescriptor(): Obtains the run time descriptor of the persistence-capable class with which this instance of ClassInfo is associated.
getFields(): Gets the array of fields for the persistence-capable class associated with this instance of ClassInfo.
icreate(): This method is overridden by persistence-capable objects that do not inherit from COM.odi.Persistent.
register(ClassInfo): Registers a class as persistence-capable with PSE/PSE Pro by providing an instance of its associated ClassInfo subclass.
remove(String): Removes a persistence-capable class from the registry.

create

  public abstract Persistent create()

Creates a default instance of the persistence-capable class associated with this instance of ClassInfo. An application must call this method the first time it makes an instance of a persistence-capable class addressable. When you define a create() method that overrides this one, it must set all of the associated persistence-capable class's nonstatic reference fields to null. PSE/PSE Pro sets the proper values for each field when it calls the initializeContents() method on an instance of the persistence-capable class.

For example:

	class Person extends Persistent {
	  String name; int age; Person children[];
	  ...
	}
	class PersonInfo extends ClassInfo {
	  public Persistent create() { return new Person(null, 0, null); }
	  ...
	}

Returns:: A default instance of the persistence-capable class associated with this instance of ClassInfo.
See Also:: initializeContents

icreate

  public IPersistent icreate()

This method is overridden by persistence-capable objects that do not inherit from COM.odi.Persistent. It's contract is identical to that of create() above, except that it returns an instance of IPersistent. Ideally we would modify create to return IPersistent, but we don't to stay link compatible with applications that preceded IPersistent.

createArray

  public abstract Object[] createArray(int nDimensions,
                                       int sizeOfOuterDimension) throws BadArrayDimensionsException

Creates an array of references to instances of the persistence-capable class associated with this instance of ClassInfo. If you define a createArray() method that overrides this one, ensure that it creates an array of the appropriate depth and size or that it throws BadArrayDimensionsException.

For example:

	class PersonInfo extends ClassInfo {
	  public Object[] createArray(int nDimensions, int sizeOfOuterDimension)
	    throws BadArrayDimensionsException {
	    switch (nDimensions) {
	    case 1:
	      return new Person[sizeOfOuterDimension];
	    case 2:
	      return new Person[sizeOfOuterDimension][];
	    default:
	      throw new BadArrayDimensionsException(nDimensions);
	    }
	  }
	  ...
	}

Parameters:: nDimensions - The number of dimensions in the array being created.; sizeOfOuterDimension - The size of the first dimension you specify.
Returns:: An array of references to instances of the persistence-capable class associated with this instance of ClassInfo.
Throws: BadArrayDimensionsException: If nDimensions exceeds the number of dimensions supported by the implementation of createArray().

getClassDescriptor

  public abstract Class getClassDescriptor() throws ClassNotFoundException

Obtains the run time descriptor of the persistence-capable class with which this instance of ClassInfo is associated.

Returns:: The Class object for the persistence-capable class associated with this instance of ClassInfo.
Throws: ClassNotFoundException: If the class was not found.

getFields

  public abstract Field[] getFields()

Gets the array of fields for the persistence-capable class associated with this instance of ClassInfo. If you define this method, the order that you specify for the fields determines the index numbers used by the Persistent.initializeContents() and Persistent.flushContents() methods, which PSE/PSE Pro calls as needed on the persistence-capable class.

For example:

	class PersonInfo extends ClassInfo {
	  public Field[] getFields() { return fields; }
	  private static Field[] fields = {
	    Field.createString("name");
	    Field.createInt("age");
	    Field.createClassArray("children", "Person", 1);
	  }
	  ...
	}

The definition of the ClassInfo.getFields() method specifies a create method for each field that you want to access in a persistent object. PSE/PSE Pro does not require an exact match between each field in the Java class definition and each field created by the getFields() method.

If a field is present in both the Java class definition and the result of the getFields() method, then the two definitions must exactly match.

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.

The 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.

An example of how you might use transient-only and persistent-only fields is in the demo directory that is included in PSE/PSE Pro. In the rep example, Rectangle.a and Rectangle.b are transient-only fields, while ax, ay, bx, and by are persistent-only fields.

The user guide provides additional information for defining a getFields() function.

Returns:: The array of fields for the persistence-capable class associated with this instance of ClassInfo.
See Also:: Field

register

  public static void register(ClassInfo classInfo)

Registers a class as persistence-capable with PSE/PSE Pro by providing an instance of its associated ClassInfo subclass. Typically, an application calls this method the first time it loads an instance of the associated persistence-capable class. A call to this method is in a static expression in the persistence-capable class.

For example:

 class Person extends Persistent {
 static {
    ClassInfo.register(new PersonInfo());
 }
 ...
 }

Parameters:: classInfo - The name of the subclass of ClassInfo.
Throws: NullPointerException: If the classInfo argument is null.
Throws: SchemaException: If the persistence-capable class associated with the specified ClassInfo subclass does not exist.

get

  public static ClassInfo get(String className)

Obtains the class-specific information for the specified Persistent subclass. If this persistence-capable class has not yet been loaded into the Java Virtual Machine, a call to this method causes the class to be loaded. This invokes user-defined handlers as needed.

Parameters:: className - The fully qualified name of the Persistent subclass, including the package name.
Returns:: The instance of the ClassInfo subclass that was registered for the specified Pesistent subclass. This value is never null.
Throws: ClassNotRegisteredException: If the associated classInfo is not found.
Throws: NullPointerException: If the className argument is null.

remove

  public static void remove(String className)

Removes a persistence-capable class from the registry.

Parameters:: className - The fully qualified name of a Persistent subclass. Be sure to include the package name in the specification.
Throws: NullPointerException: If the className argument is null.