Objectivity/DB Administration : Administration Tasks : Objectivity/DB Schema
12 
Objectivity/DB Schema
An Objectivity/DB schema defines the contents of a particular federated database by describing every class whose objects can be stored in that federated database.
This chapter describes:
General information about a federated database’s schema, including an overview of Objectivity/DB data types.
How to export and import a schema to transfer it from one federated database to another.
About Objectivity/DB Schemas
A schema is a federated database’s representation of the particular types of data that can be stored persistently in that federated database. Because objects are the fundamental units of storage for persistent data, a schema contains descriptions of the classes to which those objects belong.
Interoperability
A federated database’s schema is shared by all applications and tools that access the federated database. Because the schema is independent of any particular programming language or architecture, it can be shared by:
Applications and tools written in any of the Objectivity-supported programming languages and products.
Applications and tools compiled for any of the Objectivity-supported architectures which are combinations of hardware, operating system, and compiler on Windows, UNIX, Linux, and Macintosh platforms.
The language- and architecture-independence of the schema enables applications written in different languages and running on different platforms to interoperate (create, read, and update stored objects) in the same federated database.
Storable Classes
A federated database’s schema contains descriptions of storable classes, which are the classes that are to have objects saved persistently in the federated database. (A schema does not contain descriptions of nonstorable classes, which are classes whose instances can exist only transiently in application memory.)
Every federated database is created with a schema containing descriptions of Objectivity/DB-defined storable classes, called internal classes or system classes.
A database developer or administrator adds descriptions of application-specific storable classes to a schema to enable applications to store object of those classes in the federated database; see Mechanisms for Adding Class Descriptions to a Schema.
Every storable class in a schema is either:
A referenceable class (also called persistence-capable)
An embeddable class (also called non-persistence-capable)
Each persistent object of a referenceable class has a unique object identifier (OID), so it can be stored and found independently of other objects. Such persistent objects can be referenced by other storable objects.
In contrast, an object of an embeddable class is stored only as a part of another object. That is, the embedded object’s values are stored among the values of the object that embeds it.
Schema Class Descriptions
The description for a particular storable class contains the following information:
The name of the class.
The name of the class’s immediate superclass, if the class inherits from another storable class.
A description of every persistent attribute in the class. Persistent attributes define the values that can be stored by an object of the class. Certain attributes represent relationships to other classes.
A unique type number assigned by Objectivity/DB.
Each attribute description includes a name and a data type. The data type of an attribute may be:
One of the types described in Objectivity/DB Data Types.
An application-specific embeddable class described in the same schema.
Mechanisms for Adding Class Descriptions to a Schema
Mechanisms for adding application-specific class descriptions to a schema vary according to the Objectivity/DB product you are using.
Some products require that class descriptions be added before an application can access the federated database; furthermore, the schema class descriptions must correspond to class definitions compiled into the application.
During Objectivity/C++ application development, you can explicitly add class descriptions by running ooddlx (see Objectivity/C++ Data Definition Language).
During Objectivity/.NET for C# application development, you can design and load class descriptions using the Persistence Designer.
During Objectivity for Java application development, class descriptions are added automatically the first time you run the application.
Other products allow schema class descriptions to be added dynamically while applications are running.
You can define storable classes and add them to a schema by submitting REST requests; see Objectivity REST.
You can define storable classes and add them to a schema by executing DO statements; see Declarative Objectivity (DO) Language.
A Spark driver job may add classes to a schema automatically while writing a DataFrame.
Note:If you have a federated database with a populated schema, you can transfer that schema to another federated database; see Duplicating a Schema.
Mechanisms for Changing Class Descriptions
You can add descriptions of new storable classes to an existing schema at any time.
If you need to modify an existing class description in a schema—for example, by adding, deleting, or changing the data type of an attribute—you must choose one of the following alternatives:
Re-create the entire federated database and its schema. This is a common approach during the early stages of development when the federated database contains test data you can discard.
Modify existing class descriptions by performing schema evolution. This allows you to preserve existing persistent objects by subsequently converting them to match the new schema class descriptions.
Note:Schema evolution is supported by selected Objectivity products. See the documentation for your product.
Objectivity/DB Data Types
The schema bases its descriptions of storable classes on its own type system instead of the type system of any particular programming language. Such Objectivity/DB data types include built-in basic data types for numeric, Boolean, and character data, as well as system classes that define more complex data structures, such as strings and collections.
Objectivity/DB maintains translations between its data types and those defined by the various Objectivity-supported programming languages, so the Objectivity/DB data types can serve as a common representation across the language-specific type systems used by applications.
Note:Some features, products, or programming interfaces have limitations that prevent them from supporting the complete set of schema data types. Applications written using such interfaces cannot create or access objects with attributes of those types. Supported data types are given in the documentation for each feature, product, or programming interface.
Table 12‑1 provides an overview of the Objectivity/DB data types that are supported for the attributes of schema classes. Related types are presented as “families” identified by a logical type, such as Integer or String. Within some families, the related types are distinguished by one or both of the following characteristics:
Encoding
Representation used for a stored value of the type. Encodings are specific to the logical type—for example, Unsigned for Integer, and Utf8 for String.
Storage
Storage reserved for a value of the type. Storage is specific to the logical type—for example, B16 (16-bit) for Integers, and Variable for Strings.
 
Table 12‑1: Objectivity/DB Data Types 
Family of Data Types
Description
Boolean
Values that are either true or false
   Binary encoding
Byte
Data type for:
8-bit Boolean values
   
Character
Characters within a string
   Binary encoding
B8, B16,
B32
Data types for:
8-bit, 16-bit, and 32-bit character values.
Integer
Signed or unsigned whole numbers
   Signed encoding
 
B8, B16, B32, B64
Data types for:
Signed 8-bit, 16-bit, 32-bit, and 64-bit integer values.
   Unsigned encoding
B8, B16, B32, B64
Types support:
Unsigned 8-bit, 16-bit, 32-bit, and 64-bit integer values.
Real
Real numbers with a fractional part
   IEEE encoding
B32, B64
Data types for:
32-bit and 64-bit real (floating-point) values.
Guid
Values that are GUIDs (globally unique identifiers)
   Binary encoding
B128
Data type for:
128-bit GUID or UUID (universally unique identifier).
String
Sequences of characters
   Byte encoding
Fixed, Variable, Optimized
Data types for:
Strings that use an 8-bit character encoding such as ASCII or ISO-Latin1, and are either fixed-length, variable-length, or optimized for (but not limited to) a particular length.
   Utf8 encoding
   Utf16 encoding
   Utf32 encoding
Fixed, Variable, Optimized
Data types for:
Strings that use Unicode UTF-8, UTF-16, or UTF-32 character encoding, and are either fixed-length, variable-length, or optimized for (but not limited to) a particular length.
Date
Dates on the Gregorian calendar, with day precision
   OBJY encoding
Data type for:
4-byte date values from January 1, 0001 to December 31, 9999.
Time
Times in the 24-hour clock format, with 100-microsecond precision
   OBJY encoding
Data type for:
4-byte time values from 00:00:00.0000 (midnight) to 23:59:59.9999.
DateTime
Datetimes (timestamps) for with 100-nanosecond precision, with or without time-zone offset
   OBJY encoding
Datetime, DatetimeOffset
Data type for:
Datetime values from January 1, 0001, 00:00:00.0000000 to December 31, 9999, 23:59:59.9999999.
 
May be:
8-byte values expressed either in the local time standard or in the Coordinated Universal Time (UTC) standard.
16-byte values representing a local time in a time zone that is expressed as an offset (number of minutes between local time and UTC).
Interval
Timespans between two dates, times or datetimes, with 100 nanosecond precision
   OBJY encoding
Data type for:
8-byte interval values from 5,000,000 days to -5,000,000 days.
Reference
Object references to persistent instances of a referenceable schema class
 
Data type for:
Object references encapsulating the Objectivity/DB object identifier (OID) of a persistent object of a referenceable class described in the schema.
 
May be:
Unidirectional, to model one-way relationships between persistent objects.
Bidirectional (when paired with an inverse), to model two-way relationships between persistent objects.
 
