Caution

Failure to postprocess the correct classes together can result in problem situations that appear when you try to run the application and that are hard to diagnose. There are postprocessor options that allow you to determine which classes are made persistence-capable.

This chapter discusses the following topics:

Overview of the Class File Postprocessor

Running the Postprocessor

Managing Annotated Class Files

Creating Persistence-Aware Classes

How the Postprocessor Works

Including Transient and Already Annotated Classes

Putting Processed Classes in a New Package

Creating Persistence-Capable Classes with Transient Fields

Customizing Updated Classes

Optimizing Operations That Retrieve Persistent Objects

Specifying the Number of Array Dimensions in Persistence-Capable Classes

Performing a Test Run of the Postprocessor

Using an Input File

Annotations You Must Add

Class File Postprocessor Limitations

Overview of the Class File Postprocessor

The command you use to run the class file postprocessor is osjcfp. The postprocessor provides a number of command options that allow you to tailor the results to your needs.

You can run the postprocessor on classes or class libraries that you create or that you purchase from a vendor. See COM\odi\demo\collections\README.htm for an example of making a third-party library persistence-capable.

You must explicitly postprocess or manually annotate each class that you want to be persistence-capable. The capacity for an object to be stored in a database is not inherited when you subclass a persistence-capable class.

When you postprocess or manually annotate a class, this registers the class with ObjectStore. If a class is not postprocessed or manually annotated, ObjectStore throws ClassNotRegisteredException.

This overview provides the following information:

• Description of the Annotations
  
• Description of the Process
  
• Postprocessing a Batch of Files Is Important
  
• Manual Annotation
  

• Modifying the class to implement the COM.odi.IPersistent interface.
  
• Defining methods to initialize instance fields with data from the database, writing modified fields to the database, and resetting instance fields to default values.
  
• Modifying methods to fetch the contents of persistent instances from the database as needed and to mark modified instances so their changes can be written to the database at transaction commit.
  Before an application can access the contents of a persistent object, it must call the ObjectStore.fetch() method to read the object or the ObjectStore.dirty() method to modify the object. These calls make the contents of the object available to your application. The postprocessor inserts these calls in methods of classes that it makes persistence-capable or persistence-aware.

• Defining an additional class that provides schema information about the persistence-capable class. This new class is a subclass of the COM.odi.ClassInfo class.
  

This destination directory is never the original directory, unless you specify the -inplace option. When you are in a development cycle, it is best to specify a directory other than the original directory. Doing so avoids errors and provides both a persistence-capable and a transient version of the same class.

It is not necessary to recompile all classes before iteratively running the postprocessor. The requirement is that the compiled classes be consistent.

The postprocessor tries to minimize the amount of work it does. It checks file modification times and only reprocesses those files that have changed.

Postprocessing a Batch of Files Is Important

You can use the postprocessor -inplace option to create multiple batches. When you do, there is no requirement for the separate batches to be stored in different directories.

Example of one batch

When this is the scenario, you must run the postprocessor on all of these classes at the same time. You cannot run the postprocessor on each file individually. This is because when the postprocessor operates on A, it might refer to B and C. The postprocessor must have information about B and C to correctly annotate A.

Example of two batches

Now, in a simple (one-batch) program, when you run the postprocessor, you always specify all files in your application. In this case, you do not want the postprocessor to operate on JGL because it has already been postprocessed. In fact, you probably do not have the class files that have not been postprocessed.

It is correct to run the postprocessor on only A, B, and C. This is because there is a rule: JGL classes never know about A, B, and C. After all, JGL was written, finished, and put on the shelf before A, B, and C were created.

There are two batches here:

• The first batch contains the persistence-capable JGL library. Object Design runs the postprocessor on this batch.
  
• The second batch contains your own classes, A, B, and C. You run the postprocessor on this batch.
  

Checking for correct batches

• Class B inherits from class A and either class is persistence-capable.
  
• Class A is persistence-capable or persistence-aware and it directly refers to the fields of class B, which is persistence-capable.
  

Running the Postprocessor

1. Compile the source files.
   
   
2. Run the postprocessor on the resulting class files.
   
   

Some Java-supplied classes are persistence-capable. Others are not persistence-capable and cannot be made persistence-capable. A third category of classes can be made persistence-capable, but there are important issues to consider when you do so. Be sure to read Java-Supplied Persistence-Capable Classes.

The topics discussed in this section are

• Preparing to Run the Postprocessor
  
