Properties

Property 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 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, 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 and a stable metadata state 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. For more information about class descriptions, see Class Descriptions. For more information about class definitions, see Class Definitions.

Within each class description is an ordered list that is referenced by a PropertyDescriptions property that holds all of the property descriptions for a class. Each property description is represented by a PropertyDescription object that describes the fixed, immutable metadata of a specific property; when a class is instantiated into an object, the property description metadata is used as the basis for that object's property. After it is instantiated, an object's metadata can be accessed from the ClassDescription object that is returned by its ClassDescription object-valued property. All of a ClassDescription object's properties (including all of the PropertyDescription objects that are returned by its PropertyDescriptions property) are read-only. For more information about property descriptions, see Property Descriptions.

Within each class definition is an ordered list that is referenced by a PropertyDefinitions property that holds all of the property definitions for a class. Each property definition is represented by a PropertyDefinition object that defines the mutable metadata of a specific property that an application can modify. To modify the metadata of a class or property, you must modify the properties of its associated ClassDefinition and PropertyDefinition objects. For more information about property definitions, see Property Definitions.

Property Descriptions

Each property description holds the immutable (read-only) metadata properties that are used to describe a single property that is associated with a particular class instance and is contained in an ordered list that is referenced by the PropertyDescriptions property of the ClassDescription object for a class.

Property descriptions are classified according to the data type of the property they describe. There are eight property description classes, all subclassed from the abstract superclass, PropertyDescription, which define the properties common to all of the property description types:

• PropertyDescriptionBinary: Describes a property that holds a BINARY value.
• PropertyDescriptionBoolean: Describes a property that holds a BOOLEAN value.
• PropertyDescriptionDateTime: Describes a property that holds a DATE value.
• PropertyDescriptionFloat64: Describes a property that holds a DOUBLE value.
• PropertyDescriptionId: Describes a property that holds a GUID value.
• PropertyDescriptionInteger32: Describes a property that holds a LONG value.
• PropertyDescriptionObject: Describes a property that holds an OBJECT value.
• PropertyDescriptionString: Describes a property that holds a STRING value.

Every property description object has the following read-only metadata properties:

• DataType: Specifies the data type of the values that the property can hold.
• Cardinality: Specifies whether the property can hold a single value (single cardinality) or multiple values (list or enumeration cardinality).
• IsValueRequired: Specifies whether the property is required to have a value.
• Settability: Specifies a PropertySettability constant, which indicates how the value of a property can be set.
• IsReadOnly: Specifies whether you can modify the value of the property.
• IsSystemGenerated: Specifies whether the property has its value set automatically by the Content Engine.
• IsSystemOwned: Specifies whether the property was originally created by the Content Engine, as opposed to user-created.
• IsHidden: Specifies whether the property is hidden from non-administrative users.
• IsOrderable, IsSearchable, IsSelectable: Specifies how the property appears in query operations.
• RequiresUniqueElements: Specifies whether the values of a multi-valued property must be unique.
• PersistentType: Specifies whether a property can be made persistent (that is, have its state that is stored in a database).
• PrivilegedSettability: Specifies the settability of a property when an application is granted privileged write access.

In addition, every property description object has a type-specific form of the following properties:

• A property that optionally specifies a default value for the property. For example, in PropertyDescriptionString object, the property is PropertyDefaultString.
• A property that optionally specifies a list of values that can be assigned to a property. For example, in a PropertyDescriptionObject object, the property is PropertySelectionsObject.
• For all property description objects except PropertyDescriptionId and PropertyDescriptionObject, a property that specifies the maximum value that is allowed for the property. For example, in a PropertyDescriptionString object, the property is MaximumLengthString.
• For PropertyDescriptionDateTime, PropertyDescriptionFloat64, and PropertyDescriptionInteger32 objects, a property that specifies the minimum value allowed. For example, in a PropertyDescriptionInteger32 object, the property is PropertyMinimumInteger32.

PropertyDescriptionObject objects include the following additional properties:

• AllowsForeignObject: Specifies whether an object-valued property is permitted to reference an object in another object store or not.
• DeletionAction: Specifies the action to be taken regarding a given object-valued property when an attempt is made to delete the object that contains the property.
• ReflectivePropertyId: Specifies the Id property of the reflective property for an object-valued property. A reflective property is a property that you can create to constrain a multi-valued, object-valued property in another class to return specific objects of a given class.
• RequiredClass: Specifies the class description of a class of which an object must be an instance or subclass.

System and Custom Properties

A system property is a property that is integral to a Content Engine object and cannot be added to or removed from a class definition. Although you can modify the values of a system property that has read/write access (and for which you have the appropriate privileges), you cannot, in general, modify its metadata. (An exception is the PropertyDefaultXXX property of the property definition of certain system properties.) Unlike a custom property, a system property does not have an associated property template and thus the PropertyTemplate property of its property definition is null.

A custom property is a user-defined property that you can assign to a class. Defining custom properties is a means of extending the system metadata. You can also modify certain metadata properties of a custom property even after it is created. Each custom property is based on a property template that is specified by the PropertyTemplate property of its property definition.

For an object-valued custom property, the type of object that the property can hold is determined by the property definition's RequiredClassId property. The value of an object-valued custom property can be one of the following types of objects:

