Guide  Reference  Contents  Previous  Next  Index

Schema Management

An Objectivity/DB federated database has a schema that describes every class whose objects are saved in the federated database. The schema is shared by all applications that access the federated database. The schema description for a class specifies the name of the class and the data type of each persistent field. The schema uses class names and field data types that are independent of the application source language. This language-independent representation allows applications written in Java, C++, and Smalltalk to read and write persistent objects in the same federated database.

When a Java application writes an object to the federated database, the object's persistent data in memory is mapped from Java data types to the corresponding Objectivity/DB data types specified in the schema. When a Java application reads an object, the object's persistent data in the federated database is mapped from the Objectivity/DB data types to the corresponding types declared in the Java class.

This chapter introduces schema policies, explains how Java applications add class descriptions to the schema, and describes the language-independent class name and field data types used in a class description in the schema.

In This Chapter

Schema Policies

Adding Class Descriptions to the Schema

Adding Descriptions Automatically

Adding Descriptions Explicitly

Content of a Schema Class Description

Schema Class Names

Default Mapping for Java Types

Schema Policies

Each language has its own mechanism for adding class descriptions to the schema. In the case of Java, descriptions are added dynamically by a running application. The schema policy of the connection determines whether descriptions can be added to the schema. If so, class descriptions can be added automatically by Objectivity for Java or explicitly by the application.

A schema policy is an object of a class that implements the SchemaPolicy interface. Every connection has an associated schema policy that controls what kinds of modifications the application can make to the schema. Properties of the schema policy specify whether:

• New class descriptions can be added to the schema.

• Existing class descriptions in the schema can be modified. (Modifications to class descriptions are discussed in Chapter 15, "Schema Evolution and Object Conversion".)

• A field's access control is considered in testing whether its description is the same in the schema and the Java class declaration.

• Informational messages are printed.

• The policy is locked, preventing its properties from being changed.

When you open a connection, the connection's schema policy is unlocked and it allows your application to add class descriptions to the schema and to change existing descriptions. The schema policy requires a field's access control to be the same in the schema and the Java class declaration. Informational messages related to the schema are printed. If you want to change the schema policy in any way, you must call methods of the schema policy.

To obtain the schema policy that governs your application, you call the getSchemaPolicy method of the connection object. You can call methods of the schema policy to get and set its properties.

During the prototyping or development phases of a project, you should not need to change the schema policy. However, you may want to modify the schema policy in a deployed application.

• You may want to prohibit deployed applications from modifying the class descriptions in the schema.

• If you initialize the schema of an empty federated database for delivery to installation sites, you may want to prohibit your deployed application from adding class descriptions to the schema.

• If your application needs to interoperate with applications written in C++ or Smalltalk, you may need to prohibit applications from modifying the class descriptions in the schema; modifications made by a Java application could result in a class description with Objectivity/DB data types that are not supported by C++ or Smalltalk applications.

• If your application needs to interoperate with applications written in C++ or Smalltalk, you may need to allow the access control of fields in the schema to be different from the access control in the Java class declarations. For example, if a class description in the schema was created by a C++ program, the access control of the fields will be the access control specified by the C++ program; you may need to use different access control for corresponding fields of your Java class.

• You may prefer to print only error messages related to the schema in a deployed application.

• You may prefer for the schema policy to be locked in a deployed application. Once the policy is locked, it cannot be unlocked or modified in any way.

This code fragment sets the schema policy in a deployed application immediately after the application opens a connection to the federated database.

    ...
    Connection connection = Connection.open(...);
    SchemaPolicy policy = connection.getSchemaPolicy();
    // Prohibit addition of new class descriptions
    policy.setCreateClassAllowed(false);
    // Prohibit modification of existing class descriptions
    policy.setChangeClassAllowed(false);
    // Allow access control to be different in schema and Java class
    policy.setFieldAccessControlEnforced(false);
    // Use terse messages
    policy.setVerbose(false);
    // Lock the schema policy
    policy.setPolicyLocked();

Adding Class Descriptions to the Schema

Class descriptions can be added to the schema in either of two ways: automatically as they are needed, or under explicit control of the application. If informational messages are enabled, the schema manager will print a message whenever a new class description is added to the schema.

The class description will contain the application's schema class name for the class and field descriptions corresponding to the persistent fields of the Java class. For details, see "Content of a Schema Class Description".

Adding Descriptions Automatically

A Java application does not need to take any explicit action to add class descriptions to the schema; they are added automatically when they are needed. Objectivity for Java needs to have a schema description for a particular persistence-capable class, PCclass, when:

• An instance of PCclass is made persistent.

• The application scans a storage object for persistent objects of the class PCclass.

• The description of a subclass of PCclass is added to the schema.

• The description of another class is added to the schema and that class references PCclass in a persistent field.

• The description of another class is added to the schema and that class has a relationship in which PCclass is the related class.

• An index is defined for objects of PCclass.

• A subclass of PCclass is added to the schema for any of the above reasons.

