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):
false
, only the Content Engine server can instantiate the class. false
, only the Content Engine server can save the state of the object instance. PropertyDescriptionList
object containing an ordered collection of all of the property descriptions belonging to the class description.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):
false
, only the Content Engine server can instantiate the class. false
, only the Content Engine server can save the state of the object instance. Read-only.PropertyDefinitionList
object containing an ordered collection of all of the property definitions belonging to the class definition.The ClassDefinition
class has four subclasses: SubscribableClassDefinition
, VersionableClassDefinition
, DocumentClassDefinition
, and EventClassDefinition
. Their usage is summarized below:
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 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:
true
. If these criteria have been met, an application may create a new subclass by following these steps:
Factory.ClassDefinition.fetchInstance
method). createSubclass
method and set a reference to the new class definition object that it returns. save
method of the new class definition object.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:
true
. If these criteria have been met, an application can add user-defined properties to a class by following these steps:
Factory.ClassDefinition.fetchInstance
method).createClassProperty
method and set a reference to the new property definition that it returns. PropertyDefinitionList
collection object's add
method with the new property definition as a parameter. save
method to save the new property to the object store. 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:
true
. If these criteria have been met, an application can create an object instance of a class by following these steps:
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 can be a subclass of the class 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. createInstance
method, if successfully called, will return 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. 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
IndependentObject
class.getObjectReference
method. This method call returns an ObjectReference
object, which specifies the independent object's identity information. InstantiatingScope.fetchObject
or Factory.<classname>.fetchInstance
.A dependent object has the following characteristics:
DependentObject
class. 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.
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.