com.odi
Class ClassInfo

java.lang.Object
  com.odi.ClassInfo

public abstract class ClassInfo

extends Object

ClassInfo is an abstract class that PSE/PSE Pro uses to manage the schema information for persistence-capable classes. Normally, the Class File Postprocessor arranges to define a ClassInfo subclass, if the persistence-capable class is private or if the -nooptimizeclassinfo option is specified, 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 implement ClassInfo yourself, you do not need to be familiar with this class.

For each class that inherits from the PSE/PSE Pro Persistent class, or OSHashPersistent class there must be a subclass of 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 persistence-capable class 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 }
     ...
    }

 public class PersonClassInfo extends ClassInfo {
    public Persistent create() { return new Person(null, 0, null); }
    public Class getClassDescriptor() {
       return Person.class;
    }
    public Field[] getFields() { return fields; }
       private static Field[] fields = {
         Field.createString("name");
         Field.createInt("age");
         Field.createClassArray("children", "com.odi.demo.people.Person", 1);
       }
    }
 

See the API User Guide, for additional information about Defining a ClassInfo Subclass.

See Also:

Persistent, Field

Method Summary

abstract IPersistent	create() Creates a default instance of the persistence-capable class associated with this instance of ClassInfo.
static ClassInfo	get(Class theClass) Obtains the class-specific information for the specified IPersistent class.
static ClassInfo	get(String className) Obtains the class-specific information for the specified IPersistent class.
boolean	getAllowsPeerQueries() Determines whether instances of the associated class may be accessed by queries on com.odi.coll collections.
abstract Class	getClassDescriptor() Obtains the class object for the persistence-capable class with which this instance of ClassInfo is associated.
abstract Field[]	getFields() Gets the array of fields for the persistence-capable class associated with this instance of ClassInfo.
static void	noteIndexableField(String fieldName) Notes a field as being indexable for OSJI.
static void	notePersistentField(String fieldName) Notes a field as needing to be part of the schema for the class despite its transient declaration.
static void	noteTransientField(String fieldName) Notes a field as needing to be excluded from the schema for the class even though the field has not been declared transient.
static ClassInfo	register(ClassInfo classInfo) Registers a class as persistence-capable with PSE/PSE Pro by providing an instance of its associated ClassInfo subclass.
static void	remove(String className) Removes a persistence-capable class from the registry.
void	setAllowsPeerQueries() Specifies that instances of the associated class may be accessed by queries on com.odi.coll collections.

Method Detail

create

public abstract IPersistent create()

Creates a default instance of the persistence-capable class associated with this instance of ClassInfo. PSE/PSE Pro calls 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 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:

IPersistent.initializeContents(com.odi.GenericObject)

getClassDescriptor

public abstract Class getClassDescriptor()
                                  throws ClassNotFoundException

Obtains the class object for 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 calls 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.

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 or postInitializeContents() 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.

Chapter 9 in the API User Guide provides additional information for defining a getFields() method. See Defining a ClassInfo Subclass.

Returns:

The array of fields for the persistence-capable class associated with this instance of ClassInfo.

See Also:

Field

register

public static ClassInfo 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 should be in a static expression in the persistence-capable class.

For example:

 class Person extends Persistent {
 ClassInfo personClassInfo = new PersonClassInfo();
 static {
    ClassInfo.register(personClassInfo);
 }
 ...
 }
 

Parameters:

classInfo - The instance of the subclass of ClassInfo.

Returns:

The ClassInfo input argument

Throws:

NullPointerException - If the classInfo argument is null.

SchemaException - If the persistence-capable class associated with the specified ClassInfo subclass does not exist.

getAllowsPeerQueries

public final boolean getAllowsPeerQueries()

Determines whether instances of the associated class may be accessed by queries on com.odi.coll collections. Only meaningful in ObjectStore.

Returns true if the class has indexable fields or if setAllowsPeerQueries() has been called with a true argument. If this method returns false, then instances of this class should not be navigated through in queries on com.odi.coll collections. In particular, if use of immediate Strings has been enabled with the com.odi.permitImmediateStrings session initialization property, then com.odi.coll queries will not correctly interpret the immediate string values. Queries on com.odi.util collections are not affected by this problem.

Returns:

True if instances the class may be accessed by queries on com.odi.coll collections, otherwise false.

See Also:

ClassInfo.setAllowsPeerQueries()

setAllowsPeerQueries

public final void setAllowsPeerQueries()

Specifies that instances of the associated class may be accessed by queries on com.odi.coll collections. Only meaningful in ObjectStore.

If the class is not marked as allowing peer queries, either because this method has not been called, or because the class does not contains indexable fields, then instances of this class should not be navigated through in queries on com.odi.coll collections. In particular, if use of immediate Strings has been enabled with the com.odi.permitImmediateStrings session initialization property, then com.odi.coll queries will not see the immediate string values. Queries on com.odi.util collections are not affected by this problem.

See Also:

ClassInfo.getAllowsPeerQueries()

get

public static ClassInfo get(String className)

Obtains the class-specific information for the specified IPersistent class. 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 IPersistent class, including the package name.

Returns:

The instance of the ClassInfo subclass that was registered for the specified IPersistent class. This value is never null.

Throws:

ClassNotRegisteredException - If the associated ClassInfo instance is not found.

IllegalArgumentException - If the className argument is null.

get

public static ClassInfo get(Class theClass)

Obtains the class-specific information for the specified IPersistent class.

Parameters:

theClass - The IPersistent class.

Returns:

The instance of the ClassInfo subclass that was registered for the specified IPersistent class. This value is never null.

Throws:

ClassNotRegisteredException - If the associated ClassInfo instance is not found.

IllegalArgumentException - If theClass 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.

notePersistentField

public static void notePersistentField(String fieldName)

Notes a field as needing to be part of the schema for the class despite its transient declaration. If susbsequently ClassInfo must be created for it via the reflection API, the field will be included as part of the schema for the class.

Parameters:

fieldName - The fully qualified name of the field that must be treated as persistent.

Throws:

SchemaException - If the schema for the class is already known and the field had been excluded from the schema.

noteTransientField

public static void noteTransientField(String fieldName)

Notes a field as needing to be excluded from the schema for the class even though the field has not been declared transient.

Parameters:

fieldName - The fully qualified name of the non-transient field that is to be assumed transient.

Throws:

SchemaException - If the schema for the class is already known and the field had been included in the schema.

noteIndexableField

public static void noteIndexableField(String fieldName)

Notes a field as being indexable for OSJI.

Parameters:

fieldName - The fully qualified name of the indexable field.

Throws:

SchemaException - If the schema for the class is already known and the field had been included in the schema.