Example: Simple PropertyCollector Example (Java) uses a ContainerView to specify the objects that start the collection process. This is the simplest way to set up a filter, using a single reference to a view to provide the PropertyCollector with access to a set of objects. To select objects from the inventory, a filter includes TraversalSpec and possibly SelectionSpec objects. Use these objects to make object selections based on the references in a view, and to extend inventory traversal beyond those objects (or beyond the object specified in ObjectSpec.obj).
Use a TraversalSpec object to identify a managed object type and a traversal property in that type. TraversalSpec contains the following properties:
|
■
|
type – identifies an inventory object type.
|
|
■
|
path – specifies a managed object reference property in the type object. This property provides the traversal path extending from this object.
|
|
■
|
selectSet – specifies an optional list of selection objects for additonal object traversal paths. The PropertyCollector applies the TraversalSpec objects in the selectSet array to the result of the traversal (the target of TraversalSpec.path). The selectSet array can also contain SelectionSpec objects; a SelectionSpec is a reference to a TraversalSpec. See SelectionSpec Traversal.
|
|
■
|
skip – indicates whether to collect properties for the path object.
|
During inventory traversal, the PropertyCollector applies the PropertySpec object or objects (PropertyFilterSpec.propSet) to objects. Inventory traversal begins with the object identified by ObjectSpec.obj and continues by following TraversalSpec paths. If PropertySpec.type matches the current object type, and the skip property is false, the PropertyCollector sends the PropertySpec.pathSet properties to your client.
Inventory Navigation is a representation of a PropertyFilterSpec that defines traversal of VirtualMachine objects. The filter uses a ContainerView as a starting point. The TraversalSpec for the ContainerView specifies the view property for access to the view’s virtual machines. The figure shows TraversalSpec objects that extend navigation from a VirtualMachine object to the associated Network and ResourcePool objects. The PropertyCollector applies these TraversalSpec objects to each of the VirtualMachine objects in the view list. The figure also shows the PropertySpec objects for collecting data from VirtualMachine, Network, and ResourcePool objects.
Example: Inventory Traversal shows a Java code fragment, based on Example: Simple PropertyCollector Example (Java), that implements the inventory traversal shown in Inventory Navigation.
|
1
|
Create a ContainerView for virtual machines.
|
|
2
|
Create an ObjectSpec that uses the container view as the collection starting point.
|
|
3
|
|
4
|
Create additional TraversalSpec objects to select additional objects.
|
The SelectSet list for the container view TraversalSpec has two TraversalSpec objects. Both specify a VirtualMachine object context. One object uses the network property to extend traversal to the Network managed object. The other uses the resourcePool property to extend traversal to the ResourcePool managed object.
|
5
|
To retrieve properties that are embedded in data objects, the PropertySpec.PathSet property uses dot notation to specify the property paths.
Example: Inventory Traversal
The selectSet array in ObjectSpec and TraversalSpec objects can include TraversalSpec objects and SelectionSpec objects. SelectionSpec is the base class for TraversalSpec objects. SelectionSpec defines the name property. You can use a SelectionSpec object in a selectSet array as a reference to a named TraversalSpec object. By using SelectionSpec references, you can reuse a TraversalSpec and you can define recursive traversal.
Use SelectionSpec references to avoid writing duplicate TraversalSpec declarations. The TraversalSpec identified in a SelectionSpec reference must be within the same PropertyFilterSpec. SelectionSpec Reference shows the use of SelectionSpec references to a virtual machine TraversalSpec. The SelectionSpec references are associated with Network and Datastore traversals.
If the ObjectSpec.selectSet array contains a SelectionSpec, the referenced TraversalSpec must identify the same object type. TraversalSpec.type must match the type of the object specified in ObjectSpec.obj. The PropertyCollector applies the TraversalSpec to the object and use the TraversalSpec.path property to extend its traversal.
Use a SelectionSpec to apply a TraversalSpec to the results of its own traversal. To use a recursive filter construction, create a SelectionSpec that specifies the name of a TraversalSpec and add it to the named TraversalSpec selection set. The recursive construction extends inventory traversal beyond the paths directly represented by TraversalSpec objects.
You can use recursive traversal on any inventory objects that can be nested. See Inventory Hierarchies and ServiceInstance for a general representation of the structure of an inventory. For example, on a vCenter Server, folders can nest to arbitrary depths. To describe a traversal path through a succession of folders, you can add a SelectionSpec to the Folder TraversalSpec. The SelectionSpec must reference the TraversalSpec. Recursive TraversalSpec and SelectionSpec shows a representation of a TraversalSpec and its associated SelectionSpec for nested folder traversal.
Example: Nested Folder Traversal shows a Java code fragment that creates a recursive filter for nested folder traversal.
|
1
|
Use the SearchIndex managed object to retrieve the managed object reference for the top-level virtual machine folder.
|
This folder is used as the beginning of the inventory traversal. For more information see SearchIndex.
|
2
|
Create an ObjectSpec object that references the top-level virtual machine folder.
|
|
3
|
|
4
|
The TraversalSpec.path property identifies the Folder.childEntity property for traversal to any child objects.
|
5
|
|
6
|
|
7
|
|
8
|
Add the object and property specifications to the PropertyFilterSpec.
|
|
9
|
Call the RetrievePropertiesEx method.
|
Example: Nested Folder Traversal