• An instance of a RepositoryObject subclass.
• An instance of a SecurityPrincipal subclass (includes User and Group objects).
• An independently retrievable GCD object. The following GCD objects are not allowed: EntireNetwork and Domain.

To add a custom property to a class, you must first create (or select an existing) property template to use as the basis for creating a new property definition. After you create a property template, you can use it to create and add a user-defined property definition to a class definition. Note that a system property cannot be assigned to a class by using a class definition; only a custom property can be assigned.

To add a custom property to a class, follow these steps:

1. Obtain an object reference to the class definition that belongs to the class to be subclassed (using the Factory.ClassDefinition.fetchInstance method). The AllowsPropertyAdditions property of the class definition must have a value of true, which indicates that the class is user extensible.
2. If you choose not to use an existing property template as the basis for your new custom property, create a property template object, set its required properties, and save it.
3. Call the 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 with the new property definition as a parameter.
5. Call the class definition's save method to save the new property to the object store.

Symbolic Names

A property's symbolic name is required to be unique within a class family only. A class family is defined by a root class (for example, Document, Folder, and CustomObject) and all of its descendants.

A metadata prefix-naming convention for property and class symbolic names is defined for the IBM® FileNet P8 Content Engine. All new properties and classes that are introduced in this release or later, by any IBM FileNet P8 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 property and class symbolic name values only; there are no constraints on the values chosen for display names.

The 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 AddOns. However, the DITA feature Add-On will continue to use the "Dita" prefix instead of the "Cm" prefix.

Any IBM FileNet P8 product that produces its own feature Add-On 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 before this release will continue to use it instead.

The following list of Add-On metadata prefixes are reserved:

• "Cm": reserved by the IBM FileNet P8 Content Engine
• "Dita": reserved by the IBM FileNet P8 Content Engine for the 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 custom property or class, 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.

Settable System Properties

The ability to set four system properties (Creator, DateCreated, Modifier, and LastModifier) is provided by the AccessRight.PRIVILEGED_WRITE) access right on the object store. These properties remain read-only for normal users. For users who have been granted access to the PRIVILEGED_WRITE access right, the settability of the Creator and DateCreated properties is SETTABLE_ONLY_ON_CREATE and the settability of the LastModifier and DateLastModified properties is READ_WRITE.

Property Templates

A property template is a collection of mutable metadata properties that are used to globally define one or more custom properties. Note that system properties do not have property templates. By providing a standard template from which class properties can be constructed, property templates promote the reuse of properties both within and across object stores. Property templates also provide multicultural support with a single point of modification for the locale-specific display names and descriptive text of a property. The property template that forms the basis of a given property definition contains the property definition's locale-specific strings for the DisplayName and DescriptiveText properties. After a property definition is created from a property template, it permanently retains an association with that property template. A property template is not associated with any class; each property template is independently persistable and independently securable. Each property template must be unique within an object store and can be aliased such that it is globally unique across multiple object stores.

Property templates are classified according to the data type of the property they define. There are eight property template classes, all subclassed from the abstract superclass, PropertyTemplate, which define the properties common to all of the property template types:

• PropertyTemplateBinary: Describes a template for properties that hold a BINARY value.
• PropertyTemplateBoolean: Describes a template for properties that hold a BOOLEAN value.
• PropertyTemplateDateTime: Describes a template for properties that hold a DATE value.
• PropertyTemplateFloat64: Describes a template for properties that hold a DOUBLE value.
• PropertyTemplateId: Describes a template for properties that hold a GUID value.
• PropertyTemplateInteger32: Describes a template for properties that hold a LONG value.
• PropertyTemplateObject: Describes a template for properties that hold an OBJECT value.
• PropertyTemplateString: Describes a template for properties that hold a STRING value.

Each property template object has the following read/write properties to globally control property metadata. The values of the properties that you set on a property template are carried over to its associated property definition:

• AliasIds: Specifies an IdList object that contains a list of optional alias IDs for a property.
• Cardinality: Specifies whether a property is a singleton, list, or enumeration. Note that this property can be set only when you create a property template; after the property template has been saved, the Cardinality property's settability will be read-only on the property template (and on any property definitions that are created from the property template).
• ChoiceList: Specifies a ChoiceList object that represents the discrete set of possible values that a property can hold.
• DescriptiveTexts: Specifies a LocalizedStringList object containing a collection of LocalizedString objects, each of which represents a locale-specific, user-readable description for a property. The value of the LocalizedText property of the LocalizedString object for the object store's default locale becomes the read-only value of the property definition's DescriptiveText property.
• DisplayNames: Specifies a LocalizedStringList object that contains a collection of LocalizedString objects, each of which represents a locale-specific, user-readable display name for a property. The value of the LocalizedText property of the LocalizedString object for the object store's default locale becomes the read-only value of the property definition's DisplayName property.
• IsHidden: Specifies whether a property is hidden from non-administrative users.
• IsNameProperty: Specifies whether the value of a property provides the name of the object instances of the class to which it belongs.
• IsValueRequired: Specifies whether a property is required to have a value.
• ModificationAccessRequired: Specifies the access rights that are required to change the value of the property on the object instances on which the property occurs.
• PersistenceType: Specifies a PropertyPersistence constant that indicates whether a property can be made persistent (that is, have its state that is stored in a database).
• RequiresUniqueElements: Specifies whether the values of a multi-valued property must be unique. Note that this property can be set only when you create a property template; after the property template has been saved, the RequiresUniqueElements property's settability will be read-only on the property template (and on any property definitions that are created from the property template).
• Settability: Specifies a PropertySettability constant, which indicates how the value of a property can be set.