• Requirements for Running the Postprocessor
  
• Example of Running the Postprocessor
  
• About the Postprocessor Destination Directory
  
• How the Postprocessor Interprets File Names
  
• Order of Processing
  
• How the Postprocessor Handles Duplicate File Specifications
  
• How the Postprocessor Handles Files Not Found
  
• Zip and Jar Files as Input to Postprocessor
  
• How the Postprocessor Handles Previously Annotated Classes
  
• Troubleshooting OutOfMemory Error
  
• How the Postprocessor Handles Inner Classes
  
• Creating Smaller Annotated Files
  

• A tools.zip or tools.jar entry must be in your CLASSPATH environment variable.
  
• The osji.zip or osji.jar file must be in your CLASSPATH environment variable.
  
• Also, you must update your PATH environment variable to contain the bin directory from the ObjectStore for Java distribution.
  On Windows, you might set PATH to be something like this:

  PATH=c:\jdk117\bin;c:\odi\ostore\bin;c:\odi\osji\bin;
  c:\winnt\system32;c:\winnt

  On UNIX, it would be something like this:

  PATH=/usr/ucb:/usr/bin:/opt/jdk117/bin:/opt/SUNWspro/bin:
  /opt/ODI/ostore/bin:/opt/ODI/osji/bin

• The -dest option with a destination directory for the annotated class files. This can be an absolute or relative path name. This directory must already exist when you specify it on the postprocessor command line. The postprocessor does not create it.
  You can also specify the -inplace option to instruct the postporcessor to overwrite your original class files. If you do, the -dest option is still required.

• A batch of files. A batch includes all files in your application except for already annotated files that your application refers to. You can specify
  
  • One or more .class files
    
  • One or more .zip files
    
  • One or more .jar files
    
  • One or more class names (you must specify the package names)
    
  • Any combination of the previous items
    

osjcfp -dest osjcfpout COM.odi.demo.threads.Institution Banking.zip Account.class 

Example of Running the Postprocessor

osjcfp -dest ..\osjcfpout Person.class

The postprocessor places the annotated Person.class file and the PersonClassInfo.class file in a package-relative subdirectory of the osjcfpout directory. For example, suppose the Person class package name is COM.odi.demo.people. Further suppose that the osjcfpout directory is in the \users\kim directory. The postprocessor writes the annotated class file to a file whose name is made up of the destination directory, the class package, the class name, and the .class extension. It writes the PersonClassInfo.class file to a similar location:

\users\kim\osjcfpout\COM\odi\demo\people\Person.class
\users\kim\osjcfpout\COM\odi\demo\people\PersonClassInfo.class

osjcfp -dest ..\osjcfpout Person.class
osjcfp -dest \users\kim\osjcfpout COM.odi.demo.people.Person

If you specify a destination directory in such a way that it would store the annotated class file in the same location as the unannotated class file, and you do not specify the -inplace option, the postprocessor displays an error message and terminates. It does not produce any class file output.

The postprocessor ignores classes that are rooted in the destination directory. If you try to postprocess a class that exists only in the destination directory (and you do not specify -inplace), the postprocessor reports that it cannot find the file. For example, if you specify the following command when you run osjcfp, you receive an error as shown.

setenv CLASSPATH /usr/devo/java/test:/opt/ODI/osji.zip:/optODI/tools.zip

cd /usr/devo/java/test
javac com/users/jobs/teacher.java
osjcfp -d . com.users.jobs.teacher
...
Error: Class com/users/jobs/teacher could not be found.

Typically, after you run the postprocessor, you have a transient version of a class (your original file) and a persistence-capable version of the class (in the destination directory).

If there are no errors, the postprocessor places a version of all files specified on the command line in the destination directory. The postprocessor annotates those files that require annotations and does not modify those files that do not.

How the Postprocessor Interprets File Names

If a name you specify does not end with .class, .zip, or .jar, the postprocessor assumes it is a class name delimited with periods, for example, a.b.C. The postprocessor uses the CLASSPATH environment variable or the -classpath specification on the postprocessor command line to locate the .class file, which can be in a .zip file or .jar file. (The use of the -classpath option does not affect the class path used for the execution of the postprocessor.)

Here is an example of adding the -classpath option. It assumes that you are using ObjectStore on UNIX with the JDK installed in /usr/local/JDK-1.1.

osjcfp -dest osjcfpout -classpath \
/usr/osji:/usr/local/JDK-1.1/java/lib/classes.zip:\
/usr/osji/lib/osji.zip COM.odi.demo.threads.Institution \
Banking.zip Account.class 

Order of Processing

• Annotating the class to be persistence-capable
  
• Annotating the class to be persistence-aware
  
• Copying the class to the destination directory without annotating it
  

If you specify a .class file or class name, the postprocessor processes it according to the persistence mode that is in effect when the postprocessor reaches the file name. If you specify a .zip file or .jar file the postprocessor processes all class files in the .zip file or .jar file according to the persistence mode that is in effect when the postprocessor reaches the name of the. zip file or .jar file in the command line.

osjcfp -dest osjcfpout -persistaware Tent.class Family.class \
-persistcapable Campers.zip Site.class -copyclass Weather.class

• The Tent and Family classes are persistence-aware.
  
• The Site class, its superclass if it has one other than java.lang.Object, all classes in the Campers.zip file, and any of their superclasses (other than java.lang.Object) are persistence-capable.
  
• The Weather class is not annotated and is copied as is to the destination directory.
  

If you specify the same class more than once on a command line, both specifications must resolve to the same disk location. For example, suppose you specify both Person.class and COM.odi.demo.people.Person. This is allowed only if the class path causes COM.odi.demo.people.Person to resolve to the same Person.class that is explicitly specified.

How the Postprocessor Handles Files Not Found

Zip and Jar Files as Input to Postprocessor

How the Postprocessor Handles Previously Annotated Classes

Troubleshooting OutOfMemory Error

• Set the OSJCFPJAVA environment variable to include the -mx option. For example, Solaris csh users can enter
  

        setenv OSJCFPJAVA "java -mx32m"
  
  Windows users can enter 
  
        set OSJCFPJAVA=java -mx32m
  

• Edit the osjcfp script (Solaris) or osjcfp.bat script (Windows) to incorporate the -mx option in the invocation of Java near the end of the script. On Solaris, the line to change is
  

        $OSJCFPJAVA $javaargs COM.odi.filter.OSCFP $args
  
  On Windows, the line to change is
  
        %osjcfpjava% COM.odi.filter.OSCFP %1 %2 %3 %4 %5 %6 %7 %8
  
  Add -mx32m before the COM.odi.filter.OSCFP entry. This allows the Java virtual machine to increase the heap to 32 MB. You can increase this value further if you need to.
  
  

Class Foo {
      int a;
      public class Bar {}
}

osjcfp -dest ../osjcfpout -pc Foo.class -pc Foo$Bar.class

When the postprocessor does not create a ClassInfo class, it uses the Java reflection API instead. Some of the reflection API is subject to security and access constraints that are enforced to varying degrees depending on the version of the JDK and the platform. In other words, you can use the -optimizeclassinfo option if the Java environment in which you intend to run the application does not restrict the use of the reflection API.

Managing Annotated Class Files

• The unannotated class files in the original directory
  
• The annotated class files in the destination directory
  

• When you compile source code, you must ensure that any class files the compiler reads in are unannotated class files. The compiler must find unannotated class files before it finds annotated class files with the same names.
  Note: While the above is true for simple applications, it might not be true for more complex applications. See Using the Right Class Files in Complex Applications.

• When you run your application, you must ensure that ObjectStore finds the annotated class files before it finds the unannotated class files with the same names.
  

• Specify the -classpath argument to the compiler so it finds the unannotated class files first.
  
• Modify your CLASSPATH environment variable so Java can find the annotated class files first when it runs your application.
  

• Ensuring That the Compiler Finds Unannotated Class Files
  
• Ensuring That ObjectStore Finds Annotated Class Files
  
• Using the Right Class Files in Complex Applications
  
• Alternatives for Finding the Right Files
  
• How the Postprocessor Determines Whether to Generate an Annotated Class File
  

• Through the CLASSPATH environment variable
  
• Through the -classpath argument to the compiler
  

Example 1

CLASSPATH=c:\osji\osji.zip;c:\app\osjcfpout;c:\app

javac -classpath c:\app;c:\osji\osji.zip;c:\jdk117\lib\classes.zip App.java 

void foo(COM.odi.IPersistent p) {}
void bar() { foo(new X()); } // Trying to pass an X instance to 
                  // a function that is expecting COM.odi.IPersistent

Ensuring That ObjectStore Finds Annotated Class Files

Example

• ObjectStore is installed in c:\odi\osji.
  
• You are building an application in c:\app.
  
• You create a directory named c:\app\osjcfpout to hold the annotated class files.
  

c:\app\osjcfpout;c:\app;c:\odi\osji\osji.zip 

Using the Right Class Files in Complex Applications

Independent library

• Unannotated class files for any classes in X
  
• Annotated class files for any classes that are in other batches and are referenced by classes in X
  

Classes referenced by other classes

1. Compile the source files and postprocess the class files in the first batch. (This is the batch of files that are referenced by other classes in the application.)
   
   
2. Compile the source files in the second batch. You might not want to compile all files in this batch at the same time. Specify the -classpath option to point to the annotated class files in the first batch and any unannotated class files in the second batch.
   
   
3. Run the postprocessor on the second batch. Specify a destination directory that is different from the destination directory that was specified when the postprocessor operated on the first batch. You can package the result of postprocessing the second batch in a .zip file or .jar file.
   
   

Two other alternatives are to

• Delete the contents of the destination directory before you recompile.
  
• Specify the -classpath option when you run the postprocessor, just as you did for compilation.
  

This works fine when you run the postprocessor repeatedly with the same command line. However, when you change input parameters to the postprocessor, it is a good idea to remove the previously annotated class files from the destination directory. The reason for this is that a comparison of dates might not cause a new annotated file to be generated when the specification of a new input parameter requires a new annotated file to be generated.

To force the postprocessor to overwrite existing annotated files, specify the -f or -force option when you run the postprocessor.

Creating Persistence-Aware Classes

Persistence-aware annotations require less space than persistence-capable annotations. The postprocessor only adds calls to ObjectStore.fetch() and ObjectStore.dirty() where they are needed to operate on persistent objects. When the postprocessor makes a class persistence-aware, it does not annotate that class's superclass. You only need to make a class persistence-aware, instead of copying it as is, if

• The class accesses fields of a persistence-capable class instead of using methods to access the fields.
  
• The class accesses elements of persistent arrays.
  

Specifying the Postprocessor Command Line

osjcfp -dest osjcfpout -persistaware Compute.class

No Changes to Superclasses

How the Postprocessor Works

• Ensuring Consistent Class Files
  
• Modifications to Superclasses
  
• Effects on Inheritance
  
• Location of Annotated Class Files
  
• Postprocessor Errors and Warnings
  
• Handling of Final Fields
  
• Handling of Static Fields
  
• Which Java Executable to Use
  
• Line-Number and Local-Variable Information
  
• Using a Debugger
  
• Handling of finalize() Methods
  
• Description of Postprocessor Optimizations
  

Modifications to Superclasses

Effects on Inheritance

Implementation of the IPersistent interface is mandatory for objects that you want to be persistent. You must define classes so that if they inherit from another class, it is a class that can implement IPersistent.

Problem with Object.hashCode()

This is not a problem if you never put the object into a persistent hash table or other structure that uses the hashCode() method to locate objects. If you do put them in hash tables or something similar, the hash table or other structure that relies on the hashCode() method might become corrupted when you bring the objects back from the database.

To resolve this problem, you can define your own hashCode() method and base it on the contents of the object so it returns the same thing every time. The signature of this method must be

public int hashCode()

Location of Annotated Class Files

You must create the destination directory before you specify it in an osjcfp command line. The postprocessor creates the required subdirectories in the destination directory.

For example, suppose you specify osjcfpout as the destination directory. When you run the postprocessor on the Person.class file, which is in the COM.odi.demo.people package, the postprocessor places the annotated file in

osjcfpout\COM\odi\demo\people\Person.class

Postprocessor Errors and Warnings

For any warnings from the postprocessor, you might determine that you can safely ignore the warning. In this case, you can stop the postprocessor from warning you about the field in question. To do so, specify the -quietfield option followed by the fully qualified name of the field for which you want to suppress warnings. Alternatively, you can specify -quietclass to suppress all warnings on the class.

Handling of Final Fields

Handling of Static Fields

Static fields that can hold persistent values

X.y is a static field of a type that implements COM.odi.IPersistent and that might refer to a persistent object. If this field does refer to a persistent object it must be user maintained.

Referring to a persistent object

• When you create a database, create an object of the desired type and create a database root to refer to the object. This makes the object persistent and provides a mechanism you can use to find the object.
  
• When you start a new transaction, if the object referenced by the static field is null or stale, look up the database root and set the value of the static field to the root value.
  

How can X.y be reachable from some other point? Perhaps some other persistent object or an object that is going to be persistent refers to the object that the static data member is referring to. When ObjectStore commits the transaction and performs transitive persistence, it finds the object that the static data member is referring to.

References to stale objects

Summary

class X { static OSHashtable y = new OSHashtable(); }

• X.y does not become persistent just because class X is persistence-capable or because an instance of X becomes persistent.
  
• If you want X.y to become persistent, you must make it reachable from a root through a path that does not involve a static field, for example, db.createRoot("X.y", X.y).
  
• If X.y does become persistent, you must be aware that the OSHashtable object referenced by X.y might become stale at transaction boundaries. If it does, you must update X.y to refer to a nonstale instance.
  

If the postprocessor cannot find a Java executable, it generates a Bad command or file name error message.

Line-Number and Local-Variable Information

Using a Debugger

x = foo(y.m);

You should rely on the Step over command whenever possible. However, there are situations where you must use the Step into command. If you inadvertently step into an ObjectStore method, step out of the ObjectStore code and return to your own code by doing one of the following:

• Use a Step out command.
  
• Set a breakpoint in the calling code.
  
• Use repeated Step over commands until the method returns.
  

If your persistence-capable class defines a finalize() method (Object Design recommends that it should not), the class file postprocessor inserts annotations at the beginning of the finalize() method that change the persistent object to a transient object.

Description of Postprocessor Optimizations

• For array objects in looping constructs, the postprocessor inserts the call to fetch() or dirty() only in the first loop iteration. To disable this optimization, specify the -noarrayopt option when you run the postprocessor. This causes the postprocessor to insert calls to fetch() or dirty() in every iteration.
  
• For constructors, the postprocessor does not insert full annotations that would allow constructors to handle modifications to newly constructed objects. To disable this optimization, specify the -noinitializeropt option when you run the postprocessor. This causes the postprocessor to fully annotate constructors so that they can correctly handle modifications to objects that become persistent during constructor execution.
  If your application inserts objects into ObjectStore collections during construction of the objects being inserted, you must specify the -noinitializeropt option. Doing so avoids errors in the handling of modifications to the newly constructed objects.

• For access to fields relative to this in nonstatic member methods, the postprocessor optimizes calls to fetch() and dirty(). To disable this optimization, specify the -nothisopt option when you run the postprocessor. This causes the postprocessor to insert a fetch() or dirty() call for each access to a field in this.
  

• If you call commit() or evict() while iterating over persistent array elements, specify -noarrayopt when you run the postprocessor.
  
• If you call commit() or evict() in between accesses to different fields of this, specify -nothisopt when you run the postprocessor.
  

Including Transient and Already Annotated Classes

Copying Classes to the Destination Directory

osjcfp -dest osjcfpout a.zip -copyclass b.class

You can follow the -copyclass option with one or more .class file names, class names, .jar file names, or .zip file names. This option applies to each name that follows it, until the postprocessor reaches a -pc or -pa option.

Specifying Classes to Be Copied and Classes to Be Persistence-Capable

osjcfp -dest osjcfpout -copyclass *.class -persistcapable a.class

When Can a Class Be Transient?

Any class that directly accesses A's nontransient data members must be either persistence-capable or persistence-aware. Any other class that refers to A and does not directly access nontransient data members can be transient. That is, you do not have to postprocess it.

An important exception to this is that if a class manipulates an array object that might be persistent (specifically, setting and getting array elements), that class must be annotated to be persistence-aware. However, if the code that provides access to the array is annotated to access the values of the array, you can avoid making the class persistence-aware. It is difficult to reliably implement this in the general case.

If you compile with optimization the classes that use the methods that get and set array values, the compiler might inline the get and set methods. In this case, you must make the class that uses the get and set methods persistence-aware.

Putting Processed Classes in a New Package

To help you use the -translatepackage option, this section discusses the following topics:

• Using the -translatepackage Option
  
• How the Postprocessor Applies the Option
  
• Updating References to New Package Name
  
• References to Transient and Persistent Versions of a Class
  
• References to Transient Instances of a Persistence-Capable Class
  

{ -translatepackage | -tp } orig_pkg_name new_pkg_name

For example, suppose you have the a.b.C class and you want to create the d.e.C persistence-capable class. Run the postprocessor like this:

osjcfp -dest osjcfpout -translatepackage a.b d.e C.class

