Guide Reference Contents Previous Next Index
An Objectivity/DB federated database can be shared by Java applications and applications written in C++ or Smalltalk. Each application maps data for an object between the Objectivity/DB data types specified in the schema description for its class and data types native to the application. This chapter explains how to define a persistence-capable Java class that is compatible with an existing schema class description. You can ignore this chapter if your application doesn't interoperate with applications written in different languages.
If you develop a Java application to interoperate with applications in other languages, you must be sure that your Java classes and the corresponding classes in the other languages are all compatible with the schema of the shared federated database.
Refer to Objectivity documentation for the various languages to find out how each language adds a class description to the schema and what Objectivity/DB types each language supports.
Some field types and inheritance relationships preclude interoperability because they are not supported by all application languages. Java does not support the following characteristics; if a schema description of a class contains any of these characteristics, you cannot define a compatible Java class:
Your application can use whatever naming convention you prefer for persistence-capable Java classes. The schema identifies each class with a unique class name. A Java application also has a schema class name for each persistence-capable class. When the application reads or writes a persistent object, Objectivity for Java maps between the Java name of the object's class and the application's schema class name for the class.
If a class name in the schema is a legal Java class name, you may use the same name for the corresponding Java class, but you are not required to do so. The only requirement is that your application's schema class name is the same as the class name in the schema.
When you define a Java class corresponding to an existing schema class definition, the inheritance hierarchy for your Java class must be the same as the inheritance hierarchy reflected in schema class descriptions. In particular, the superclass for your class should be the Java class whose schema class name appears as the superclass in the class definition. You can use the Objectivity/DB objects and types browser to see the superclass specified in an existing class description.
When you define a Java class corresponding to an existing schema class definition, you should define a relationship corresponding to each relationship in the class description. You can use the Objectivity/DB objects and types browser to see the relationships in an existing class description.
Define each relationship of your Java class as described in the schema. The relationship fields of your Java class should be in the order in which the corresponding relationships appear in the class description. The related class should be the Java class whose schema class name appears in the schema class description. The following properties of the relationship should be the same in your class as in the schema:
When you define a Java class corresponding to an existing schema class definition, you should define a persistent field corresponding to each field in the class description. The fields of your Java class should have the same names as the field names in the class description; they should be declared in your class in the order in which they appear in the class description.
Because different languages support different field access control settings, you do not need to define each Java field with the same access control as appears in the schema. Instead, you should use the field access control that makes sense for your Java application and set the schema policy of your application to disregard field access control when comparing a Java class with the corresponding class description in the schema.
You must select a Java type for each field that is compatible with the corresponding Objectivity/DB data type in the class description. You can use the Objectivity/DB objects and types browser to see the Objectivity/DB type of each field in an existing class description.
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. However, each Objectivity/DB type has one or more recommended mappings; some Objectivity/DB types can be mapped to additional Java types, but these mappings are not recommended. If at all possible, you should select the Java type of a field from the recommended mappings for the Objectivity/DB type of the field.
This section groups Objectivity/DB data types according to the classification presented in Chapter 21, "Objectivity/DB Data Types". For each group of Objectivity/DB data types, a table lists the recommended mappings. When you define a Java class to be compatible with a class description in the schema, you should use these tables to select a recommended Java type corresponding to the Objectivity/DB type of each field. Any notes or warnings about potential problems appear before the corresponding table of mappings.
This section describes the Java types that are compatible with Objectivity/DB object references when the referenced class is an application-defined persistence-capable class or a persistence-capable class in the public Objectivity for Java programmer interface. Object references to Objectivity/DB internal persistence-capable classes are described in later sections.
The following table lists the recommended Java type for Objectivity/DB object-reference types.
A field whose declared Java data type is an interface is represented in the schema by the Objectivity/DB type ooRef(ooObj). As a consequence, you may map a regular or short reference to ooObj to any interface type. Of course, you should only use an interface that is implemented by some persistence-capable class.
The following table lists the Java classes that are allowed mappings for Objectivity/DB object-references to ooObj.
| Objectivity/DB Reference Types | Allowed Java Type |
|---|---|
| ooRef(ooObj) ooShortRef(ooObj) | PCinterfacewhere PCinterface is an interface (implemented by one or more persistence-capable classes) |
The following table lists the recommended Java types for each of the Objectivity/DB primitive numeric types that are used for character, integer, and floating-point data.
| Objectivity/DB Primitive Type | Recommended Java Types |
|---|---|
| int8 | byte |
| int16 | short |
| int32 | int |
| int64 | long |
| uint8 | boolean short |
| uint16 | character int |
| uint32 | long |
| uint64 | long |
| float32 | float |
| float64 | double |
| char | byte |
The schema description for a field containing a string specifies an embedded Objectivity/DB non-persistence-capable class. If a class C has a field whose type is a non-persistence-capable string class, an instance of that string class is embedded within the data for a persistent object of class C. Although Java has no way to embed one instance within the data for another, Objectivity for Java can map these embedded instances into standard Java references to Java string classes.
The following table lists the recommended Java types for each Objectivity/DB non-persistence-capable string class.
The ooVString class is intended for strings of ASCII characters only; if a string with Unicode characters is stored as an ooVString and then retrieved by an application, the retrieved string is not guaranteed to be rendered correctly. In contrast, the ooUTF8String class can represent unicode characters that will be rendered correctly on all platforms supporting unicode.
Objectivity/DB also has a persistence-capable string class, oojString, that is used only for the elements of a string array of class ArrayOfObject; you should map references to a string array to the Java type String[] as described in "Arrays". Because schema descriptions do not contain fields that are object references to the class oojString, you do not need to map such object-reference types to a Java string class except in the context of the containing array.
The schema description for a field containing date or time data specifies either an embedded Objectivity/DB non-persistence-capable class or an object-reference type for which the referenced class is an internal Objectivity/DB persistence-capable class.
If a class C has a field whose type is a non-persistence-capable date or time class, an instance of that date or time class is embedded within the data for a persistent object of class C. Although Java has no way to embed one instance within the data for another, Objectivity for Java can map these embedded instances into standard Java references to Java date or time classes. Mapping an Objectivity non-persistence-capable class to a Java class can lead to two differences between data in Java memory and the corresponding data after it has been written to the federated database:
For a discussion of these differences, see "Data in the Federated Database".
The following table lists the recommended Java types for each Objectivity/DB non-persistence-capable date and time class.
The following table lists the recommended Java types for object references to each Objectivity/DB persistence-capable date and time class.
| Objectivity/DB Object-Reference to Date or Time Class | Recommended Java Types |
|---|---|
| ooRef(oojDate) | java.util.Date java.sql.Date |
| ooRef(oojTime) | java.sql.Time |
| ooRef(oojTimestamp) | java.sql.Timestamp |
The schema description for a field containing a variable-length array specifies either an embedded non-persistence-capable Objectivity/DB array class or an object-reference type for which the referenced class is an internal Objectivity/DB persistence-capable array class.
Java preserves array identity; Objectivity/DB's persistence-capable array classes preserve identity but its non-persistence-capable array classes do not. If a non-persistence-capable array class is mapped to a Java array, array identity is lost when a Java array is written to the federated 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 Java application, the two retrieved objects will reference the different arrays.
The following table lists the recommended Java type for each Objectivity/DB non-persistence-capable array class.
A field whose declared Java data type is an interface is represented in the schema by the Objectivity/DB type ooRef(ooObj). As a consequence, you may map an array of object references to ooObj to an array of any interface type. Of course, you should only use an interface that is implemented by some persistence-capable class.
The following table lists the Java classes that are allowed mappings for Objectivity/DB non-persistence-capable array classes involving object references to ooObj.
An object reference to an Objectivity/DB array class corresponds to a Java array. In the case of an array of objects, the class of the array elements determines the appropriate Java array type.
The following table lists the recommended Java type for object references to the Objectivity/DB persistence-capable array classes.
A field whose declared Java data type is an interface is represented in the schema by the Objectivity/DB type ooRef(ooObj). As a consequence, you may map an array of object references to ooObj to an array of any interface type. Of course, you should only use an interface that is implemented by some persistence-capable class.
The following table lists the Java classes that are allowed mappings for object references to the Objectivity/DB array classes involving references to ooObj.
Guide Reference Contents Previous Next Index