|
|
This chapter describes the SPI data model. It includes the following sections:
External system data is represented by two primary types:
To address and access data, both Nodes and ObjectClasses have a unique ID. The ID contains both the repository name and an opaque repository-specific (String) UUID. Generally, from an SPI implementor’s perspective, the UUID is the only field in the ID that should be examined and all data should be tied to the repository-specific UUID rather than to the ID. However, you need to construct the ID as the SPI needs to return data. The repository name is assigned by the VCR, as it receives the object from the SPI.
| Note: | The UUID field must never be null, as this value is reserved for the repository root ID. |
Nodes have a unique implicit hierarchical path from the repository root that ends with the node name. You can retrieve nodes based on this path. For example, a node with name “foo” might be available at repository path /someNode/anotherNode/foo.
From an SPI implementor’s perspective, all paths start with the repository root node, that is /foo. In contrast from a VCR client perspective, all paths start with the repository name, that is /SomeRepo/foo. The VCR manages this path modification.
The special path “/” is reserved for representing the repository root and the special ID UUID=null is reserved for repository root ID. The repository root is an artificial address construct for retrieving the top-most nodes in a repository. You cannot directly fetch the root node, but you can retrieve its children.
Figure 2-1shows an overview of the SPI data model.
An ObjectClass defines the schema for a Node (that is, what kind of data a node of that type can contain). Besides the schema, the ObjectClass contains a name and ID that uniquely identifies the Node within the repository, plus an array of property definitions that describe the data (Properties) that a Node of that type can hold. For example, you could create a type “City” with property definitions for “population” (String) and “image” (binary).
ObjectClasses support, but do not require, type-inheritance. A type City may inherit from type Location, thus receiving property definitions from Location. Single inheritance is supported. Additionally, ObjectClasses support, but do not require, type nesting, which is a containment structure. This allows you to construct a hierarchy of Node data rather than a flat list of properties.
An ObjectClass contains a PropertyDefinition that defines the schema for a single Property that can exist on a Node of that objectClass. This is actually the schema for a named piece of data. The primary fields in it include:
A PropertyDefinition may define a set of PropertyChoices that you can use to provide some predefined values. For example, a String property may have a set of property choices, one for each state.
A PropertyChoice can be demarcated as default. When a node is created, if the associated property has no value, it is created with the default PropertyChoice value.
A Node represents a set of external system data. A Node has a name, and you can address a node using a unique hierarchical path (ending with its name), or a unique ID.
If a node has a type, then you can include a set of Property values that hold external system data. The set of Properties available depends on the node’s type (ObjectClass). For example, if Node myNode is of type City, and City has PropertyDefinitions for size and image, the myNode can have a property called size and another called image, with values for each of these properties.
Nodes also have implicit system metadata including:
A Property represents a named piece of external system data. It exists as part of a Node object. Each Node can have multiple properties providing its ObjectClass defines multiple properties. A Property has a name that maps up to a PropertyDefinition on the node’s ObjectClass with the same name.
Properties may have zero or more Values. The schema for the property values depends on the associated PropertyDefinition. For example, if Node myNode is of type City, and City has property definitions for size (String) and image (binary), then myNode can have a property called “size” with a string value, and another called “image”, with a binary value.
A Value represents an unnamed piece of external system data. It exists as part of a Property object. A Property may have multiple values if its PropertyDefinition is multi-valued. The Value contains the real value of the data type specified on the property’s PropertyDefinition. For example, if the “Person” ObjectClass has a “favoriteColors” PropertyDefinition (a multi-valued String), a node of type “Person” can have a Property named “favoriteColors” that contains zero or more string Values. Valid value types are:
A BinaryValue represents an unnamed piece of external system binary data. It exists as part of a Value object. There can be only one BinaryValue object per Value object. In addition to an InputStream, the BinaryValue also includes metadata:
BinaryValues are generally loaded on-demand for better performance.
|