osjcfp -dest osjcfpout -tp COM.odi COM.odi.beta 
COM.odi.demo.New COM.odi.Old

The postprocessor does not place the annotated file for COM.odi.demo.New in a different package because the original package name is COM.odi.demo and not just COM.odi. The postprocessor annotates COM.odi.demo.New and places it in osjcfpout\COM\odi\demo\COM.odi.demo.New.class.

How the Postprocessor Applies the Option

• All classes in the original package that are locatable by means of the CLASSPATH environment variable or the -classpath option if you specify it. The -classpath specification overrides the CLASSPATH environment variable.
  
• Files on the command line whose package name exactly matches the specification for the original package name. This is true for files processed with the -persistcapable, -persistaware, or -copyclass option.
  

Multiple option specifications

Updating References to New Package Name

The postprocessor updates the references in classes that it is currently operating on. This includes each class specified on the command line and each class found in a. zip file or .jar file that is specified on the command line.

The postprocessor cannot detect if there are .class files for which the postprocessor was not called that refer to the renamed package. You must either run the postprocessor on the complete set of class files or modify the Java source of any files that the postprocessor is not annotating.

References to Transient and Persistent Versions of a Class

It is not possible for the postprocessor to determine which references should be to persistence-capable objects. Because of this, you must code the class so it uses the full path name of the different versions of the class. This is the only way to clarify which version of the class is wanted. However, this technique works correctly only when you are operating across batches. It does not work when you are within the same batch.

Example

int n= y.z.C.countThem()

Also, it is not possible for a.b.C and a.b.D to be in the same batch, because the -translatepackage option would apply to a.b.D. This would make all of a.b.D's calls go to the persistence-capable version, which is not what you want.

Steps to follow

1. Create a utility library.
   
   This is the first batch. This library creates transient versions of the class.

2. Run the postprocessor on the first batch and specify options that put the two different versions of the class in two different packages.
   
   This step creates the persistence-capable version of the class.

3. Use the library from an application.
   
   The application is the second batch.

4. Compile the application with the annotated files of the first batch, but not the second batch, in the compiler's class path.
   
   

There is no need for the unannotated version of the class to be available at run time.

To use the annotated version of the class, even if you are using it transiently, the osji.zip or stublib.zip file must be available in the CLASSPATH at run-time. If you are only using the class transiently, it can be the stublib.zip that is available.

Creating Persistence-Capable Classes with Transient Fields

class A {
      transient java.awt.Component myVisualizationComponent;
      int myValue;
      ...
}

In your persistence-capable class, you might have transient fields that you want to be able to access outside a transaction. In this situation, you can specify the -noannotatefield or -naf option for the field when you run the postprocessor. This option prevents access to the specified field from causing fetch() and dirty() calls on the containing object. Normally, access to a transient field causes fetch() or dirty() to be called to allow the postInitializeContents() and preFlushContents() methods to convert between persistent and transient state.

Transient Fields and Serialization

On the other hand, there might be a field that must be available for object serialization, but you do not want to store that field in the database. In this situation, specify the -transientfield option for the field when you run the postprocessor. This option causes the postprocessor to treat the specified field as though it has a transient modifier, even if it does not.

Initialization of Some Transient Fields

private transient final MyField myField = new MyField();

You can create the hollow object constructor manually. For example, suppose you define the MyField class, which extends the MyFarm class:

...
public MyField(COM.odi.ClassInfo dummyClassInfo) {
      super(dummyClassInfo);
}

Alternatively, you can remove the final qualifier and initialize the transient field in an IPersistent.postInitializeContents() method.

If you include an inline initialization of a field declared to be transient and final, the postprocessor displays an error message and stops processing. If you include an inline initialization of a field declared to be transient, but not final, the postprocessor warns you about the situation and continues processing. If you determine that you can safely ignore the message, you can turn it off with the -ignoretransient option to the postprocessor.

See also Transient Fields in Persistence-Capable Classes.

Customizing Updated Classes

Implementing Customized Methods and Hook Methods

• The initializeContents() method loads real values into hollow instances of your persistence-capable class. In other words, hollow objects become active objects with an internal clean state.
  
• The flushContents() method copies values from a modified instance (active persistent object) back to the database. This changes the internal clean or dirty state of the persistent object to the clean state.
  
• The clearContents() method resets the values of an instance to the default values. This changes a clean active object to a hollow object.
  

