Managed Object - PropertyCollector

Property of
ServiceContent
See also
ObjectContent, PropertyFilter, PropertyFilterSpec, UpdateSet

Managed Object Description

PropertyCollector is the managed object type that clients use to retrieve a set of properties from one or more managed objects. Clients can also use the PropertyCollector to determine when any of the properties have changed. The change detection mechanism supports both polling and notification to detect property changes.

To decrease network traffic when collecting updates, a client creates one or more property collector filters to specify the parts of a managed object in which the client is interested.

All property collector state information is session-specific:

Properties

Name Type Description
filter* PManagedObjectReference[]
to a PropertyFilter[]
The filters that this property collector uses to determine the list of properties to retrieve and observe for changes.
*May not be presentP Required privilege: System.View

Methods

Methods defined in this Managed Object
CancelWaitForUpdates, CheckForUpdates, CreateFilter, RetrieveProperties, WaitForUpdates

CancelWaitForUpdates

Cancels an outstanding WaitForUpdates, if any. The outstanding waitForUpdates operation completes by throwing the Canceled fault.
Required Privileges
System.View

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PropertyCollector used to make the method call.

Return Value

Type Description
None

Faults

Type Description
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition



CheckForUpdates

Checks for updates on properties specified by the union of all current filters. If no updates are pending, this method returns null.

The return value contains the changes between the previous version and the current values of the properties. The result includes a new version string the client passes in order to receive further updates.

Required Privileges
System.View

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PropertyCollector used to make the method call.
version*xsd:string The data version currently known to the client. The value must be either the special initial version (an empty string), or a data version string that was returned from a previous call to CheckForUpdates or WaitForUpdates.
*Need not be set

Return Value

Type Description
UpdateSetChanges since the last updated version. If no updates are pending, then this method returns null.

Faults

Type Description
InvalidCollectorVersionThrown if the version string is out-of-date or invalid.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition



CreateFilter

Creates a new filter for the given set of managed objects.
Required Privileges
System.View

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PropertyCollector used to make the method call.
specPropertyFilterSpec The specifications for the filter.
partialUpdatesxsd:boolean Flag to specify whether a change to a nested property should report only the nested change or the entire specified property value. If the value is true, a change should report only the nested property. If the value is false, a change should report the enclosing property named in the filter.

Return Value

Type Description
ManagedObjectReference
to a PropertyFilter
A reference to the new filter.

Faults

Type Description
InvalidArgumentThrown if any of the following is true:
  • "spec" is empty.
  • "spec" contains a selection with properties not defined on its type.
InvalidPropertyThrown if "spec" has a property that is not defined on one of the objects.
InvalidTypeThrown if "spec" contains, directly or indirectly, a type name that does not refer to a known type.
ManagedObjectNotFoundThrown if "spec" refers to objects that are not present on the server
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition



RetrieveProperties

Retrieves the specified properties of the specified managed objects.

This method is equivalent to creating a filter for the given objects and property specification set, then receiving the property values, and finally destroying the filter. If you want to monitor the contents of an object, you should use either CheckForUpdates or WaitForUpdates.

Required Privileges
System.View

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PropertyCollector used to make the method call.
specSetPropertyFilterSpec[] The specifications for the properties to retrieve.

Return Value

Type Description
ObjectContent[]The data contents of the specified objects.

Faults

Type Description
InvalidArgumentThrown if any of the following is true:
  • "specSet" is empty.
  • "specSet" contains a selection with properties not defined on its type.
InvalidPropertyThrown if "specSet" has a property not defined on one of the objects.
InvalidTypeThrown if "specSet" contains, directly or indirectly, a type name that does not refer to a known type.
ManagedObjectNotFoundThrown if "specSet" refers to objects that are not present on the server
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition



WaitForUpdates

Waits for updates on properties specified by the union of all current filters. Unlike checkForUpdates, this method waits until updates are available before it completes.

The return value contains the changes between the previous version and the current values of the properties. The result includes a new version string the client passes in order to receive further updates.

Required Privileges
System.View

Parameters

NameTypeDescription
_thisManagedObjectReference A reference to the PropertyCollector used to make the method call.
version*xsd:string The data version currently known to the client. The value must be either the special initial version (an empty string), or a data version string that was returned from a previous call to CheckForUpdates or WaitForUpdates.
*Need not be set

Return Value

Type Description
UpdateSetChanges since the last updated version.

Faults

Type Description
InvalidCollectorVersionThrown if the version string is out-of-date or invalid.
RequestCanceledThrown if CancelWaitForUpdates has been called or another WaitForUpdates has been issued.
RuntimeFaultThrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition