Scripting Object - VcPropertyCollector

Attribute of
VcSdkConnection, VcServiceContent
Returned by
createPropertyCollector

Scripting Object Description

The VcPropertyCollector managed object retrieves and detects changes to the properties of other managed objects. The VcPropertyCollector method provides one-time property retrieval. The VcPropertyCollector 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:

Attributes

Name Type Description
filter*VcPropertyFilter []

The filters that this VcPropertyCollector uses to determine the list of properties for which it detects incremental changes.
idstring

returns the id of this ManagedObject
referenceVcManagedObjectReference

returns the ManagedObjectReference of this ManagedObject
sdkConnectionVcSdkConnection

returns the parent SdkConnection
vimHostVcSdkConnection

returns the parent SdkConnection (deprecated)
vimTypestring

returns the type of this ManagedObject
*May not be present

Methods

Methods defined in this Scripting Object
cancelRetrievePropertiesEx, cancelWaitForUpdates, checkForUpdates, continueRetrievePropertiesEx, createFilter, createPropertyCollector, createTrigger, destroyPropertyCollector, retrieveProperties, retrievePropertiesEx, waitForUpdates, waitForUpdatesEx

createFilter

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

Parameters

NameTypeDescription
specVcPropertyFilterSpec

The specifications for the filter.
partialUpdatesboolean

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
VcPropertyFilter

retrieveProperties

Deprecated.

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

Parameters

NameTypeDescription
specSetVcPropertyFilterSpec []

Specifies the properties to retrieve.

Return Value

Type Description
VcObjectContent []

checkForUpdates

Deprecated.

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

Parameters

NameTypeDescription
version*string

The data version currently known to the client. The value must be either
*Need not be set

Return Value

Type Description
VcUpdateSet

waitForUpdates

Deprecated.

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

Parameters

NameTypeDescription
version*string

The data version currently known to the client. The value must be either
*Need not be set

Return Value

Type Description
VcUpdateSet

cancelWaitForUpdates

Attempts to cancel outstanding calls to VcPropertyCollector or VcPropertyCollector 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 VcRequestCanceled fault.

Parameters

NameTypeDescription
None

Return Value

Type Description
None

waitForUpdatesEx

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

VcPropertyCollector may return only partial update calculations. See VcUpdateSet for a more detailed explanation. VcPropertyCollector may also return null after a timeout, either as requested by VcWaitOptions or due to VcPropertyCollector policy.

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

Parameters

NameTypeDescription
version*string

The data version currently known to the client. The value must be either
options*VcWaitOptions

Additional options controlling the change calculation. If omitted, equivalent to an options argument with no fields set.
*Need not be set

Return Value

Type Description
VcUpdateSet

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

Parameters

NameTypeDescription
specSetVcPropertyFilterSpec []

Specifies the properties to retrieve.
optionsVcRetrieveOptions

Additional method options. If omitted, equivalent to an options argument with no fields set.

Return Value

Type Description
VcRetrieveResult

continueRetrievePropertiesEx

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

Parameters

NameTypeDescription
tokenstring

the token returned in the previous VcRetrieveResult returned on the same session by the same VcPropertyCollector.

Return Value

Type Description
VcRetrieveResult

cancelRetrievePropertiesEx

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

Parameters

NameTypeDescription
tokenstring

the token returned in the previous VcRetrieveResult returned on the same session by the same VcPropertyCollector.

Return Value

Type Description
None

createPropertyCollector

Creates a new session-specific VcPropertyCollector that can be used to retrieve property updates independent of any other VcPropertyCollector. The newly created VcPropertyCollector is not tied to the creating VcPropertyCollector in any way and exists until it is destroyed by a call to VcPropertyCollector or until the session on which the PropertyCollector was created is closed. This is in contrast to the default VcPropertyCollector, 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 VcPropertyCollector can be useful when multiple modules or even multiple clients that share the same session need to create their own VcPropertyFilter objects and process updates independently. They may also be useful to allow important updates to be seen on one VcPropertyCollector while a large update is being calculated on another. The underlying issue that this addresses is that any call to VcPropertyCollector, VcPropertyCollector, or VcPropertyCollector does updates on all the filters created on a given VcPropertyCollector on a given session.

A more subtle use of multiple VcPropertyCollector 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 VcPropertyCollector on the same session cannot ever be created in parallel. This means that multiple calls to VcPropertyCollector, VcPropertyCollector, or VcPropertyCollector made to the same VcPropertyCollector 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 VcPropertyCollector instances allows the server to handle these calculations in parallel.

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

Parameters

NameTypeDescription
None

Return Value

Type Description
VcPropertyCollector

destroyPropertyCollector

Destroys this VcPropertyCollector.

A VcPropertyCollector that was created by VcPropertyCollector 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 VcPropertyCollector provided by a service is not session specific and may not be destroyed.

Parameters

NameTypeDescription
None

Return Value

Type Description
None

createTrigger

Create a trigger from this ManagedObject

Parameters

NameTypeDescription
timeoutnumber

Waiting timout in seconds
filterstring

The monitored vCenter API filter
conditionstring

The condition in OGNL language
filterToSync*string

The vCenter API filter used to synchronize the content of the session
*Need not be set

Return Value

Type Description
Trigger