Guide Reference Contents Previous Next Index
At some point during the lifetime of your Objectivity/DB application, you may find it necessary to modify the definition of one or more persistence-capable classes. The corresponding class descriptions in the schema of your federated database must be modified to be consistent with the new Java class declarations. If the federated database contains any persistent objects of the modified classes, those objects must be converted to make them consistent with the new class descriptions in the schema.
If such changes occur during the prototyping or development phases of a project, you could simply modify your Java class declarations as necessary and create a new federated database to use for test purposes or delete objects of the changed classes from your federated database. After your application is deployed, however, the federated database at each installation site will contain objects created by the application's end users. It would not be practical to delete the deployed federated database or to delete objects from it.
Objectivity/DB provides mechanisms and tools to assist you with modifying the schema, distributing the changed schema to your installation sites, and integrating the changes into their existing federated databases. In Objectivity for Java, class descriptions in the schema are changed dynamically by a running application. The schema policy of the connection determines whether such modifications are allowed.
Deployed applications typically prohibit modifications to schema descriptions. If a new version of your deployed application uses modified persistence-capable classes, you may need to deliver the new version to installation sites along with a separate "update application" that performs the necessary schema evolution. The update application can set its schema policy to permit changes to schema descriptions and then register each of the modified classes. Registering a class updates its corresponding class description in the schema. Your update application might also convert all affected objects in the federated database. Objectivity for Java can perform simple conversions for you. If you make extensive changes to a class, however, you may need to implement your own mechanism for converting the existing objects of that class.
Schema evolution is the process of modifying class descriptions in the schema of your federated database to be consistent with new Java class declarations. Schema evolution becomes necessary when you modify the Java declaration of a persistence-capable class for which a corresponding class description already exists in the schema. Updates to the schema description of a particular class can be triggered in either of two ways: automatically when the schema descriptions are needed, or under explicit control of the application. In either case, Objectivity for Java searches the schema for the application's schema class name for the class. If it finds the name, it compares the schema description associated with that name with the Java class declaration.
If the schema description is incompatible with the Java class declaration, Objectivity for Java automatically replaces the existing schema description with a new description generated from the Java class. Because schema class descriptions are shared by Java, C++, and Smalltalk applications, it is possible that the incompatibility was introduced in a different the language environment. However, the resolution of the incompatibility will be based on the Java class definition.
Ideally, schema evolution should be performed when no other processes are running. After schema evolution is complete, all processes should use class definitions corresponding to the new schema description. If this approach is not practical, you should have a plan for switching each process to the new class definition in an orderly manner.
If you change the name of your Java class, you do not need to update the class description in the schema. Instead, you just modify your application to use the same schema class name for your new Java class as it used for your old Java class. The schema will continue to use the same class name; all existing objects of the class will remain in the federated database, identified by the same schema class name with which they were created.
If you make any of the following changes to a Java class, the corresponding class description must be updated in the schema:
Class descriptions in the schema are modified automatically as needed. When Objectivity for Java needs the schema description of a Java class, it triggers a schema comparison; the schema description is updated automatically if it is found to be incompatible with the Java class declaration.
Objectivity for Java needs the schema description for a particular persistence-capable class, PCclass, when:
After you modify persistence-capable classes, you can explicitly trigger the necessary schema modifications. For example, you might write an update application to update schema descriptions for all Java classes that have been modified since the last release of a deployed application. You could deliver the update application with the new release of the deployed application. Separating schema modifications into an update application allows the deployed application to run with a schema policy that prohibits changes to schema descriptions.
To make any necessary updates to the schema's description of a persistence-capable class, you call the registerClass method of the connection object. The parameter to registerClass is the package-qualified name of the Java class that was modified. This method checks the schema descriptions of the specified class, its superclass and other ancestor classes, and all classes to which it is related based on its relationship definitions. If the class has persistent fields that reference other persistence-capable classes, registerClass checks their descriptions recursively. Any schema description that is found to be inconsistent with the corresponding Java class declaration is updated automatically.
Whenever Objectivity for Java needs a current schema description for a class (because the application is attempting to read or write an object of the class or because of an explicit call to registerClass), the existing class description in the schema is compared to the corresponding Java class declaration. Three outcomes are possible. The schema description is:
If the schema comparison detects an incompatible schema description, Objectivity for Java generates a new schema description from the Java class declaration. The content of the new descriptions is discussed in "Content of a Schema Class Description". Note that all fields in the new schema description use the default mapping for the corresponding Java type, even if the Objectivity/DB type of the field in the old schema description was an allowed mapping for the Java type.
The schema retains the original schema description for the evolved class in addition to the new one. Objectivity/DB uses the original schema description when it needs to access an object that has not been converted to the new schema description.
After a class description in the schema is changed, all objects of that class must be converted. If the class has subclasses, objects of its subclass and other descendant classes must also be converted. Object conversion is the process of converting persistent objects in a federated database to make their data consistent with the modified schema. The objects that must be converted are called the affected objects.
Objectivity for Java can perform simple conversions for you. If you make extensive changes to a class, however, you may need to implement your own mechanism for converting the existing objects of that class.
Objectivity/DB converts the persistent data of an affected object, affectedObject, as follows:
If you want to rename a field without losing data, you should evolve the class in two passes, converting the objects between the two passes. In the first schema-evolution pass, you add a new field or inline relationship with the new name. You then convert objects by copying data from the old field to the new field. In the second schema-evolution pass, you remove the old field.
However, if the only changes were to the relationship's delete or lock propagation, copying, or versioning behaviors, affectedObject retains the relationship.
During object conversion, inherited fields are treated the same as fields defined in the class of affectedObject.
When your application retrieves an affected object by scanning a storage object for all objects of the class, Objectivity/DB automatically converts the retrieved object. When you retrieve an affected object in any other way, Objectivity/DB converts the retrieved object when you call its fetch method. In either case, the conversion is performed in application memory. If the local representation of the converted object belongs to a session whose open mode is read/write, the converted object is written to the federated database immediately. If the session's open mode is read only, however, the object in the federated database remains unconverted.
You can explicitly trigger the conversion of all the affected objects in a particular storage object by calling the convertObjects method of that storage object. Doing so allows you to select the conversion granularity to federated database, database, or container.
For performance reasons, you may prefer to update objects explicitly rather than waiting for them to be converted when they are accessed. Explicit conversion eliminates the overhead of read-only sessions that convert the affected objects in memory without writing the converted objects to the federated database.
Guide Reference Contents Previous Next Index