IBM FileNet P8, Version 5.2            

Properties

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 Classes.

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:

A property can hold the following data types:

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.

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, 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.

Property Descriptions

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:

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

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

PropertyDescriptionObject objects include the following additional properties:

System and Custom 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. The Content Engine allows you to define custom properties as a means of extending the system metadata. 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:

  1. Obtain an object reference to the class definition belonging 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.

Starting with the 4.5.1 release, a metadata prefix-naming convention for property and class symbolic names has been defined for the P8 Content Engine. All new properties and classes introduced in this release or later, by any IBM® ECM product that produces its own Content Engine feature AddOn, 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.

Details of the prefix-naming convention are given below:

Starting with the 4.5.1 release, any IBM ECM product that produces its own feature AddOn 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 prior to this release will continue to use it instead.

The following list of AddOn metadata prefixes are reserved:

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 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.

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 re-use 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. 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:

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:

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

PropertyTemplateObject objects include the following additional property:

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:

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

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

PropertyDefinitionObject objects include the following additional properties:

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:

Metaproperty Modifiable on property template? Modifiable on property definition? Property template change reflected on property definition? Property definition change automatically propagated to subclasses?
AliasIds yes yes no yes
AllowsForeignObject yes yes no no
AuditAs yes yes no yes
Cardinality No, settable only on create no n/a n/a
ChoiceList yes yes no yes 1
CopytoReservation n/a yes n/a no
Creator no, requires AccessRight.PRIVILEGED_WRITE to change n/a n/a n/a
DateCreated no, requires AccessRight.PRIVILEGED_WRITE to change n/a n/a n/a
DateLastModified no, requires AccessRight.PRIVILEGED_WRITE to change n/a n/a n/a
DescriptiveTexts yes n/a/ yes (with ProperteryDefinition.DescriptiveText) n/a
DisplayNames yes n/a yes (with ProperteryDefinition.DisplayName) n/a
ExternalAliases n/a yes n/a yes 1
IsHidden yes yes no no
IsNameProperty yes yes no no
IsValueRequired yes yes no no
LastModifier no, requires AccessRight.PRIVILEGED_WRITE to change n/a n/a n/a
MaximumLengthBinary yes yes no yes, only if made smaller
MaximumLengthString yes yes no yes, only if made smaller
ModificationAccessRequired yes yes no no
Owner yes n/a n/a n/a
Permissions yes n/a n/a n/a
PersistenceType no, settable only on create no n/a n/a
PropertyDefaultBoolean yes yes no no
PropertyDefaultBinary yes yes no no
PropertyDefaultDateTime yes yes no no
PropertyDefaultFloat64 yes yes no no
PropertyDefaultId yes yes no no
PropertyDefaultInteger32 yes yes no no
PropertyDefaultString yes yes no no
PropertyDisplayCategory yes n/a n/a n/a
PropertyMaximumDateTime yes yes no yes, only if made smaller
PropertyMaximumFloat64 yes yes no yes, only if made smaller
PropertyMaximumInteger32 yes yes no yes, only if made smaller
PropertyMinimumDateTime yes yes no yes, only if made larger
PropertyMinimumFloat64 yes yes no yes, only if made larger
PropertyMinimumInteger32 yes yes no yes, only if made larger
RequiresUniqueElements no, settable only on create no n/a n/a
SecurityProxyType yes yes no yes
Settability yes yes no yes, only if made more restrictive
SymbolicName yes no yes no

1 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

Multiple-valued properties

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:

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

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:

Special Situations

When reading or setting a property, you should be aware of the following:

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

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:

  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:

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:

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:

Property Precedence Rules

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

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:

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 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 demonstrating how to use the levelDependents attribute, see Working with Properties.



Feedback

Last updated: October 2013
property_concepts.htm

© Copyright IBM Corporation 2014.
This information center is powered by Eclipse technology. (http://www.eclipse.org)