# 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

The PropertyCollector managed object retrieves and detects changes to the properties of other managed objects. The RetrievePropertiesEx method provides one-time property retrieval. The WaitForUpdatesEx method provides incremental change detection and supports both polling and notification.

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

Name | Type | Description
--- | --- | ---
filter* P | ManagedObjectReference[] to a PropertyFilter[] | The filters that this PropertyCollector uses to determine the list of properties for which it detects incremental changes.

*May not be presentP Required privilege: System.View

Methods

Methods defined in this Managed Object
CancelRetrievePropertiesEx, CancelWaitForUpdates, CheckForUpdates, ContinueRetrievePropertiesEx, CreateFilter, CreatePropertyCollector, DestroyPropertyCollector, RetrieveProperties, RetrievePropertiesEx, WaitForUpdates, WaitForUpdatesEx

# CancelRetrievePropertiesEx(cancelRetrievePropertiesEx)

Discards remaining results from a retrieval started by RetrievePropertiesEx on the same session on the same PropertyCollector.

Required Privileges
  System.Read
Since
  vSphere API 4.1

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the PropertyCollector used to make the method call.
token P | xsd:string | the token returned in the previous RetrieveResult returned on the same session by the same PropertyCollector. Since vSphere API 4.1

P Required privilege: token

Return Value

Type | Description
--- | ---
None

Faults

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

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CancelRetrievePropertiesEx" type="vim25:CancelRetrievePropertiesExRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CancelRetrievePropertiesExResponse"> <complexType/> </element>

# CancelWaitForUpdates(cancelWaitForUpdates)

Attempts to cancel outstanding calls to WaitForUpdates or WaitForUpdatesEx in the current session. If an update calculation is in process this method has no effect. If an update calculation is not in process any waiting calls complete quickly and report a RequestCanceled fault.

Required Privileges
  System.View

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the PropertyCollector used to make the method call.

Return Value

Type | Description
--- | ---
None

Faults

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

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CancelWaitForUpdates" type="vim25:CancelWaitForUpdatesRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CancelWaitForUpdatesResponse"> <complexType/> </element>

# CheckForUpdates(checkForUpdates)

Deprecated. As of vSphere API 4.1, use WaitForUpdatesEx with a maxWaitSeconds of 0.

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

Required Privileges
  System.View

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the PropertyCollector used to make the method call.
version* P | xsd:string | The data version currently known to the client. The value must be either the special initial version (an empty string) a data version returned from CheckForUpdates or WaitForUpdates by the same PropertyCollector on the same session. a non-truncated data version returned from WaitForUpdatesEx by the same PropertyCollector on the same session. Since vmodl.query.version.version1

*Need not be set P Required privilege: version

Return Value

Type | Description
--- | ---
UpdateSet | Changes since the passed in data version. If no updates are pending, then this method returns null.

Faults

Type | Description
--- | ---
InvalidCollectorVersion | Thrown if the data version does not meet the requirements above.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CheckForUpdates" type="vim25:CheckForUpdatesRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CheckForUpdatesResponse"> <complexType> <sequence> <element name="returnval" type="vim25:UpdateSet" minOccurs="0"/> </sequence> </complexType> </element>

# ContinueRetrievePropertiesEx(continueRetrievePropertiesEx)

Retrieves additional results from a retrieval started by RetrievePropertiesEx on the same session on the same PropertyCollector.

Required Privileges
  System.Read
Since
  vSphere API 4.1

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the PropertyCollector used to make the method call.
token P | xsd:string | the token returned in the previous RetrieveResult returned on the same session by the same PropertyCollector. Since vSphere API 4.1

P Required privilege: token

Return Value

Type | Description
--- | ---
RetrieveResult | retrieved objects.

Faults

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

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ContinueRetrievePropertiesEx" type="vim25:ContinueRetrievePropertiesExRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ContinueRetrievePropertiesExResponse"> <complexType> <sequence> <element name="returnval" type="vim25:RetrieveResult"/> </sequence> </complexType> </element>

# CreateFilter(createFilter)

Creates a new filter for the given set of managed objects.

Required Privileges
  System.View

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the PropertyCollector used to make the method call.
spec P | PropertyFilterSpec | The specifications for the filter. Since vmodl.query.version.version1
partialUpdates P | xsd: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. Since vmodl.query.version.version1

PRequired privilege - see tooltip for details

Return Value

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

Faults

Type | Description
--- | ---
InvalidProperty | Thrown if "spec" has a property that is not defined on one of the objects.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreateFilter" type="vim25:CreateFilterRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreateFilterResponse"> <complexType> <sequence> <element name="returnval" type="vim25:ManagedObjectReference"/> </sequence> </complexType> </element>

# CreatePropertyCollector(createPropertyCollector)