• Implement the method yourself. If you do, the postprocessor does not add the method. However, if you implement any of the three methods listed above, you must implement all of them. Also, you must define the ClassInfo subclass, define an instance of it, and register the instance. This is because the ClassInfo instance and the three above methods must agree on the conventions for field numbering. An example of a program that implements these methods is in the COM/odi/demo/rep directory in the Rectangle.java file. See COM/odi/demo/rep/README.htm.
  
• Implement the hook method that corresponds to the method you want to customize. The postprocessor does not annotate hook methods. These hook methods provide a way to perform transient field maintenance. You might also be able to use these methods as an update mechanism for notification about a change:
  
  • postInitializeContents() - If you define this method, ObjectStore calls it immediately after it calls the initializeContents() method.
    
  • preClearContents() - If you define this method, ObjectStore calls it just before it calls the clearContents() method.
    
  • preFlushContents() - If you define this method, ObjectStore calls it just before it calls the flushContents() method.
    

Sample program with hook methods

import COM.odi.*;
/**
* PColor provides a persistent representation of colors that can be
* used with the Java AWT package. The java.awt.Color class itself
* cannot be stored persistently, because some of its internal state
* depends on the particular kind of color display being used. If a
* java.awt.Color were created on a computer that used a 24-bit-deep
* color monitor, stored in a database, and then retrieved and used 
* on a different computer that had a gray-scale monitor, it would not
* function correctly. PColor stores the color value as three
* integers, and then recreates the java.awt.Color object whenever
* the PColor object is brought into Java from persistent storage.
*
* For expository purposes, this example pretends that the value of a
* java.awt.Color object can change after the object is created. The
* real java.awt.Color class is immutable, and so the setBlue method
* below would not work, and the preFlushContents method would 
* not actually be needed.
*/
public class PColor {
/*These instance variables are stored persistently. They represent
      the color value. */
      int red;
      int green;
      int blue;
/*This instance variable is declared transient, so it is not stored
persistently. It is managed by the methods below. */
transient java.awt.Color color;
      PColor(int r, int g, int b) {
            red = r;
            green = g;
            blue = b;
            color = new java.awt.Color(r, g, b);
      }
/*When a PColor is brought into Java from persistent storage, the
      java.awt.Color object is created. Note that this method runs
      after the initializeContents, so that it can use the values
      of the persistent instance variables. */
      public void postInitializeContents() {
            color = new java.awt.Color(red, green, blue);
      }
/*When a PColor is sent out from Java to persistent storage, the
color value from the java.awt.Color object is copied into the
persistent instance variables, so that it will be saved.
Note that this method runs before flushContents, so that it
can set up the values of the persistent instance variables. */
      public void preFlushContents() {
            red = color.getRed();
            green = color.getGreen();
            blue = color.getBlue();
      }
/*When clearContents happens, this method sets the color 
instance variable to null, so that this PColor object won't be
stopping the java.awt.Color object from being reclaimed. */
      public void preClearContents() {
            color = null;
      }
/*Equality for PColor objects is the same as equality of the
underlying java.awt.Color objects. */
      public boolean equals(Object obj) {
            if (obj instanceof PColor) {
                  return color.getRGB() == ((PColor)obj).color.getRGB();
            }
            return false;
      }
      public java.awt.Color getColor() {
            return color;
      }
      public int getBlue() {
            return color.getBlue();
      }
      public int setBlue(int b) {
            color.setBlue(b);
      }
      /* and so on.... */
}

Why define one?

You should avoid performing actions in a hollow object constructor that would cause the object to be fetched. Doing so might cause infinite recursion to occur.

For example, if a class has a persistent hashCode() method, it is a bad idea to define a hollow object constructor to register the instances of the class in a hash table. Doing so would cause the hashCode() method to be called, which in turn would attempt to fetch the object.

Creation steps

1. The postprocessor selects an appropriate superclass hollow object constructor.
   
   If the superclass has an accessible constructor that takes a single COM.odi.ClassInfo argument, or if it will have one because the postprocessor will add it during this execution of the tool, the postprocessor uses that constructor. The postprocessor reports an error if it cannot find an accessible constructor.

2. The postprocessor creates a public constructor that
   
   
   • Accepts a COM.odi.ClassInfo argument
     
   • Invokes the selected superclass constructor
     
   • Initializes all persistent fields to an appropriate default state that is equivalent to the result of the clearContents() method
     

Optimizing Operations That Retrieve Persistent Objects

Caution

Procedure for Optimizing Operations