In addition, every property template object has a type-specific form of the following properties:

• A property that optionally specifies a default value for the property. For example, in a PropertyTemplateString object, the property is PropertyDefaultString.
• For all property template objects except PropertyTemplateId and PropertyTemplateObject, a property that specifies the maximum value allowed for the property. For example, in a PropertyTemplateString object, the property is MaximumLengthString.
• For PropertyTemplateDateTime, PropertyTemplateFloat64, and PropertyTemplateInteger32 objects, a property that specifies the minimum value allowed. For example, in a PropertyTemplateInteger32 object, the property is PropertyMinimumInteger32.

PropertyTemplateObject objects include the following additional property:

• AllowsForeignObject: Specifies whether an object-valued property is permitted to reference an object in another object store or not.

Property Definitions

A property definition is a collection of mutable metadata originating from a property template. Each property definition is associated with a specific class definition and represents a property belonging to the object instance of a class. Property definitions are dependently persistable and dependently securable. By modifying the values of a property definition's properties, you can modify the metadata of a user-defined property that has been defined by a property template. In general, you cannot modify the property definition of a system property. (An exception is the PropertyDefaultXXX property of the property definition of certain system properties.)

Property definitions are classified according to the data type of the property they describe. There are eight property definitions classes, all subclassed from the abstract superclass, PropertyDefinition, which define the properties common to all of the property definition types:

• PropertyDefinitionBinary: Defines a property that holds a BINARY value.
• PropertyDefinitionBoolean: Defines a property that holds a BOOLEAN value.
• PropertyDefinitionDateTime: Defines a property that holds a DATE value.
• PropertyDefinitionFloat64: Defines a property that holds a DOUBLE value.
• PropertyDefinitionId: Defines a property that holds a GUID value.
• PropertyDefinitionInteger32: Defines a property that holds a LONG value.
• PropertyDefinitionObject: Defines a property that holds an OBJECT value.
• PropertyDefinitionString: Defines a property that holds a STRING value.

Each property definition object has the following read/write properties, which allow you to change the metadata of a property:

• AliasIds: Specifies an IdList object containing a list of optional alias IDs for the property.
• ChoiceList: Specifies a ChoiceList object that represents the discrete set of possible values that the property can hold.
• CopyToReservation: Specifies whether the value of the property belonging to a document should be copied, when the document is checked out, from the source document to the newly created reservation object.
• IsHidden: Specifies whether the property should be hidden from non-administrative users.
• IsNameProperty: Specifies whether the value of the property provides the name of the object instances of the class to which it belongs.
• IsValueRequired: Specifies whether the property is required to have a value.
• ModificationAccessRequired: Specifies the access rights that are required to change the value of the property on the object instances on which the property occurs.
• Settability: Specifies a PropertySettability constant, which indicates how the value of a property can be set.

In addition, every property definition object has a type-specific form of the following properties:

• A property that optionally specifies a default value for the property. For example, in PropertyDefinitionString object, the property is PropertyDefaultString.
• For all property definition objects except PropertyDefinitionId and PropertyDefinitionObject, a property that specifies the maximum value allowed for the property. For example, in a PropertyDefinitionString object, the property is MaximumLengthString.
• For PropertyDefinitionDateTime, PropertyDefinitionFloat64, and PropertyDefinitionInteger32 objects, a property that specifies the minimum value allowed. For example, in a PropertyDDefinitionInteger32 object, the property is PropertyMinimumInteger32.

PropertyDefinitionObject objects include the following additional properties:

• AllowsForeignObject: Specifies whether an object-valued property is permitted to reference an object in another object store or not.
• DeletionAction: Specifies the action to be taken regarding a given object-valued property when an attempt is made to delete the object that contains the property.
• ReflectivePropertyId: Specifies the Id property of the reflective property for an object-valued property. A reflective property is a property that you can create to constrain a multi-valued, object-valued property in another class to return specific objects of a given class.
• RequiredClassId: Specifies the ID of the class description of a class of which an object must be an instance or subclass.

Modifying Custom Metaproperties

A custom property definition originates from a property template. When you create a property definition from a property template, many of the property template metaproperties are copied to the property definition. The fact that a custom property definition contains many of the same metaproperties as its originating property template presents options in how metaproperties are changed on the property definition.

Most metaproperties can be modified per class; that is, you can modify a metaproperty directly on a property definition in a class. A metaproperty change on a property definition might or might not automatically propagate to the subclasses.

Some metaproperties are not available for modification on a class basis; they must be modified on the originating property template. In these cases, the metaproperty changes in the property template are reflected in every class that references the property definition.

The following table summarizes the effect of modifying metaproperties on property template and property definition classes. It specifies the following:

• All of the settable metaproperties on the PropertyTemplate and PropertyDefinition classes and subclasses.
• Whether the metaproperty can be changed on the property template, property definition, or both. As a rule, if you change a metaproperty on a property template that is also modifiable on the property definition, then the change will not be reflected in the property definition.
• Whether a change to a property definition metaproperty is automatically propagated to subclasses.

¹ A multi-valued property. Updates to the list value are implicitly propagated. However, adding the metaproperty to a property definition does not get automatically propagated.

Property Values

Depending on the data type that it holds, an object's property is represented by an object belonging to one of the following subclasses of the Property class:

Single-valued properties

• PropertyBinary: Represents a property that holds a byte (8-bit signed integer) array that is intended for a binary value.
• PropertyBoolean: Represents a property that holds a Boolean value.
• PropertyContent: Represents a property that holds an InputStream object that is intended for reading bytes of content data from a file source.
• PropertyDateTime: Represents a property that holds a Date object for specifying a date and time.
• PropertyFloat64: Represents a property that holds a Double (64-bit floating point) value.
• PropertyId: Represents a property that holds an Id (GUID-string) value.
• PropertyInteger32: Represents a property that holds an Integer (32-bit signed integer) value.
• PropertyString: Represents a property that holds a String value.
• PropertyEngineObject: Represents a property that holds a single Content Engine object (an instance of an EngineObject subclass).

Multiple-valued properties

• PropertyBinaryList: Represents a property that holds a BinaryList object, which contains a collection of binary values.
• PropertyBooleanList: Represents a property that holds a BooleanList object, which contains a collection of Boolean values.
• PropertyDateTimeList: Represents a property that holds a DateTimeList object, which contains a collection of Date values.
• PropertyFloat64List: Represents a property that holds a Float64List object, which contains a collection of Double values.
• PropertyIdList: Represents a property that holds an IdList object, which contains a collection of GUID-string values.
• PropertyInteger32List: Represents a property that holds an Integer32List object, which contains a collection of Integer values.
• PropertyStringList: Represents a property that holds a StringList object, which contains a collection of String values.
• PropertyIndependentObjectSet: Represents a property that holds an IndependentObjectSet object, which contains a collection of IndependentObject object values.
• PropertyDependentObjectList: Represents a property that holds a DependentObjectList object, which contains a collection of DependentObject object values.

Reading Property Values

To read or set the value of a property or to retrieve the Property object that represents a specific object property, you must first retrieve the object's Properties object. A Properties object is a collection of all of the properties belonging to a given Content Engine object. To obtain an object's Properties object, call an object's getProperties method. Once you have retrieved an object's Properties collection object, you can read the value (or values) of a specific property by using one of the following procedures. Note that, depending on its cardinality, an individual property in a Properties object collection can hold a single value or multiple values:

• Call the appropriate Properties object's getXXXValue method corresponding to the data type of the property you want to retrieve (getBinaryValue, getBinaryListValue, getBooleanValue, and so on) and specify the property's name as a parameter.
• Return a specific property using the Properties object's get method, specifying the property's name as a parameter. From the selected property, call the appropriate getXXXValue method corresponding to the property's data type.

You can obtain a specific Property object in a Properties object collection in one of the following ways:

• Use a Properties object's get method and specify the name of the property to retrieve.
• In a Java application, you can iterate through each Property object in a Properties object collection by using the iterator() method.
• In a C# application, you can iterate through each Property object in a Properties object collection by using the ForEach command.

Setting Property Values

If the isSettable property of a Property object has a value of true, an application can set the value of a property in one of the following ways:

• To set the value of a specific property in a Properties object collection, use the appropriate putValue method for the property's data type: putValue(java.lang.String propertyName, BinaryList value), putValue(java.lang.String propertyName, boolean value), and so on.
• To set the value of the property represented by a Property object, call its setValue method and set its parameter to the new property value.
• To set the value of the property represented by a Property object, call its setObjectValue method and set its parameter to the new property value.

Special Situations

When you read or set a property, be aware of the following:

• If you fetch a read-only property from the server and your client application attempts to modify its value, an exception will be thrown immediately on the client (before you save it). However, if you add a new property (one that was originally excluded from retrieval) to the property cache, that property's settability information (available via the property's isSettable method) is not present in the property cache. Therefore, regardless of whether the new property is read-only or not, modifications will be allowed by the client and any errors generated will not be returned until the object to which the property belongs is saved.
• If you define a custom property with a default value that cannot be persisted (saved) to the database and you later fetch an object instantiated from the class to which that property has been added, you can only retrieve the property's default value. Because the property has not been persisted to the database, no other value is available. Whether or not a given custom property can be persisted is determined by the value given to the PersistenceType property of its associated property template.
• When an application attempts to set the PropertyDefaultString property of a PropertyTemplateString object to a long string that is less than 4000 characters, a DB_ERROR exception can be thrown instead of a BAD_VALUE exception. This exception occurs when the maximum row size of the database has been exceeded, but not the maximum length allowed for the property value.
• If an E_READ_ONLY exception is thrown because a client application is attempting to update one or more read-only properties during a user-initiated transaction, the transaction will not be automatically rolled back by the server; a client application must explicitly rollback or commit the data.

Property Cache Concepts

To save system resources, each Content Engine object maintains a local (client-side) property cache from which one or more of an object's properties, if available, can be retrieved. The property cache is populated whenever properties are retrieved from the server during an object refresh or a property fetch. By ensuring that the property cache contains the properties you require, your client application can minimize the number of round-trips to the server, thus improving performance.

There are three ways to instantiate objects, with differing effect on the initial state of the local property cache:

1. Fetchless instantiation: To construct a local instance of a specified class, call a factory getInstance method. This method does not verify the existence of the requested object on the server; it returns a local reference without making a round trip to the server. The local reference is not affiliated with a server object until you perform a function on the object (for example, fetch a property value) that causes a round-trip to the server; until then, the property cache remains empty except for properties added by setter accessor method calls. For performance reasons, it is useful to fetchlessly instantiate objects this way if those objects will only serve passively; for example, as the target value of an object-valued property.
2. Fetch instantiation: To retrieve a specified server object, call a factory fetchInstance method. This method instantiates an object by making a round trip to the server and fetching the object's property values. The client application controls which properties are fetched into the local property cache by using a property filter. The local instantiated object will have a value for its update sequence number that is current as of the fetch. Note, however, that the server object can change over time; to keep the local object current, call its refresh method.
3. Create instantiation: To instantiate a local object that references a new server object, call a factory createInstance method. When the local object is instantiated, a round-trip to the server is not made and the object will not yet be persisted in the repository. Instead, the local instance will have associated with it a Create pending action. To persist the new object to the object store, you must explicitly call its save method, or commit the object via a batch operation. Both approaches will cause a round-trip to the server. Until the object is saved and refreshed, the property cache will contain only properties added by setter accessor method calls.

There are two ways to add server object properties to the local property cache:

1. Object refresh: To add a new set of properties from the server, call an existing object's refresh method. If the same object already has a set of properties in the properties cache, the entire set will be discarded.
2. Property fetch: To add a new property or re-fetch an existing property in the property cache by making a round-trip to the server, call an object's fetchProperty or fetchProperties method. If the object has existing properties in the properties cache, they will be merged; new properties will be added and existing properties will be replaced. If this object has changed on the server since it was last retrieved (indicated by a mismatch of the update sequence number of the server object and the local object), you should first call its refresh method; otherwise, an error will be thrown. During a property fetch, the following rules apply:
   • Any attempt to replace a dirty property (see below) with a fetched property will not cause an exception to be thrown; instead, the fetched property will automatically replace the dirty property.
   • If the returned object is newer than the current object, an exception will be thrown.
   • As a special case, a current object that has been fetchlessly instantiated will match any returned object, after which the current object will use the update sequence number of the returned object and will no longer be considered a fetchlessly instantiated object.

To remove specific object properties from the property cache, use one of the Properties.removeFromCache methods. Note that if the specified property is not in the properties cache, an exception will not be thrown. A subsequent request for the value of a property that has been removed from the cache will throw an exception.

When you use a getter accessor method to access a property, an attempt is made to read the property from the property cache. If the property is not found in the property cache, an API_PROPERTY_NOT_IN_CACHE exception will be thrown. Note, however, that a property that returns an unevaluated object can be present in the cache without having an explicit value; fetching the value of an unevaluated object will cause an automatic round-trip to the server to retrieve its value and will not generate an exception.

Setting the value of a property via a setter accessor method will either update the cached value (if present) or add a new cache entry, but does not immediately persist that property value into the persistent store; instead, any modified properties are accumulated internally until explicitly saved (via a save method call) or implicitly saved as a side effect of some other operation. When a property is changed in the property cache, but not yet persisted, it is marked as "dirty" by the server. This allows the server to keep track of which properties need to have their state updated in the persistent store. Once a property value has been changed in the cache, the only way to recover its original value is to re-fetch it from the server. A client-to-server update transmits only the dirty properties; each property whose IsDirty method returns true will have its state updated on the server and will be marked as not dirty.

Property Filter Concepts

A property filter allows you to control which properties of a Content Engine object (and with what level of detail) to return from the server during an object retrieval or an object refresh. Because the number and size of properties might be large for certain objects, using a property filter to retrieve a subset of the available properties can result in better performance by reducing the amount of data that is retrieved from the server.

For an example of how to control which properties to return from an object, consider the Document and Folder object types. The following tables list selected properties of the Document and Folder object types, including the data types that they hold and their cardinality.

Document object

Folder object

By using a property filter, you can fetch a document and all of the folders in which that document is filed using a single call to the server. Likewise, you can retrieve a folder, all of the documents contained in that folder, and all of the subfolders of that folder in a single call to the server (subject to available memory). You can also specify exactly which properties of an object to fetch; for example, you might fetch the Creator property, but not the DateCreated property.

When you fetch property data from the server with your client application, you should have three goals in mind:

1. Achieving a balance between the number of server round trips needed to fetch all of the required data and the resources required by the server and client to handle each fetch.
2. Avoiding performance inefficiency caused by fetching unnecessary data.
3. Avoiding API_PROPERTY_NOT_IN_CACHE exceptions due to insufficient data being fetched.

The simplest approach to achieving these goals, although not necessarily the most efficient, is to not use a property filter at all: this is achieved by passing in null whenever a property filter is specified as an API method parameter. If you omit a property filter when calling a fetch method, your client application will fetch all of an object's scalar (non-object) properties, and placeholders for all of its object-valued properties; subsequent attempts to read an object-valued property will result in an automatic remote call to the server to fetch the object value. Note that API_PROPERTY_NOT_IN_CACHE errors will not occur because all of the scalar properties are already present in the local property cache. Any requests for object-valued properties that are not in the local property cache will be processed automatically by the Content Engine, which will fetch the object value from the server. Although not using a property filter will cause all property values to be eventually retrieved and allow navigation from one object to the next, there will be more remote calls to the server, which can affect performance. Therefore, if you want to achieve maximum efficiency and speed from your client application, you should use property filters when fetching object properties. Property filters provide precise control and feedback to assist in optimizing performance.

There are three ways that an object-valued property can be fetched (or not fetched) from the server using a fetchProperty or refresh method:

1. The property is specified in a property filter. The property's object value is fetched from the server and loaded into the local property cache. A getter accessor method call to read the property will retrieve its object value from the local property cache.
2. No property filter is used. The property's object value is not fetched, but is set up to be fetched later; its value is stored in the property cache as a reference object or as an unevaluated object. A getter accessor method call to read the property will automatically cause a round-trip to the server to fetch its object value and return it to the caller. Any subsequent getter accessor method calls to read the property will retrieve its value directly from the property cache. For more information, see the PropertyState constant class.
3. A property filter is used, but the property is either not specified for inclusion or is specified for exclusion. The property's object value is not fetched and is not set up to be fetched later. A getter accessor method call to read the property will generate an API_PROPERTY_NOT_IN_CACHE exception.

For example, if you call Document.get_Reservation in a client application to read the reservation object value of a Reservation property, the outcome is determined by how the property was fetched (or not fetched) as described in the previous section:

1. The reservation object is retrieved from the local property cache.
2. The reservation object is not present in the local property cache, but a round trip is automatically made to the server to fetch it and the reservation object is returned. Note that any subsequent calls to Document.get_Reservation will retrieve the reservation object directly from the local property cache instead of from the server.
3. The reservation object is not present in the local property cache; no server access is attempted and an API_PROPERTY_NOT_IN_CACHE exception is returned.

Performance-sensitive applications that wish to minimize server round trips might instead want to access object-valued properties differently, especially if the application needs only the object's reference (that is, its class or object identities). In general, when an application does not use property filters, an object-valued property's reference is placed into the property cache and that reference is used to retrieve the full object (via a round trip to the server). This additional round trip can be eliminated by accessing only the property's object reference. For example:

 PropertyEngineObject peo =
      (PropertyEngineObject)Document.getProperties().get(PropertyNames.RESERVATION); ObjectReference
      reservationRef = peo.getObjectReference(); 

Property Filter Structure

A property filter consists of a PropertyFilter object and one or more filter elements, each of which is represented by a FilterElement object. Each filter element represents a specification for adding properties (either by identifier or type) to the property filter. To create a filter element to specify properties by identifier, call a PropertyFilter.addIncludeProperty method. To create a filter element to specify properties by type, call a PropertyFilter.addIncludeType method. Depending on which specific addIncludeProperty or addIncludeType method you call, you can choose to create a FilterElement object and provide it as a parameter or have the server create a FilterElement object for you based on the information that you provide in the method's parameters. In addition, you can explicitly specify that one or more properties be excluded by calling the PropertyFilter.addExcludeProperty method.

PropertyFilter Object

A PropertyFilter object has the following components:

• Zero or more IncludeProperty specifications. Each one specifies, by identifier, one or more properties to retrieve from the server. You create an IncludeProperty specification by calling one of the addIncludeProperty methods. Each IncludeProperty specification is encapsulated in a FilterElement object, which specifies the properties to retrieve and optionally specifies the maxSize, maxRecursion, levelDependents, and pageSize attributes. You can also set the global defaults for these attributes with the appropriate PropertyFilter method.
• Zero or more IncludeType specifications. Each one specifies, by type, properties to retrieve from the server. The property type specification is set to one of the FilteredPropertyType constants (for example, FilteredPropertyType.ANY_SINGLETON, which specifies all properties of single cardinality). You create an IncludeType specification by calling one of the addIncludeType methods. Each IncludeType specification is encapsulated in a FilterElement object, which specifies the type of property to retrieve and optionally specifies the maxSize, maxRecursion, levelDependents, and pageSize attributes. You can also set the global defaults for these attributes with the appropriate PropertyFilter method.
• Zero or more ExcludeProperty specifications. Each one specifies, by identifier, one or more properties to be excluded from server retrieval. Any properties specified for exclusion will override those properties that are specified in an IncludeProperty or IncludeType specification. You create an ExcludeProperty specification by calling the addExcludeProperty method and providing a space-separated list of the symbolic names or GUID-string identifiers of the properties to exclude.

In general, property filters in your application should use IncludeProperty or IncludeType specifications instead of ExcludeProperty specifications because an IncludeProperty or IncludeType specification allows you to better control which properties are returned. An ExcludeProperty specification will not prevent the retrieval of any new properties that might be subsequently added to an object, while an IncludeProperty (or IncludeType) specification will retrieve only a fixed set of properties. Any new properties that are subsequently added to an object will need to be explicitly added to an IncludeProperty specification to be retrieved.

A PropertyFilter object has attributes you can set that control how properties are retrieved. These attributes act as global defaults for the PropertyFilter object. You can override each of these attributes for an individual FilterElement object when you call an addIncludeProperty or addIncludeType method. For any attribute not specified for a FilterElement object, the global attribute value for the PropertyFilter object applies. If a global value is unspecified, a default value applies. Each of the following attributes can be set by the appropriate PropertyFilter method:

