Managed Object - PropertyCollector(vmodl.query.PropertyCollector)

Property of

ServiceContent

Returned by

CreatePropertyCollector

See also

ObjectContent, PropertyFilter, PropertyFilterSpec, RetrieveOptions, RetrieveResult, UpdateSet, WaitOptions

Since

vmodl.query.version.version1

Managed Object Description

For change detection a client creates one or more filters to specify the subset of managed objects in which the client is interested. Filters keep per-session state to track incremental changes. Because this state is per-session:

• A session cannot share its PropertyCollector filters with other sessions
• two different clients can share the same session, and so can share the same filters, but this is not recommended
• When a session terminates, the associated PropertyCollector filters are automatically destroyed.

Properties

Methods

CancelRetrievePropertiesEx(cancelRetrievePropertiesEx)

Required Privileges

System.Anonymous

Since

vSphere API 4.1

Parameters

Return Value

Faults

Events

CancelWaitForUpdates(cancelWaitForUpdates)

Required Privileges

System.View

Parameters

Return Value

Faults

Events

CheckForUpdates(checkForUpdates)

Required Privileges

System.View

Parameters

Return Value

Faults

Events

ContinueRetrievePropertiesEx(continueRetrievePropertiesEx)

Required Privileges

System.Anonymous

Since

vSphere API 4.1

Parameters

Return Value

Faults

Events

CreateFilter(createFilter)

Required Privileges

System.View

Parameters

Return Value

Faults

Events

CreatePropertyCollector(createPropertyCollector)

A new PropertyCollector can be useful when multiple modules or even multiple clients that share the same session need to create their own PropertyFilter objects and process updates independently. They may also be useful to allow important updates to be seen on one PropertyCollector while a large update is being calculated on another. The underlying issue that this addresses is that any call to WaitForUpdates, CheckForUpdates, or WaitForUpdatesEx does updates on all the filters created on a given PropertyCollector on a given session.

A more subtle use of multiple PropertyCollector objects is implied by the fact that the returned version value for the various updates calculations is strongly ordered. The only way this can make sense is that two different versions calculated on the same PropertyCollector on the same session cannot ever be created in parallel. This means that multiple calls to WaitForUpdates, CheckForUpdates, or WaitForUpdatesEx made to the same PropertyCollector on the same session on different threads of the same client, or even on different clients that share the same session are still handled on the server serially. Use of different PropertyCollector instances allows the server to handle these calculations in parallel.

Typically a service that supports the PropertyCollector managed object type will automatically create a default PropertyCollector and provide some way to obtain a reference to this PropertyCollector. If not, it will have to provide some service-specific way to create the a PropertyCollector.

Required Privileges

System.View

Since

vSphere API 4.1

Parameters

Return Value

Faults

Events

DestroyPropertyCollector(destroy)

A PropertyCollector that was created by CreatePropertyCollector is automatically destroyed when the session on which it was created is closed. This method can be used to destroy them explicitly.

An automatically created PropertyCollector provided by a service is not session specific and may not be destroyed.

Required Privileges

System.View

Since

vSphere API 4.1

Parameters

Return Value

Faults

Events

RetrieveProperties(retrieveContents)

This method is similar to creating the filters, receiving the property values, and destroying the filters. The main difference is that the output blends the results from all the filters and reports a given managed object at most once no matter how many filters apply.

The filter creation step can throw all of the same faults as CreateFilter.

Required Privileges

System.Anonymous

Parameters

Return Value

Faults

Events

RetrievePropertiesEx(retrievePropertiesEx)

This method is similar to creating the filters, receiving the property values, and destroying the filters. The main difference is that the output blends the results from all the filters and reports a given managed object at most once no matter how many filters apply.

The filter creation step can throw all of the same faults as CreateFilter.

Required Privileges

System.Anonymous

Since

vSphere API 4.1

Parameters

Return Value

Faults

Events

WaitForUpdates(waitForUpdates)

Required Privileges

System.View

Parameters

Return Value

Faults

Events

WaitForUpdatesEx(waitForUpdatesEx)

WaitForUpdatesEx may return only partial update calculations. See truncated for a more detailed explanation. WaitForUpdatesEx may also return null after a timeout, either as requested by maxWaitSeconds or due to PropertyCollector policy.

If an application uses waitForUpdatesEx it is strongly recommended that it not make concurrent calls to WaitForUpdates, CheckForUpdates, or WaitForUpdatesEx in the same session. Concurrent calls may cause suspended change calculations to be discarded.

Required Privileges

System.View

Since

vSphere API 4.1

Parameters

Return Value

Faults

Events