If you do this annotation, you should also add implements IPersistent to the definition of any class that is accessed with a fetch() or dirty() call. When you do this, the compiler can effectively use the multiple overloadings of the fetch() and dirty() methods, which take COM.odi.IPersistent arguments. Also, the compiler can generate more efficient code when you declare the class to implement IPersistent in your source.

Inlining Code

When using the JDK javac compiler, this occurs when you specify the -O (capital O, as in Oslo) option.

To ensure that the postprocessor functions correctly, you must do one of the following:

• Prevent the compiler from inlining code.
  
• If you add fetch() and dirty() calls to a method that is a candidate for inlining, then also annotate all the methods that call that method. A method is a candidate for inlining if it calls static, final, or private methods, or invokes methods with the super. qualification construct.
  

try {
       method body goes here 
}      catch ( SomeRuntimeExceptionThatWillNotOccur) {
            ObjectStore.fetch(this);
}

Specifying the Number of Array Dimensions in Persistence-Capable Classes

osjcfp -dest osjcfpout -a 4 Person.class Pet.class -copyclass 
Car.class

An alternative, and far more complex, way to increase the number of allowed array dimensions is to manually implement the class of the ClassInfo instance associated with the persistence-capable class.

Performing a Test Run of the Postprocessor

To perform a test run of the postprocessor, specify the -nowrite option on the command line. For example:

osjcfp -dest osjcfpout -nowrite classes.zip

osjcfp -dest osjcfpout -nowrite -verbose classes.zip

To suppress nonfatal warning messages, specify the -quiet option. The -quiet and -verbose options are mutually exclusive. The last one used on the command line applies to the entire execution. For example, the following line suppresses warning messages during the processing of all specified files because the -quiet option comes after the -verbose option.

osjcfp -dest osjcfpout -nowrite -verbose classes.zip -quiet more.zip

Using an Input File

Windows

Format

Indicate comments with a # sign. The postprocessor ignores any subsequent characters on the same line as the # sign.

Example

osjcfp @optionsAndFiles

osjcfp -dest osjcfpout @file1 -tp old.pack new.pack @file2 

1. Replaces @file1 with the contents of file1.
   
   
2. Replaces @file2 with the contents of file2.
   
   
3. Executes the command line starting with the -dest option.
   
   

Annotations You Must Add

Keep in mind that when you add even one fetch() or dirty() call to a method, the postprocessor recognizes that the method is already annotated and does not add any other fetch() or dirty() calls to that method. If you do annotate a method, be sure to add all required calls.

This section provides information about the following topics:

• Interfacing with Nonpersistent Methods
  
• Interfacing with Native Classes
  
• Annotating Subclasses
  
• Passing Arrays
  
• Implementing the Hollow Object Constructor for Some Instance Fields
  
• Using the Java Reflection API with Persistence-Capable Objects
  

If all access to persistent objects is through annotated methods (methods in persistence-capable or persistence-aware classes), then manual annotations are not required. For arrays, there is no way to define a class so that arrays of that class can only be accessed by persistence-aware classes. You must be sure to call the fetch() or dirty() method on a persistent array before passing it to a method in a nonpersistent class.

Interfacing with Native Classes

• Modify the native code to call fetch() or dirty() itself.
  
• Make the necessary fetch() and dirty() calls before calling the native method.
  

If you forget to run the postprocessor on a subclass and if the subclass is reachable from a persistent root (other than through a transient field), ObjectStore might try to migrate instances of the subclass to the database. This attempt causes an error because the subclass is not persistence-capable.

Passing Arrays

If the called method is declared to accept an array argument, the postprocessor recognizes that a fetch() call might be needed and inserts it.

Implementing the Hollow Object Constructor for Some Instance Fields

However, there might be transient nonstatic fields that have initializer expressions or fields that are treated as transient by your implementation of the ClassInfo type and the initializeContents() and flushContents() methods. In this case, you must manually implement the hollow object constructor or ObjectStore does not run the initializer. It is impossible for the postprocessor to detect such cases, and no warning message can be provided.

Using the Java Reflection API with Persistence-Capable Objects

• Call the ObjectStore.fetch() method for an object before you call any of the java.lang.reflect.Field get methods to get the value of any of the object's fields.
  
• Call the ObjectStore.dirty() method for an object before you call any of the java.lang.reflect.Field set methods to set the value of any of the object's fields.
  

Updated: 10/07/98 08:46:04