Each Content Engine object is instantiated from a Content Engine class, which is a specification for a set of objects having the same supported methods and properties. The class to which an object belongs determines the object's methods, properties, and default security. Many Content Engine classes (most notably the Document, CustomObject, Folder classes) can be subclassed by a client application; each subclass can have its own set of custom properties in addition to the properties provided by its superclass. In addition, the Content Engine also specifies abstract classes, which can neither be modified nor instantiated. Abstract classes exist as a means by which related classes can be grouped together; the properties and methods of abstract classes are inherited by concrete subclasses, from which objects can be instantiated. For information about properties, see Property Concepts.
Metadata is data that provides information about other data. To give client applications the ability to modify the metadata of classes and properties while keeping object states consistent, the Content Engine maintains two distinct sets of class and property metadata, immutable (fixed) metadata and mutable (alterable) metadata, which are represented by two sets of objects: class description and property description objects, and class definition and property definition objects.
Class description and property description objects describe, using read-only properties, Content Engine class and property metadata that cannot be changed by an application. Because these objects must maintain a fixed metadata "snapshot" in order to avoid the potential for unstable metadata when the relationships and hierarchies of objects change, a parallel set of objects exist for the purpose of allowing the modification of class and property metadata: class definition and property definition objects. These objects define, using read/write properties, the Content Engine class and property metadata that can be modified by a client application. Only classes and properties that can be subclassed or modified by an application have a corresponding class definition or property definition whose properties you can modify. Once the metadata for a given class or property has been changed and persisted in its class definition and property definition objects by an application and a stable metadata state has been obtained by the Content Engine server, the server updates the appropriate class description and property description objects in the object store with the new metadata state.
You cannot update metadata and then use that updated metadata in a single batch transaction. For example, if you attempt to create a document subclass, save it, and then create a document from the new subclass within the same user-initiated batch transaction, the operation will fail; you must first create a new subclass in one transaction and then use the new subclass in another transaction. For more information about batch transactions, see Batch Concepts.
For more information about class descriptions, see Class Descriptions. For more information about class definitions, see Class Definitions.
Every Content Engine object that is an instance of an EngineObject subclass has a class description. A class description describes the metadata of a specific Content Engine class that cannot be modified by an application. Each class description is represented by a ClassDescription object with a unique Id and SymbolicName property value and is contained in the ClassDescriptionSet unordered set referenced by an object store's ClassDescriptions property. For performance reasons, if a client application needs to retrieve a particular class description, it is highly recommended that it obtain it directly from the appropriate object's ClassDescription property or use the Factory.ClassDescription.fetchInstance method instead of iterating through the class descriptions returned by an object store's ClassDescriptions property.
Within each ClassDescription object is a PropertyDescriptionList ordered list referenced by the PropertyDescriptions property, which holds all of the property descriptions for a class. Each property description describes the fixed, immutable metadata of a specific object property and is represented by a PropertyDescription object. When an object is instantiated from a class, the property description metadata forms the basis for that object's properties. For more information about property descriptions, see Property Descriptions.
The following class description properties describe some of the read-only metadata of a class (note that all class description properties are read-only):
Once an object has been instantiated, the metadata of the class to which it belongs can be accessed from the ClassDescription object returned by its ClassDescription object-valued property. Because ClassDescription objects can only be modified by the server, all of its properties (including all of the PropertyDescription objects returned by its PropertyDescriptions property) are read-only.
A client application can use a ClassDescription object in the following primary ways:
Because the ClassDescription object is itself a Content Engine object and (like all other Content Engine classes) is an instance of a subclass of the top-level EngineObject class, all ClassDescription objects have a ClassDescription property, which returns the ClassDescription object that describes the ClassDescription class. To prevent infinite recursion, the ClassDescription property of the ClassDescription object for the ClassDescription class returns null.
Class descriptions are heavily used by metadata-driven applications; because they are cached both on the client and on the server, their retrieval is much faster than that of class definitions.
For every Content Engine class that can be modified by a client application, the Content Engine provides a class definition that holds its mutable class metadata. Each class definition in the object store is defined by an object instance of a ClassDefinition subclass. The class definitions for root classes are available directly from the ClassDefinitionSet unordered set referenced by an object store's RootClassDefinition property. All other class definitions can be found in the collection returned by the appropriate class definition's ImmediateSubclassDefinitions property (or, if necessary, the collection returned by those class definitions' ImmediateSubclassDefinitions property, and so on). For example, the class definition for the WorkflowDefinition class is located in the collection returned by the ImmediateSubclassDefinitions property of the class definition for the Document class in the collection returned by an object store's RootClassDefinition property. For performance reasons, if a client application needs to retrieve a particular class definition, it is highly recommended that it use the Factory.ClassDefinition.fetchInstance method instead of iterating through the class definitions returned by an object store's RootClassDefinitions property.
Within each class definition object is a PropertyDefinitionList ordered list referenced by the PropertyDefinitions property, which holds all of the property definitions for a class. Each property definition is represented by a PropertyDefinition object that defines the metadata of a specific object property that an application can modify. For more information about property definitions, see Property Definitions.
For example, because a Document class can be modified by an application, both a class description and class definition with a symbolic name of Document exist in the object store. Although the class description cannot be modified, you can modify properties, subclass, and add property definitions to the class definition.
The following class definition properties define some of the read/write metadata of a class (all properties are read/write unless otherwise noted):
The ClassDefinition class has four subclasses: SubscribableClassDefinition, VersionableClassDefinition, DocumentClassDefinition, and EventClassDefinition. Their usage is summarized below:
Therefore, depending on the specific class that it defines, a class definition in the ClassDefinitionSet collection object will be either a SubscribableClassDefinition, DocumentClassDefinition, or EventClassDefinition object.
The Content Engine supports the definition of a new class by subclassing certain existing classes. When a new class is created, the class from which it has been subclassed becomes the immediate superclass of the new class. The new subclass automatically inherits all of the methods and properties supported by its immediate superclass. The identifier of the subclass can neither be an identifier of the immediate superclass nor any of its superclasses. Multiple subclasses can be derived from a single superclass and each new subclass, therefore creating a hierarchy of increasingly specialized classes.
The definition of a subclass can differ from that of its superclass in the following ways:
Although every Content Engine object can be an instance of only one class, it can conform to many class definitions, because it possesses all the properties and supports all the methods required by each successive superclass of its class, up to and including its base class. Every subclass contains an ordered list of property descriptions in which the inherited properties appear first, in the order listed in its superclass, followed by the properties added in the subclass.
For an application to be able to subclass a given class, the following criteria must be met:
If these criteria have been met, an application can create a new subclass by following these steps:
Symbolic Names
The symbolic name of a class is required to be unique within an object store. Starting with the 4.5.1 release, a metadata prefix-naming convention for class and property symbolic names has been defined for the P8 Content Engine. All new classes and properties introduced in this release or later, by any IBM® ECM product that produces its own Content Engine feature AddOn, or by new system properties in the Content Engine server, are required to adhere to this naming convention. Note that this naming convention applies to class and property symbolic name values only; there are no constraints on the values chosen for display names.
Details of the prefix-naming convention are given below:
Starting with the 4.5.1 release, any IBM ECM product that produces its own feature AddOn will also conform to a prefix-naming convention. These feature AddOns will use a prefix of "Cm???", in which "???" represents a short product-name abbreviation. However, any IBM ECM products that have already established their own prefix-naming convention prior to this release will continue to use it instead.
The following list of AddOn metadata prefixes are reserved:
When you create a new class or custom property, avoid assigning its symbolic name with a value beginning with one of these reserved prefixes; as long as you do so, you will not be subject to name collisions in this release or in any future upgrades.
There are two types of properties in the Content Engine: system properties and custom (user-defined) properties. System properties are properties that are integral to the functionality of the Content Engine and cannot be removed or added to other classes. Custom properties are properties that an application can add to a class to provide a means of customizing existing classes or new subclasses. To determine whether a given property is a system or custom property, read the value of the IsSystemOwned property of the property's PropertyDescription or PropertyDefinition object.
For an application to be able to add custom properties to a given class, the following criteria must be met:
If these criteria have been met, the class is user extensible and an application can add user-defined properties to a class by following these steps:
The Content Engine allows a client application to instantiate certain classes into objects.
For an application to be able to instantiate a given class, the following criteria must be met:
If these criteria have been met, an application can create an object instance of a class by following these steps:
There are two main categories of classes in the Content Engine: classes that represent independent objects and classes that represent dependent objects.
An independent object has the following characteristics
A dependent object has the following characteristics:
In addition to being independent, an object can also be persistable (that is, allow an application to save its state to the database). An object that is both an independent object and a persistable object belongs to a class that is a subclass of the IndependentlyPersistableObject class and is considered to be an independently persistable object. These objects implement the save and delete methods, which allow an application to directly create, update, or delete them.
A dependent object that belongs to an independently persistable object (via an object-valued property) is considered to be a dependently persistable object. A dependently persistable object has no independent existence; it does not implement the save and delete methods and its state can only be saved when the independently persistable object to which it belongs is saved.
For example, a ClassDefinition object is an independently persistable object because the class to which it belongs is a subclass of the IndependentObject and IndependentlyPersistableObject classes. Assuming you have the proper permissions, you can directly save a ClassDefinition object using its save method or delete it using its delete method. By contrast, a PropertyDefinition object is a dependently persistable object because the class to which it belongs is a subclass of the DependentObject class, and therefore it has neither a save nor a delete method. A PropertyDefinition object exists only as an object in the PropertyDefinitionList collection object referenced by a ClassDefinition object's PropertyDefinitions property, and can only be saved when the ClassDefinition object to which it belongs is saved. In addition, a PropertyDefinition object is deleted when the ClassDefinition object to which it belongs is deleted.
Another example of an independent object is a ClassDescription object, because it is an instance of an IndependentObject subclass. However, it is not independently persistable because it is not an instance of an IndependentlyPersistableObject subclass (and therefore it has neither a save nor a delete method). Similarly, because a ClassDescription object cannot be persisted by a client application, any dependent objects belonging to it, such as a PropertyDescription object, are not dependently persistable.
The Content Engine server creates and stores timestamps on all persistent objects using Coordinated Universal Time (UTC) time. Use the following procedure in your client application to calculate time-relating strings:
The Content Engine server stores the date and time, in UTC, when the object was created or modified.
For data and time values that a client application can input, such as the properties of a date-valued property template or property definition:
The Content Engine server stores the date and time values in UTC.
Each client application determines local time using the system clock of the machine on which it is installed.
If a federated Document class is changed to a native Content Engine Document class and that document is deleted on the Content Engine server, it will also be deleted on Image Services. However, if an Image Services Annotation class is changed to a native Content Engine Annotation class, a deletion of an annotation on the Content Engine server will not be propagated to Image Services.