• levelDependents: A Boolean that specifies whether the recursion level to use when retrieving a dependent object is the same as that of the independent object to which it belongs (true) or one level deeper (false). Set this value via the setLevelDependents method. For more information, see Dependent Objects.
• maxRecursion: A zero-based integer that specifies the maximum allowable recursion depth to use when retrieving property relationships. This attribute determines the depth to which properties are included. If unspecified, the default is zero. Set this value via the setMaxRecursion method. For more information, see Property Recursion.
• maxSize: A long that specifies the maximum size, in bytes, of content data that can be returned when properties that hold content data are retrieved. If the amount of content data that is held by retrieved properties exceeds this size, no content data is returned. If unspecified, the default is to return all content data, no matter how large. Set this value via the setMaxSize method.
• pageSize: An integer that specifies the iterator page size for independent object sets returned by PropertyIndependentObjectSet properties. The iterator page size determines how many elements of an independent object set are retrieved during each fetch. If the page size is unspecified, by default the server uses the value of the QueryPageDefaultSize property of the ServerCacheConfiguration object (the default for this property is 500). If the page size exceeds the value of the QueryPageMaxSize property of the ServerCacheConfiguration object (the default for this property is 1000), the server uses the value of the QueryPageMaxSize property instead. Set this value via the setPageSize(int pageSize) or setPageSize(java.lang.Integer pageSize) method.

To see all of the methods that use a PropertyFilter object as a parameter, select Use from the header of the PropertyFilter class topic in the Java API Reference documentation.

FilterElement Object

Each FilterElement object can specify one or more properties, either by identifier (symbolic name or GUID-string identifier) or by type. When specifying properties by identifier, a FilterElement object is created by setting the value parameter of the appropriate constructor to a string-separated list of symbolic names or GUID-string identifiers. When specifying properties by type, a FilterElement object is created by setting the value parameter of the appropriate constructor to a string-separated list of type specifiers or a FilteredPropertyType constant.

In addition, a FilterElement object has local attributes you can set that control how properties are retrieved. These attributes override any global attributes that might be specified by the associated PropertyFilter object and they apply exclusively to properties whose retrieval is determined by a particular FilterElement object. If an attribute is not set in a FilterElement object, the attribute's global value in the PropertyFilter object will be used instead. If a global value is unspecified, a default value applies. The following attributes are set by the parameters of a FilterElement constructor or the parameters of a PropertyFilter object's addIncludeProperty or addIncludeType method:

• levelDependents: A Boolean that specifies whether the recursion level to use when retrieving a dependent object is the same as that of the independent object to which it belongs (true) or one level deeper (false). Set this value via a FilterElement constructor's levelDependents parameter or the levelDependents parameter of a PropertyFilter object's addIncludeProperty or addIncludeType method. If unspecified, the value of the global levelDependents attribute of the PropertyFilter object is used. If both the PropertyFilter and FilterElement attributes are unspecified, the default is false. For more information, see Dependent Objects.
• maxRecursion: A zero-based integer that specifies the maximum allowable recursion depth to use when retrieving property relationships. This attribute determines the depth to which properties are included. If unspecified, the default is zero. Set this value via a FilterElement constructor's maxRecursion parameter or the maxRecursion parameter of a PropertyFilter object's addIncludeProperty or addIncludeType method. If unspecified, the value of the global maxRecursion attribute of the PropertyFilter object is used. If both the PropertyFilter and FilterElement attributes are unspecified, the default is 0. For more information, see Property Recursion.
• maxSize: A long that specifies the maximum size, in bytes, of content data that can be returned when properties that hold content data are retrieved. If the amount of content data that is held by retrieved properties exceeds this size, no content data is returned. Set this value via a FilterElement constructor's maxSize parameter or the maxSize parameter of a PropertyFilter object's addIncludeProperty or addIncludeType method. If unspecified, the value of the global maxSize attribute of the PropertyFilter object is used. If both the PropertyFilter and FilterElement attributes are unspecified, the default is to return all content data, no matter how large.
• pageSize: An integer that specifies the iterator page size for independent object sets returned by PropertyIndependentObjectSet properties. The iterator page size determines how many elements of an independent object set are retrieved during each fetch. Set this value via a FilterElement constructor's pageSize parameter or the pageSize parameter of a PropertyFilter object's addIncludeProperty or addIncludeType method. If unspecified, the value of the global pageSize attribute of the PropertyFilter object is used. If both the PropertyFilter and FilterElement attributes are unspecified, by default the server uses the value of the QueryPageDefaultSize property of the ServerCacheConfiguration object (the default for this property is 500). If the page size exceeds the value of the QueryPageMaxSize property of the ServerCacheConfiguration object (the default for this property is 1000), the server uses the value of the QueryPageMaxSize property instead.

Property Precedence Rules

To resolve potential conflicts when a property is specified by more than one means, the following property filter precedence rules apply:

• Properties specified in an ExcludeProperty specification override those specified in an IncludeProperty or IncludeType specification. That is, if the same property is specified to be excluded in an ExcludeProperty specification and specified to be included in an IncludeProperty or IncludeType specification, the property will be excluded.
• If a property is specified in both an IncludeProperty and an IncludeType specification, only the attributes from the IncludeProperty specification apply.
• If a property type is specified more than once by the same means, only the attributes from the property's first appearance apply.
• If a property type is specified by more than one means (for example, a PropertyFilter object that has an IncludeType specification that specifies FilteredPropertyType.SINGLETON_STRING and another IncludeType specification that specifies FilteredPropertyType.ANY_SINGLETON), only the attributes from the most specific IncludeType specification apply (in the previous example, the SINGLETON_STRING specification).
• If two filter elements match the same property, only the most specific filter element will be used. Thus, if a property of a fetched object was matched by a filter element with a property name and another filter element with a property type, the property name filter element and its attributes will be used. Likewise, if a property is matched with two property-type filter elements, the most specific filter element will be used. For example, a property type of “String” is chosen over a property type of “*”.

Property Recursion

In order to use the maxRecursion attribute, you must understand the concept of property recursion in Content Engine objects. Content Engine object properties can have properties that reference other objects that in turn have their own properties, and so on. This means that fetching a single Content Engine object that has one or more object-valued properties can potentially result in many additional properties being returned. To control the number of properties that are fetched, property filters allow clients to define the depth of recursion for property relationships. When the server traverses an object tree formed by an object's object-valued properties, it keeps track of the current recursion level for each object. The current recursion level starts at 0 for the initial fetched object and is incremented by 1 for each child object that is returned by a parent object's object-valued property.

For example, suppose you have a document with a reservation that is filed in a folder. Using indentation to represent the parent/child relationships between objects returned by object-valued properties:

      Document object #1
            Reservation: Returns Document object #2
                  FoldersFiledIn: Returns a collection of Folder objects
   

In the above example, the Reservation property returns a Document object that is a child object of the original Document object, and the FoldersFiledIn property returns a collection of Folder objects that are child objects of the Reservation object. As the server navigates the object tree, it keeps track of the current recursion level. This recursion level is initialized at 0, and is incremented by one for each child object that is traversed (unless the levelDependents attributes is set to true, as described later). Therefore, for this example the current recursion level (shown in brackets) maintained by the server for each object is as follows:

• Document object #1 [0]: Initial fetched object
• Document object #2 [1]: Child object of Document object #1
• Folder objects [2]: Child objects of Document object #2

When a property is selected to be fetched by the server due to a match in an IncludeProperty or IncludeType specification, the server determines the correct maxRecursion attribute value to use:

1. If the FilterElement object in an IncludeProperty or IncludeType specification has a value for maxRecursion, that value is used.
2. Otherwise, the global maxRecursion attribute value returned by the getMaxRecursion method of the PropertyFilter object is used.
3. If both the FilterElement object maxRecursion attribute and the PropertyFilter object global maxRecursion attribute are null, the default is 0.

When fetching properties, the server makes the following comparisons, based on a property's property type and the current recursion level of the object to which it belongs.

Scalar (non-object) properties

1. If the current recursion level is less than or equal to the recursion level specified by the maxRecursion attribute, the value of the scalar property is returned.
2. Otherwise, the value of the scalar property is not returned. Attempts to fetch it will generate an API_PROPERTY_NOT_IN_CACHE error.

Object-valued properties

1. If the current recursion level is less than the recursion level specified by the maxRecursion attribute, the object specified by the object-valued property is returned.
2. If the current recursion level is equal to the recursion level specified by the maxRecursion attribute, the property's object value is not fetched, but is set up to be fetched later; its value is stored in the property cache as a reference object or as an unevaluated object. A getter accessor method call to read the property will automatically cause a round-trip to the server to fetch its object value and return it to the caller. Any subsequent getter accessor method calls to read the property will retrieve its value directly from the property cache.
3. If the current recursion level is greater than the recursion level specified by the maxRecursion attribute, the object value specified by the object-valued property is not returned (attempts to fetch it will generate an API_PROPERTY_NOT_IN_CACHE error).

For code examples demonstrating how to use the maxRecursion attribute, see Working with Properties.

Dependent Objects

A dependent object belongs to its parent independent object and can only be persisted when the independent object to which it belongs is saved. A dependent object is an object that is instantiated from a subclass of the EngineObject class but, unlike an independent object, is not a subclass of the IndependentObject class. The only way to retrieve a dependent object is from its parent object. Because a dependent object does not have its own security attributes, its parent independent object must be inspected to check access rights.

The levelDependents attribute explicitly controls the recursion level for the elements of a dependent object collection. Normally, the elements of a dependent object collection are evaluated at a current recursion level that is one level deeper than the object that contains them. However, if the levelDependents attribute is true, the dependent object elements are evaluated at the same recursion level as the object that contains them.

Because dependent objects are typically fetched along with their parent objects, an easy way to retrieve all of the dependent objects belonging to a parent object is to set the levelDependents attribute to true. This instructs the server to always traverse into the dependent object while not incrementing the current recursion level.

When a property is selected to be fetched by the server due to a match in an IncludeProperty or IncludeType specification, the server determines the correct levelDependents attribute value to use:

1. If the FilterElement object in an IncludeProperty or IncludeType specification has a value for levelDependents, that value is used.
2. Otherwise, the global levelDependents attribute value that is returned by the getLevelDependents method of the PropertyFilter object is used.
3. If both the FilterElement object attribute and the PropertyFilter object global levelDependents attribute are null, the default is false.

If a dependent object contains a property that returns an independent object, the levelDependents attribute has no effect on that independent object.

For code examples that demonstrate how to use the levelDependents attribute, see Working with Properties.