Classes

Class Metadata

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.

Class Descriptions

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):

• AllowsInstances: Specifies whether an application can create an object instance of the class. If this property is false, only the Content Engine server can instantiate the class.
• IsHidden: Specifies whether the class is hidden from non-administrative users.
• IsPersistent: Specifies whether you can save the state of the object instance of the class. If this property is false, only the Content Engine server can save the state of the object instance.
• PropertyDescriptions: Specifies a PropertyDescriptionList object that contains an ordered collection of all of the property descriptions that belong to the class description.

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:

• Reading its property values to determine the attributes of its class.
• Reading its PropertyDescriptionList property to describe the metadata of the properties that belong to the object instance of its class.
• Returning its DefaultInstancePermissions property to determine the default permissions for an object instance of its class.

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.

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):

• AllowsInstances: Specifies whether an application can create an object instance of the class. If this property is false, only the Content Engine server can instantiate the class.
• AllowsPropertyAdditions: Specifies whether user-defined properties can be added to the class.
• AllowsSubclasses: Specifies whether you can create subclasses from the class. Read-only.
• IsHidden: Specifies whether the class is hidden from non-administrative users.
• IsPersistent: Specifies whether you can save the state of the object instance of the class. If this property is false, only the Content Engine server can save the state of the object instance. Read-only.
• PropertyDefinitions: Specifies a PropertyDefinitionList object that contains an ordered collection of all the property definitions that belong to the class definition.
• SymbolicName: Specifies a unique (within an object store) programmatic identifier for the class.

The ClassDefinition class has four subclasses: SubscribableClassDefinition, VersionableClassDefinition,DocumentClassDefinition, and EventClassDefinition. Their usage is summarized as follows:

• SubscribableClassDefinition: An immediate subclass of the ClassDefinition class. Object instances of this class hold the class definition for all classes except Document and Event classes
• VersionableClassDefinition: An immediate subclass of the SubscribableClassDefinition class and immediate superclass of the DocumentClassDefinition class. No object instances of this class exist in the object store.
• DocumentClassDefinition: An immediate subclass of the VersionableClassDefinition class. Object instances of this class hold the class definition of Document classes (and their subclasses).
• EventClassDefinition: An immediate subclass of the ClassDefinition class. Object instances of this class hold the class definition of Event classes (and their subclasses).

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.

Subclasses

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:

• Additional properties can be supported.
• An inherited property that is optional in the superclass can be mandatory in the subclass (but not vice versa).
• The default value for an inherited property can differ in the subclass.
• The allowable values for an inherited property can be further constrained in the subclass; however, new allowable values cannot be introduced.

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:

• The class must have a class definition or a superclass of its class definition that is defined in the collection object that is returned by an object store's RootClassDefinition property.
• The AllowsSubclasses property of the class definition must have a value of true.

If these criteria are met, an application can create a new subclass by following these steps:

1. Obtain an object reference to the class definition that belongs to the class to be subclassed (by using the Factory.ClassDefinition.fetchInstance method).
2. Call the class definition's createSubclass method and set a reference to the new class definition object that it returns.
3. Save the new class to the object store by calling the save method of the new class definition object.

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 Content Cortex 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:

• A prefix of "Cm" is used for the symbolic name of any new Content Engine class or system property of a user-extensible class that is introduced in this release. For example, "CmNewProperty".
• All new system classes follow the naming convention, whether they are user extensible or not.
• The "Cm" prefix is also used for any new properties or classes that are introduced in Content Engine feature Add-Ons. However, the DITA feature Add-On continues to use the "Dita" prefix instead of the "Cm" prefix.

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:

• “Cm”: reserved by the Content Cortex Content Engine
• “Dita”: reserved by the Content Cortex Content Engine for the P8 DITA Add-On
• “RM”: reserved by IBM Enterprise Records
• “EDM”: reserved by IBM eDiscovery Manager
• “EDISC_”: reserved by IBM eDiscovery Manager
• “ICC”: reserved by IBM Content Collector

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.

Custom Properties

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:

• The class must have a class definition or a superclass of its class definition that is defined in the collection object that is returned by an object store's RootClassDefinition property.
• The AllowsPropertyAdditions property of the class definition must have a value of true.

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:

1. Obtain an object reference to the class definition that belongs to the class to be subclassed (by using the Factory.ClassDefinition.fetchInstance method).
2. If you choose not to use an existing property template as the basis for your new property, create a property template object, set its required properties, and save it.
3. Call a property template's createClassProperty method and set a reference to the new property definition that it returns.
4. Obtain an object reference to the class definition's PropertyDefinitions property and call the PropertyDefinitionList collection object's add method by using the new property definition as a parameter.
5. Call the class definition's save method to save the new property to the object store.

Object Instantiation

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:

• The class must have a class definition or a superclass of its class definition that is defined in the collection that is returned by an object store's RootClassDefinition property.
• The AllowsInstances property of the class definition must have a value of true.

If these criteria are met, an application can create an object instance of a class by following these steps:

1. Call a createInstance method of the Factory class corresponding to the type of object that you want to create. All of the createInstance methods require that you specify, at a minimum, the object store and the symbolic name of the object's class (this class can be a subclass of the class that is represented by the Factory class). For example, to create a document object, call a Factory.Document.createInstance method. If the class does not have a createInstance method in its Factory class, it cannot be instantiated by an application.
2. The createInstance method, if successfully called, returns an object instance of the class that you specified in the classId parameter. To save the object to the object store, you must set its required properties and call the object's save method.

Types of Object Persistence

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

• The class to which an independent object belongs is a subclass of the IndependentObject class.
• It has its own unique identity, independent of any other object, which can be retrieved by calling its getObjectReference method. This method call returns an ObjectReference object, which specifies the independent object's identity information.
• An independent object can be retrieved from the server with a call to InstantiatingScope.fetchObject or Factory.<classname>.fetchInstance.
• It can be persisted without being referenced directly by another object.
• Some independent objects allow you to subclass or add properties to the class to which they belong. You can read their class definition's allowsSubclasses and allowsPropertyAdditions properties to determine whether a particular class can be subclassed or allow the addition of new properties.

A dependent object has the following characteristics:

• The class to which a dependent object belongs is a subclass of the DependentObject class.
• A dependent object can be fetched only as a property of an independent object.
• A dependent object cannot be persisted unless the independent object that references it (with an object-valued property) is persisted.
• The class to which a dependent object belongs does not have a class definition and therefore cannot be subclassed or modified.

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.

Timestamps

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:

1. In your client application, create or modify an object by using the API.

   The Content Engine server stores the date and time, in Coordinated Universal Time, when the object was created or modified.

2. Retrieve the date and time value that specifies when the object was created or modified by using the DateCreated or DateLastModified property. For documents, you can also access the DateCheckedIn or DateContentLastAccessed properties.
3. Convert the date and time value from Coordinated Universal Time to local time and format the time to a user-specified local string.

For data and time values that a client application can input, such as the properties of a date-valued property template or property definition:

1. In your client application, convert the local time to Coordinated Universal Time.
2. Enter the local date and time values for the PropertyMinimumDateTime, PropertyMaximumDateTime, and PropertyDefaultDateTime properties of the object. The minimum time starts at 12:00:00; the maximum time ends at 23:59:59; the default time is 12:00:00).

   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.

Federated Documents

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.