Represents information, used in conjunction with one or more FilterElement objects, for controlling 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.

A PropertyFilter object has the following components:

  • Zero or more IncludeProperty specifications; each of which 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 using the appropriate PropertyFilter method. You specify each property to be retrieved by its symbolic name, or alternatively by its assigned GUID, in a space-separated list. In general, you should specify properties with their symbolic names using PropertyNames string constants and avoid the use of GUIDs.
  • Zero or more IncludeType specifications; each of which 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 using the appropriate PropertyFilter method.
  • Zero or more ExcludeProperty specifications; each of which specifies a single property, by identifier, to be excluded that would otherwise be included based on an IncludeProperty or IncludeType specification. You create an ExcludeProperty specification by calling the AddExcludeProperty method. You specify each property to be excluded by its symbolic name, or alternatively by its assigned GUID, in a space-separated list. In general, you should specify properties with their symbolic names using PropertyNames string constants and avoid the use of GUIDs.

In addition, a PropertyFilter object has attributes you can set that control how property values 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.
  • maxRecursion: A zero-based Integer that specifies the maximum allowable recursion depth to use when retrieving property relationships. This attribute determines the level of depth at which property values are included. If unspecified, the default is zero. Set this value via the SetMaxRecursion method.
  • 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 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 method.

Property filter precedence rules:

  • Properties specified in an ExcludeProperty specification override those specified in an IncludeType or IncludeProperty specification. That is, if the property is specified to be excluded in an ExcludeProperty specification, but 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 attributes from the IncludeProperty specification apply.
  • If a property is specified more than once in an IncludeProperty specification, only the attributes from the first appearance apply.
  • If a property type is specified by more than one means (for example, a PropertyFilter object has an IncludeType specification that specifies FilteredPropertyType.SINGLETON_STRING and another that specifies FilteredPropertyType.ANY_SINGLETON), the attributes from the most specific occurrence (in the previous example, the former specification) apply.
  • If a property type is specified more than once by the same means, only the attributes from the first appearance apply.

The following tables list the members exposed by PropertyFilter.

Public Constructors

 NameDescription
StaticPublic methodPropertyFilterOverloaded. Initializes a new instance of the PropertyFilter class.
Top

Protected Constructors

 NameDescription
StaticFamily methodPropertyFilterOverloaded. Initializes a new instance of the PropertyFilter class.
Top

Public Methods

 NameDescription
Public methodAddExcludePropertyAdds one or more properties to be excluded during an object retrieval or object refresh. Any properties specified for exclusion will override those properties that are specified in an IncludeProperty or IncludeType specification.
Public methodAddIncludePropertyOverloaded. Adds one or more properties, specified in a FilterElement object, to be included during an object retrieval or object refresh.
Public methodAddIncludeTypeOverloaded. Adds properties identified by type in a FilterElement object to be included during an object retrieval or object refresh. The property type can be specified in the FilterElement object by a single FilteredPropertyType constant or a space-separated list of type specifiers.
Public methodEqualsDetermines whether the specified Object is equal to the current Object. (inherited from Object)
Public methodGetExcludePropertiesReturns an array of ExcludeProperty specifications, each of which identifies the properties to be excluded during an object retrieval or object refresh. Any properties specified for exclusion will override those properties that are specified in an IncludeProperty or IncludeType specification.
Public methodGetHashCodeServes as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. (inherited from Object)
Public methodGetIncludePropertiesReturns an array of FilterElement objects, each of which identifies one or more properties to be included during an object retrieval or object refresh.
Public methodGetIncludeTypesReturns an array of FilterElement objects, each of which identifies properties to be included by type during an object retrieval or object refresh.
Public methodGetLevelDependentsReturns whether the recursion level that the property filter uses when retrieving a dependent object is the same as that of the independent object to which it belongs (True) or one level deeper (False). The returned value is a global value for this PropertyFilter object. You can set this value by calling one of the SetLevelDependents methods of this PropertyFilter object.
Public methodGetMaxRecursionReturns the maximum recursion depth for the property filter to use when retrieving property relationships. The returned value is the global value for this PropertyFilter object. You can set this value by calling one of the setMaxRecursion methods of this PropertyFilter object.
Public methodGetMaxSizeReturns the maximum size of content data that the property filter is allowed to retrieve. If this size is exceeded, no content data is retrieved. The returned value is a global value for this PropertyFilter object. You can set this value by calling the SetMaxSize method of this PropertyFilter object.
Public methodGetObjectDataThis method is exposed to satisfy the ISerializable interface.
Public methodGetPageSizeReturns 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 from the server during each fetch. You can set this value by calling one of the setPageSize methods of this PropertyFilter object.
Public methodGetTypeGets the Type of the current instance. (inherited from Object)
Public methodSetLevelDependentsOverloaded. Sets whether the recursion level that the property filter uses when retrieving a dependent object is the same as that of the independent object to which it belongs (True) or one level deeper (False). The value set is the global value for this PropertyFilter object. If the filter element of a property has a value for levelDependents, the server uses the filter element's value instead of this global value. If neither the global value nor the filter element value is specified, the default is False.
Public methodSetMaxRecursionOverloaded. Sets the maximum recursion depth for the property filter to use when retrieving property relationships. The value set is the global value for this PropertyFilter object. If the filter element of a property has a value for maxRecursion, the server uses the filter element's value instead of this global value. If neither the global value nor the filter element value is specified, the default is 0.
Public methodSetMaxSizeSets the maximum size of content data that the property filter is allowed to retrieve.
Public methodSetPageSizeOverloaded. Sets 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 from the server during each fetch. If the filter element of a property has a value for pageSize, the server uses the filter element's value instead of this global value. If neither the global value nor the filter element value is specified, 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.
Public methodToStringOverridden. Returns a String describing this PropertyFilter object. The string includes the object's class name and its maxRecursion, maxSize, pageSize, and levelDependents attributes. In addition, the string includes the object's list of included properties, list of included property types, and list of excluded properties.
Top

Protected Methods

 NameDescription
Family methodFinalizeAllows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (inherited from Object)
Family methodMemberwiseCloneCreates a shallow copy of the current Object. (inherited from Object)
Top

Explicit Interface Implementations

 NameDescription
StaticPrivate methodPropertyFilterOverloaded. Initializes a new instance of the PropertyFilter class.
Top

See Also