To maintain a client-side representation of server object state (by monitoring the properties for the inventory), use the CreateFilter and WaitForUpdatesEx methods. The WaitForUpdatesEx method supports an incremental retrieval model.
A PropertyCollector can have one or more associated PropertyFilter objects. A PropertyFilter has one or more associated PropertyFilterSpec objects. A PropertyFilterSpec that is used with the RetrievePropertiesEx method has a limited lifespan; the server destroys the filter after returning results to your client. For a sequence of incremental property collection operations, the WaitForUpdatesEx method relies on PropertyFilterSpec objects that are available for multiple calls to the method.
To create persistent property filter specifications, use the CreateFilter method. When you call CreateFilter, you pass a PropertyFilterSpec object to the method. The method adds the new filter to the PropertyCollector associated with the method invocation and returns a reference to the new filter. After you have created the filter, you can add additional PropertyFilterSpec objects. You cannot share a filter with a PropertyCollector in another session.
The WaitForUpdatesEx method supports a polling mechanism for property collection that is based on a specified wait time.
Specify the following parameters when you call WaitForUpdatesEx:
|
■
|
Managed object reference to a PropertyCollector instance.
|
|
■
|
version value that identifies a sequence value. The first time you call WaitForUpdatesEx, specify an empty string (““) to retrieve a complete set of results for the specified properties. Your subsequent calls should use the version value returned in the previous call. If you don’t include the version value, the server returns everything. For more information about data versions, see Server Data Transmission.
|
|
■
|
options specifying the amount of data to transmit in a single response (the WaitOptions.maxObjectUpdates property) and the number of seconds the PropertyCollector should wait for updates (the WaitOptions.maxWaitSeconds property).
|
The value of the WaitOptions.maxWaitSeconds property determines whether the PropertyCollector uses an instant retrieval or a polling model. When you call WaitForUpdatesEx with a wait time of 0, it checks for updates and returns immediately. When you call WaitForUpdatesEx with a wait time greater than 0, the method waits until the specified time or until a change. WaitForUpdatesEx blocks your process until updates occur or until it times out. The time-out is affected by the maxWaitSeconds value, the amount of time it takes to collect updated property values, and PropertyCollector policy.
If the property collection operation times out, and there are no updates to the requested properties, the PropertyCollector returns null for the WaitForUpdatesEx response.
|
■
|
maxWaitSeconds is an optional property. If you do not specify a value, the PropertyCollector waits as long as possible for updates. Therefore, if maxWaitSeconds is unset, the waitForUpdatesEx method will block the thread after all of the data has been retrieved, waiting for the TCP connection with the vSphere server to timeout. Your code can handle this in one of the following ways: call waitForUpdatesEx from a separate thread; look for specific updates and then stop calling the method; or change the TCP connection timeout [BindingProviderProperties.CONNECT_TIMEOUT].)
|
|
■
|
maxWaitSeconds set to zero specifies an immediate call and response. The PropertyCollector checks for updates for all properties specified by the union of all filters associated with that instance of the PropertyCollector. The PropertyCollector returns any results or null if there have been no updates.
|
|
■
|
maxWaitSeconds greater than zero specifies a wait followed by polling. The PropertyCollector returns null if no updates are available within maxWaitSeconds.
|
WaitForUpdatesEx Operations Compared lists some of the advantages and disadvantages of these two operations.
|
Returns only properties that have changed since the version specified. Returns changed data only, providing better network utilization than RetrieveProperties.
|
Returns an empty set even when nothing has changed on the server. Depending on your client application, this might be inefficient.
|
|
|
Blocks thread until an update occurs. Efficient use of network resources. The only operation that you can cancel.
|
Blocks processing thread until updates occur. However, this call can be cancelled so you can monitor the time the operation is taking and cancel if necessary.
|
The WaitForUpdatesEx method returns an UpdateSet data object, the composite data structure shown in UpdateSet Data Object Returned by WaitForUpdates Operations.
