Properties are the primary means by which Content Engine objects expose and allow manipulation of their state. Properties are defined within a given Content Engine class and through inheritance from its superclasses. For information about classes, see Class Concepts.
There are eight types of data that a Content Engine property can hold. In addition, a property's cardinality determines whether it can hold a single value of a specified data type (a single-valued property) or multiple instances of the specified data type (a multi-valued property).
There are three types of cardinality that a property can have:
SINGLE
: A property that returns a single value.ENUM
: A property that returns a read-only, enumeration collection of unique items with a data type of OBJECT
. The items in an enumeration collection can only be traversed sequentially and the number, order, and values of the items in the collection can change even if a reference to the collection remains constant.LIST
: A property that returns a list collection of items, which may either be modifiable (allowing items to be inserted, replaced, or deleted) or read-only. The items in a list collection can be accessed in random order and the number, order, and values of the items in the collection will remain constant as long as a reference to the collection is maintained. Multi-valued properties with a data type other than OBJECT
must have a cardinality of LIST
. A property can hold the following data types:
BINARY
:
SINGLE
return a byte (8-bit unsigned integer) array intended for a binary value. LIST
return a BinaryList
object. BOOLEAN
:
SINGLE
return a true
or false
value.LIST
return a BooleanList
object. DATE
:
SINGLE
return a java.util.Date
value in Java™ code, or a DateTime
value in C# and Visual Basic code.LIST
return a DateTimeList
object. DOUBLE
:
SINGLE
return a 64-bit floating point value. LIST
return a Float64List
object. GUID
:
SINGLE
return a GUID-string value.LIST
return an IdList
object. LONG
:
SINGLE
return a 32-bit signed integer value. LIST
return an Integer32List
object. OBJECT
:
SINGLE
return an EngineObject
value, which allows access to a single Content Engine object that is an instance of an EngineObject
subclass. ENUM
return an IndependentObjectSet
object, which contains a collection of IndependentObject
objects. LIST
return a DependentObjectList
object, which contains a collection of DependentObject
objects. STRING
:
LIST
return a StringList
object. A property is identified by one or more GUIDs. An initial identifier is assigned automatically to a property by the server when you create it. You can later assign additional identifiers, known as alias IDs, to a property to allow it to be searched across multiple object stores.
In Java applications, an object value can be read from the appropriate getter method or set by the appropriate setter method (if the property has read/write access). In C# or Visual Basic applications, object properties can be read or set directly using dot notation.
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 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. 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 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. Once it is instantiated, an object's metadata can be accessed from the ClassDescription
object returned by its ClassDescription object-valued property. All of a ClassDescription
object's properties (including all of the PropertyDescription
objects 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 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.
Each property description holds the immutable (read-only) metadata properties used to describe a single property associated with a particular class instance and is contained in an ordered list 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:
PropertySettability
constant, which indicates how the value of a property can be set.In addition, every property description object has a type-specific form of the following properties:
PropertyDescriptionString
object, the property is PropertyDefaultString. PropertyDescriptionObject
object, the property is PropertySelectionsObject. PropertyDescriptionId
and PropertyDescriptionObject
, a property that specifies the maximum value allowed for the property. For example, in a PropertyDescriptionString
object, the property is MaximumLengthString. 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:
A system property is a property that is integral to a Content Engine object and can neither be added to nor 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. You can also modify certain metadata properties of a custom property even after it has been created. Each custom property is based on a property template that is specified by the PropertyTemplate property of its property definition.
To add a new 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. Once you have created 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 via a class definition; only a custom property can be assigned.
To add a custom property to a class, follow these steps:
Factory.ClassDefinition.fetchInstance
method). The AllowsPropertyAdditions property of the class definition must have a value of true
. 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 ability to set four system properties (Creator, DateCreated, Modifier, and LastModifier) is provided via 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
.
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 re-use of properties both within and across object stores and support localization as a single point of modification for the 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 localization strings for the DisplayName and DescriptiveText properties. Once 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. A given 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:
IdList
object containing a list of optional alias IDs for a property.ChoiceList
object that represents the discrete set of possible values that a property can hold.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. LocalizedStringList
object containing 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. PropertyPersistence
constant that indicates whether a property can be made persistent (that is, have its state stored in a database).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:
PropertyTemplateString
object, the property is PropertyDefaultString. PropertyTemplateId
and PropertyTemplateObject
, a property that specifies the maximum value allowed for the property. For example, in a PropertyTemplateString
object, the property is MaximumLengthString. 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:
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:
IdList
object containing a list of optional alias IDs for the property.ChoiceList
object that represents the discrete set of possible values that the property can hold.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:
PropertyDefinitionString
object, the property is PropertyDefaultString. PropertyDefinitionId
and PropertyDefinitionObject
, a property that specifies the maximum value allowed for the property. For example, in a PropertyDefinitionString
object, the property is MaximumLengthString. 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:
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 intended for a binary value. PropertyBoolean
: Represents a property that holds a Boolean value. PropertyContent
: Represents a property that holds an InputStream
object 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.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:
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. 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:
Properties
object's get
method and specify the name of the property to retrieve.Property
object in a Properties
object collection by using the iterator
() method.Property
object in a Properties
object collection by using the ForEach
command.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:
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.Property
object, call its setValue
method and set its parameter to the new property value. Property
object, call its setObjectValue
method and set its parameter to the new property value. When reading or setting a property, you should be aware of the following:
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.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. 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.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:
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. 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 may change over time; to keep the local object current, call its refresh
method.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:
refresh
method. If the same object already has a set of properties in the properties cache, the entire set will be discarded.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:
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.
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 may 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 retrieving properties from objects, 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
Property name | Data type returned | Cardinality |
---|---|---|
Creator | String | Single |
DateCreated | DateTime | Single |
Reservation | Document object | Single |
FoldersFiledIn | Folder object | Enum |
Folder object
Property name | Data type returned | Cardinality |
---|---|---|
Creator | String | Single |
DateCreated | DateTime | Single |
ContainedDocuments | Document object | Single |
SubFolders | Folder object | Enum |
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:
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:
PropertyState
constant class. 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:
Document.get_Reservation
will retrieve the reservation object directly from the local property cache instead of from the server. API_PROPERTY_NOT_IN_CACHE
exception is returned. Performance-sensitive applications that wish to minimize server round trips may 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();
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.
A PropertyFilter
object has the following components:
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. 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. 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 may 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:
true
) or one level deeper (false
). Set this value via the setLevelDependents
method. For more information, see Dependent Objects. setMaxRecursion
method. For more information, see Property Recursion. setMaxSize
method. 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.
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 may 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:
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. 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.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.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. To resolve potential conflicts when a property is specified by more than one means, the following property filter precedence rules apply:
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). 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 objectDocument
object #2 [1]: Child object of Document
object #1Folder
objects [2]: Child objects of Document
object #2When 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:
FilterElement
object in an IncludeProperty or IncludeType specification has a value for maxRecursion, that value is used.getMaxRecursion
method of the PropertyFilter
object is used. 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
API_PROPERTY_NOT_IN_CACHE
error. Object-valued properties
API_PROPERTY_NOT_IN_CACHE
error).For code examples demonstrating how to use the maxRecursion attribute, see Working with Properties.
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:
FilterElement
object in an IncludeProperty or IncludeType specification has a value for levelDependents, that value is used. getLevelDependents
method of the PropertyFilter
object is used. 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 demonstrating how to use the levelDependents attribute, see Working with Properties.