Each Content Engine object is instantiated from a Content Engine class, which is a specification for a set of objects that have 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 cannot be modified or instantiated. Abstract classes exist as a means by which related classes can be grouped; 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 it keeps 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, by 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 to avoid the potential for unstable metadata when the relationships and hierarchies of objects change, a parallel set of objects exist for allowing the modification of class and property metadata: class definition and property definition objects. These objects define, by 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. After the metadata for a particular class or property is changed and persisted in its class definition and property definition objects by an application and a stable metadata state that is 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 fails; 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 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 that are returned by an object store's ClassDescriptions property.
Within each ClassDescription object is a PropertyDescriptionList ordered list that is 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):
After an object is instantiated, the metadata of the class to which it belongs can be accessed from the ClassDescription object that is returned by its ClassDescription object-valued property. Because ClassDescription objects can be modified only by the server, all of its properties (including all of the PropertyDescription objects that are 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 recursion, the ClassDescription property of the ClassDescription object for the ClassDescription class returns null.
Class descriptions are used heavily 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 an object store is defined by an instance of a ClassDefinition subclass. For each root class, a corresponding class definition is available directly from the ClassDefinitionSet object that is referenced by the object store's RootClassDefinitions property. For all other (non-root) classes, the class definition for a class is found in the collection that is returned by the ImmediateSubclassDefinitions property of the class definition of its immediate superclass. Consider, for example, the WorkflowDefinition class. Because the Document root class is its immediate superclass, the class definition for the WorkflowDefinition class is in the ClassDefinitionSet collection that is returned by the ImmediateSubclassDefinitions property of the Document class definition. In turn, the class definition of the Document class is in the ClassDefinitionSet collection that is returned by the ObjectStore object's RootClassDefinitions property.
For performance reasons, if a client application needs to retrieve a particular class definition, it is recommended that it use the Factory.ClassDefinition.fetchInstance method instead of iterating through the class definitions that are returned by an object store's RootClassDefinitions property.
Within each class definition object is a PropertyDefinitionList ordered list that is 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 as follows:
Therefore, depending on the specific class that it defines, a class definition in the ClassDefinitionSet collection object is 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 is subclassed becomes the immediate superclass of the new class. The new subclass automatically inherits all of the methods and properties that are supported by its immediate superclass. The identifier of the subclass cannot be an identifier of the immediate superclass or 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 the definition 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 that are 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 that is listed in its superclass, followed by the properties added in the subclass.
For an application to be able to create a subclass of a class, the following criteria must be met:
If these criteria are 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 V4.5.1 release, a metadata prefix-naming convention for class and property symbolic names has been defined for the FileNet P8 Content Engine. All new classes and properties that are introduced in this release or later, by any IBM® Enterprise Content Manager product that produces its own Content Engine feature Add-On, 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 that are chosen for display names.
Details of the prefix-naming convention are as follows:
Starting with the V4.5.1 release, any IBM Enterprise Content Manager product that produces its own feature Add-On also conforms to a prefix-naming convention. These feature AddOns use a prefix of "Cm???", in which "???" represents a short product-name abbreviation. However, any IBM Enterprise Content Manager products that have already established their own prefix-naming convention before this release will continue to use it instead.
The following list of Add-On 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; if 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 functioning 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 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 class, the following criteria must be met:
If these criteria are 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 particular class, the following criteria must be met:
If these criteria are 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 be saved only 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 that you have the proper permissions, you can directly save a ClassDefinition object by 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 does not have a save or a delete method. A PropertyDefinition object exists only as an object in the PropertyDefinitionList collection object that is referenced by a ClassDefinition object's PropertyDefinitions property, and can be saved only 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 does not have a save or a delete method). Similarly, because a ClassDescription object cannot be persisted by a client application, any dependent objects that belong to it, such as a PropertyDescription object, are not dependently persistable.
The Content Engine server creates and stores time stamps on all persistent objects by using Coordinated Universal Time. Use the following procedure in your client application to calculate time-relating strings:
The Content Engine server stores the date and time, in Coordinated Universal Time, 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 Coordinated Universal Time.
Each client application determines local time by using the system clock of the computer 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 is also 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 is not propagated to Image Services.