Used as:
Values of reference attributes, to model to-one relationships.
Elements of collection attributes, to model to-many relationships.
Object
Values that are objects of embeddable schema classes
Data type for:
Embedded-object attributes. When an object is embedded, its attributes are stored among the attributes of the enclosing object.
List
Ordered groupings of potentially non-unique elements
 
Data types for:
Fixed-size or variable-size arrays of elements of any type.
To-many bidirectional or unidirectional relationships to persistent objects.
Scalable lists of references to persistent objects.
Map
Ordered or unordered groupings of unique keys that lead to potentially non-unique values
 
Data types for:
Maps whose keys are strings.
Maps whose keys are references to persistent objects.
Set
Ordered or unordered groupings of unique elements
 
Data types for:
Sets of references to persistent objects.
Exporting and Importing a Schema
You can transfer a schema from one federated database to another by exporting it from the source federated database and importing it into the destination federated database. You can transfer a schema to accomplish the following tasks:
Duplicating a Schema
Adding Classes to a Populated Schema
About Schema Export and Import Operations
Exporting an Objectivity/DB schema represents the schema in an XML document as a hierarchy of XML elements. You can export either an entire schema from a source federated database, or just the portion of the schema containing descriptions of the application-defined classes.
Importing the XML document into an Objectivity/DB federated database populates the federated database with the schema class descriptions represented in the XML document.
When you import an XML document into a destination federated database, the operation interprets the document’s XML elements as instructions for creating schema components in the destination federated database. Thus, an import operation creates new class descriptions in response to the XML elements representing a source schema.
You typically import an XML document produced by an Objectivity/DB command. However, XML documents from other sources can be imported, provided they conform to the XML Schema for Objectivity/DB described in ExportSchema.
Add-Only Policy
An import operation follows an add-only policy, which means it can create new class descriptions, but it cannot change the properties of, replace, or delete any existing description.
Schema Compatibility
When you import an XML document that represents a schema, the imported source schema must be compatible with the schema in the destination federated database. A source and destination schema are compatible when the classes they have in common are identical in all respects. An import operation checks for compatibility by comparing the classes in the represented source schema to the classes in the destination schema. Whenever a source class has the same type number as a destination class, the two classes must also have the same name and members, otherwise, they are considered to be in conflict.
Note:Schema compatibility is normally an issue only for application-defined classes. By default, Objectivity/DB internal classes are not exported, and so are not part of an imported source schema.
Duplicating a Schema
You can duplicate a schema by importing it into an empty federated database. All application-specific classes from the source federated databases are created in the destination federated database.
To duplicate a schema in an empty federated database:
1. Run ExportSchema with the -bootFile option specifying the boot file of the source federated database. Use the -outFile option to specify the output XML file.
2. Run CreateFd with appropriate options to create the destination federated database.
3. If necessary, make the output XML files available wherever the destination federated database is located.
4. Run ImportSchema with the -bootFile option specifying the destination federated database’s boot file. Use the -inFile option to specify the XML file.
Adding Classes to a Populated Schema
You can transfer new classes from one populated schema to another, provided the two schemas are compatible; see Schema Compatibility. New class descriptions are created for any source classes not already in the destination schema.
In general, you cannot mix classes of two independently developed schemas, unless there is absolutely no overlap among the type numbers of the class descriptions.
To ensure compatibility, you should adopt a policy of propagating new classes “in the same direction”—that is, new classes should always originate in a particular source federated database and be imported into the same destination federated database(s).
If the source and destination schemas are incompatible, the import step reports an error and terminates without adding classes. An error may indicate either of the following:
The source and destination schemas use inconsistent type numbers—for example, due to independent development.
Schema evolution has been performed in one of the schemas and the changes need to be propagated to the other schema.
Warning:Always make a backup of a federated database before you import into it.
To add classes from one populated schema to a populated schema in another federated database:
1. Run ExportSchema with the -bootFile option specifying the boot file of the source federated database. Use the -outFile option to specify the output XML file.
2. If necessary, make the output XML files available wherever the destination federated database is located.
3. Make a backup of the destination federated database.
4. Run ImportSchema with the -bootFile option specifying the destination federated database’s boot file. Use the -inFile option to specify the XML file.