Creates a new session-specific PropertyCollector that can be used to retrieve property updates independent of any other PropertyCollector. The newly created PropertyCollector is not tied to the creating PropertyCollector in any way and exists until it is destroyed by a call to DestroyPropertyCollector or until the session on which the PropertyCollector was created is closed. This is in contrast to the default PropertyCollector, which always exists, but still has session-specific data such as filters and unfinished update calculations that are discarded when the associated session is closed.

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

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the PropertyCollector used to make the method call.

Return Value

Type | Description
--- | ---
ManagedObjectReference to a PropertyCollector | A reference to the new PropertyCollector.

Faults

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

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreatePropertyCollector" type="vim25:CreatePropertyCollectorRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreatePropertyCollectorResponse"> <complexType> <sequence> <element name="returnval" type="vim25:ManagedObjectReference"/> </sequence> </complexType> </element>

# DestroyPropertyCollector(destroy)

Destroys this PropertyCollector.

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

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the PropertyCollector used to make the method call.

Return Value

Type | Description
--- | ---
None

Faults

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

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="DestroyPropertyCollector" type="vim25:DestroyPropertyCollectorRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="DestroyPropertyCollectorResponse"> <complexType/> </element>

# RetrieveProperties(retrieveContents)

Deprecated. As of vSphere API 4.1, use RetrievePropertiesEx.

Retrieves the specified properties of the specified managed objects.

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

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the PropertyCollector used to make the method call.
specSet P | PropertyFilterSpec[] | Specifies the properties to retrieve. Since vmodl.query.version.version1

P Required privilege: specSet

Return Value

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

Faults

Type | Description
--- | ---
InvalidProperty | See CreateFilter
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RetrieveProperties" type="vim25:RetrievePropertiesRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RetrievePropertiesResponse"> <complexType> <sequence> <element name="returnval" type="vim25:ObjectContent" minOccurs="0" maxOccurs="unbounded"/> </sequence> </complexType> </element>

# RetrievePropertiesEx(retrievePropertiesEx)

Retrieves the specified properties of the specified managed objects.

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

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the PropertyCollector used to make the method call.
specSet P | PropertyFilterSpec[] | Specifies the properties to retrieve. Since vSphere API 4.1
options P | RetrieveOptions | Additional method options. If omitted, equivalent to an options argument with no fields set. Since vSphere API 4.1

PRequired privilege - see tooltip for details

Return Value

Type | Description
--- | ---
RetrieveResult | retrieved objects or null if there are no matching objects.

Faults

Type | Description
--- | ---
InvalidProperty | See CreateFilter
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RetrievePropertiesEx" type="vim25:RetrievePropertiesExRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RetrievePropertiesExResponse"> <complexType> <sequence> <element name="returnval" type="vim25:RetrieveResult" minOccurs="0"/> </sequence> </complexType> </element>

# WaitForUpdates(waitForUpdates)

Deprecated. As of vSphere API 4.1, use WaitForUpdatesEx.

Calculate the set of updates for each existing filter in the session, returning when at least one filter has updates.

Required Privileges
  System.View

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the PropertyCollector used to make the method call.
version* P | xsd:string | The data version currently known to the client. The value must be either the special initial version (an empty string) a data version returned from CheckForUpdates or WaitForUpdates by the same PropertyCollector on the same session a non-truncated data version returned from WaitForUpdatesEx by the same PropertyCollector on the same session. Since vmodl.query.version.version1

*Need not be set P Required privilege: version

Return Value

Type | Description
--- | ---
UpdateSet | Changes since the passed in data version.

Faults

Type | Description
--- | ---
InvalidCollectorVersion | Thrown if the data version does not meet the requirements above.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="WaitForUpdates" type="vim25:WaitForUpdatesRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="WaitForUpdatesResponse"> <complexType> <sequence> <element name="returnval" type="vim25:UpdateSet"/> </sequence> </complexType> </element>

# WaitForUpdatesEx(waitForUpdatesEx)

Calculate the set of updates for each existing filter in the session.

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

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the PropertyCollector used to make the method call.
version* P | xsd:string | The data version currently known to the client. The value must be either the special initial data version (an empty string), a data version returned from CheckForUpdates or WaitForUpdates a non-truncated data version returned from WaitForUpdatesEx a truncated data version returned from the last call to WaitForUpdatesEx with no intervening calls to WaitForUpdates or CheckForUpdates. Since vSphere API 4.1
options* P | WaitOptions | Additional options controlling the change calculation. If omitted, equivalent to an options argument with no fields set. Since vSphere API 4.1

*Need not be set PRequired privilege - see tooltip for details

Return Value

Type | Description
--- | ---
UpdateSet | Changes since the passed in version or null if there are no changes.

Faults

Type | Description
--- | ---
InvalidCollectorVersion | Thrown if the data version does not meet the requirements above.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="WaitForUpdatesEx" type="vim25:WaitForUpdatesExRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="WaitForUpdatesExResponse"> <complexType> <sequence> <element name="returnval" type="vim25:UpdateSet" minOccurs="0"/> </sequence> </complexType> </element>