When Objectivity for Java needs a class description, it searches the schema for the application's schema class name for the class. If it finds the name, it uses the class description associated with that name. If not, it automatically adds a new class description to the schema.

Adding Descriptions Explicitly

You can add class descriptions to the schema explicitly before any objects of the class are made persistent. For example, you might initialize the schema of an empty federated database to contain class descriptions of all persistence-capable classes used by an application. You could then deliver the empty federated database to the various installation sites when you deploy the application. When the deployed application adds persistent objects to the federated database, their class descriptions will already exist in the schema; you may want to disable the deployed application from adding more class descriptions to the schema, as described in "Schema Class Names".

To add the description of a persistence-capable class to the schema, call the registerClass method of the connection object. The parameter to registerClass is the package-qualified name of the Java class whose description is to be added. This method adds to the schema the descriptions of the specified class, its superclass, and all its other ancestor classes. If the class has persistent fields that reference other persistence-capable classes, registerClass adds their descriptions recursively.

This code fragment adds descriptions of four classes to the schema: Truck (whose Java class name is the parameter to registerClass), Vehicle (the superclass of Truck), RentalFleet (which is referenced from the fleet field of Vehicle), and Fleet (the superclass of RentalFleet).

    ...
    Connection connection = Connection.open(...);

    package RentalFleet.Vehicles;
        ...
    public class Truck extends Vehicle {
        ...

    public class Vehicle extends ooObj {
        // Persistent fields
        RentalFleet fleet;
        ...

    public class RentalFleet extends Fleet {
        ...

    public class Fleet extends ooObj {
        ...
    }

Content of a Schema Class Description

When a Java application adds a class description to the schema, either automatically or with a direct call to registerClass, the new class description contains a class name, the name of the class's superclass, an ordered collection of field descriptions, and an ordered collection of relationship descriptions.

• The class name in the schema is the application's schema class name for the class at the time when the class description was added to the schema.

• The name of the superclass in the schema is the application's schema class name for the Java superclass.

• The fields described in the schema are the persistent fields of the Java class, in the same order as they appear in the Java class declaration. Each field description specifies the field's name, data type, and access control. The field's:
  • Name in the schema is the same as the Java field name.

  • Objectivity/DB data type in the schema is the default mapping for the Java type of the field.

  • Access control (public, protected, or private) in the schema is the same as the access control of the Java field. Java fields with a default access control are mapped to private in the schema.

• The relationships described in the schema are the relationships of the Java class, in the same order as the corresponding relationship fields appear in the Java class declaration. Each relationship description specifies the same information as the relationship definition method of the Java class. The:
  • Relationship name in the schema is the same as the Java relationship name.

  • Name of the related class in the schema is the application's schema class name for the related Java class.

  • Name of the inverse relationship (if any) is the same in the schema as in Java.

  • Relationship's directionality and cardinality, its delete and lock propagation behavior, and its copying and versioning behavior are all the same in the schema as in Java.

Schema Class Names

The schema identifies each class with a unique class name that is set when the class description is added to the schema.

An Objectivity for Java application associates a schema class name with each persistence-capable class whose objects it read or writes. The schema class name is the name of the corresponding class in the federated database schema.

If two applications use different schema class names for the same class, the schema will contain two descriptions of the class, one with the schema class name used by the first application and one with the schema class name used by the second application. The federated database will consider the two classes to be distinct.

Whenever a Java application reads or writes a persistent object, Objectivity for Java maps between the name of the object's persistence-capable Java class and the schema class name for that class. The default mapping creates a schema class name from the package-qualified name of a Java class. An application can override the default for any class by registering a custom schema class name for that class.

Default Schema Class Name

Objectivity for Java creates a default schema class name from the package-qualified name of the class, using the underscore character (_) as the separator between package names and the unqualified class name. For example, the package-qualified class name of the Java class Truck in the package Vehicles within the package RentalFleet is:

    RentalFleet.Vehicles.Truck

That Truck class has the default schema class name:

    RentalFleet_Vehicles_Truck

Default schema class names are appropriate for most applications that interoperate only with other Java applications. However, you should register custom schema class names under the following circumstances:

• If your application interacts with applications written in different languages, you may want to use a custom schema class name for any persistence-capable class that your application adds to the schema.

• If your application accesses persistent objects of a class that is already in the schema, it needs to use the existing schema class name for that class. If the existing name is different from the default, you must register the existing name as the custom schema class name for the class. This situation arises when the class was added to the schema by a C++ or Smalltalk application or by a Java application that registered a custom schema class name.

• If any persistence-capable class is nested deeply in packages with long names, so that its default schema class name exceeds the 487-character limit, you should define a custom schema class name.

Custom Schema Class Name

When you register a custom schema class name for a class, you instruct Objectivity for Java to map the Java class name to the custom schema class name instead of to the default schema class name. The mapping remains in effect throughout the particular connection in which you register the custom schema class name.

The default schema class names are unnatural to C++ and Smalltalk applications because the Objectivity/DB interfaces for those languages do not have the notion of qualified name spaces analogous to Java's packages. If your application interoperates with applications written in different source languages, you can facilitate interoperability by using a custom schema class name for the persistence-capable classes that your application adds to the schema.

To register a custom schema class name for a persistence-capable class, call the setSchemaClassName method of the connection object, specifying the Java class and its custom schema class name.

The setSchemaClassName method defines the application's mapping between the Java class name and the schema class name; it does not directly modify the schema. The mapping remains in effect only during the current connection; it is never stored explicitly in the federated database.

This code fragment registers a custom schema class name for the Java class RentalFleet.Vehicles.Truck, overriding the default name (RentalFleet_Vehicles_Truck) with the custom name Truck.

    Connection connection = Connection.open(...);
    connection.setSchemaClassName(
    // Package-qualified name of class
            "RentalFleet.Vehicles.Truck",
    // Custom schema class name
            "Truck");

Remember that all applications must use the same schema class name for a given class. For example, an application that uses the custom name Truck will read and write objects identified in the federated database as Truck objects. If a second application uses the default name RentalFleet_Vehicles_Truck, it will read and write a completely different set of objects, which are identified in the federated database as RentalFleet_Vehicles_Truck objects.

Default Mapping for Java Types

Objectivity/DB supports a wide range of data types for persistent data. A given Objectivity/DB type may be mapped to more than one Java data type. A given Java data type may be mapped to more than one Objectivity/DB data type. However, each Java type has a single default, preferred mapping.

When a Java application adds a class description to the schema, the Objectivity/DB data type of each persistent field in the class description is set to the default mapping for the field's Java data type.

The tables in the following subsections give the default mappings of Java types to Objectivity/DB types. For a description of the Objectivity/DB field data types, see Chapter 21, "Objectivity/DB Data Types".

Java Primitive Types

The following table shows the default mapping of Java primitive types to Objectivity/DB types. Note that a Java primitive type is always mapped to a Objectivity/DB primitive type (never to an Objectivity/DB class).

Java Primitive Type	Default Objectivity/DB Type
byte	int8
short	int16
int	int32
long	int64
boolean	uint8
char	uint16
float	float32
double	float64

Java Classes

The following table shows the default mapping of Java classes to Objectivity/DB types. With the exception of the two Java string classes, the default representation for a Java class is an object reference to an internal persistent object of an internal Objectivity/DB class. As a consequence, object identity is usually preserved when data is transferred between a Java application and a database.

Java Class	Default Objectivity/DB Type
String	ooUTF8String
StringBuffer	ooUTF8String
java.util.Date	ooRef(oojDate)
java.sql.Date	ooRef(oojDate)
java.sql.Time	ooRef(oojTime)
java.sql.Timestamp	ooRef(oojTimestamp)
AppClass, where AppClass is an application-defined persistence-capable class whose schema class name is PCclass.	ooRef(PCclass)
APIclass, where APIclass is a persistence-capable class defined in the public Objectivity for Java programming interface (such as ooContObj or ooMap).	ooRef(APIclass)
PCinterface where PCinterface is an interface (implemented by one or more persistence-capable classes).	ooRef(ooObj)

Java Array Types

The following table shows the default mapping of Java arrays to Objectivity/DB types.

Java Array Type	Default Objectivity/DB Type
byte[]	ooRef(oojArrayOfInt8)
short[]	ooRef(oojArrayOfInt16)
int[]	ooRef(oojArrayOfInt32)
long[]	ooRef(oojArrayOfInt64)
boolean[]	ooRef(oojArrayOfBoolean)
char[]	ooRef(oojArrayOfCharacter)
float[]	ooRef(oojArrayOfFloat)
double[]	ooRef(oojArrayOfDouble)
String[]	ooRef(oojArrayOfObject) where array elements are of type oojString
java.util.Date[]	ooRef(oojArrayOfObject) where array elements are of type oojDate
java.sql.Date[]	ooRef(oojArrayOfObject) where array elements are of type oojDate
java.sql.Time[]	ooRef(oojArrayOfObject) where array elements are of type oojTime
java.sql.Timestamp[]	ooRef(oojArrayOfObject) where array elements are of type oojTimestamp
AppClass[], where AppClass is an application-defined persistence-capable class whose schema class name is PCclass.	ooRef(oojArrayOfObject) where array elements are of type ooRef(PCclass)
APIclass[], where APIclass is a persistence-capable class in the public Objectivity for Java programmer interface (for example, ooContObj or ooMap).	ooRef(oojArrayOfObject) where array elements are of type ooRef(APIclass)
PCinterface[], where PCinterface is an interface (implemented by one or more persistence-capable classes).	ooRef(oojArrayOfObject) where array elements are of type ooRef(ooObj)

The default representation for every Java array type is an object reference to an internal persistent object of an internal Objectivity/DB array class. As a consequence, array identity is preserved when data is transferred between a Java application and a database. For example, suppose that two Java objects reference the same array in persistent fields. If the two objects are saved in the database and later read by a second Java application, the two retrieved objects will also reference the same array. A change in the elements of the array will affect both referencing objects.

Guide  Reference  Contents  Previous  Next  Index