Retrieve Properties with the PropertyCollector

The following procedure shows how to retrieve properties of managed objects by using the RetrievePropertiesEx method. The procedure steps are illustrated by code fragments.

This procedure shows only the task of using the PropertyCollector. For a description of server connection, see Build a Simple vSphere Client Application for the Web Services SDK. You can also see these code fragments in the context of an end-to-end example that includes connection and authentication logic, in Build a Simple vSphere Client Application for the Web Services SDK.

To do a single retrieval operation with the PropertyCollector, use the following steps.

Procedure

Get references to the ViewManager and the PropertyCollector.
In the example, sContent is the variable for the ServiceContent data object. sContent provides the methods to retrieve the managed object references to the vSphere services.
```
ManagedObjectReference viewMgrRef = sContent.getViewManager();
ManagedObjectReference propColl = sContent.getPropertyCollector();
```
Create a container view for virtual machines.
methods is the variable for the VimPortType object. VimPortType defines the Java methods that correspond to the vSphere API methods. The createContainerView parameters container (the inventory root folder, returned by the method sContent.getRootFolder) and type (“Virtual Machine”) direct the ViewManager to select virtual machines, starting at the root folder. The value true for the recursive parameter extends the selection beyond the root folder so that the ViewManager will follow child folder paths to add virtual machines to the view. The container view provides references to all virtual machines in the inventory.
```
List<String> vmList = new ArrayList<String>();
vmList.add("VirtualMachine");

ManagedObjectReference cViewRef = methods.createContainerView(viewMgrRef,
    sContent.getRootFolder(), 
    vmList,
    true );
```
Create an object specification to define the starting point for inventory navigation.
The ObjectSpec.obj property identifies the starting object (the container view). This example collects only virtual machine data, so the skip property is set to true to ignore the container view itself during collection.
```
ObjectSpec oSpec = new ObjectSpec();
oSpec.setObj(cViewRef);
oSpec.setSkip(true);
```
Create a traversal specification to identify the path for collection.
The TraversalSpec properties type and path determine path traversal. TraversalSpec.type identifies an object type. TraversalSpec.path identifies a property in the type object. The PropertyCollector uses the path object to select additional objects.

This example uses a single TraversalSpec to walk the list of virtual machines that are available through the container view. The following code fragment specifies the ContainerView object for the TraversalSpec.type property and the view property in the ContainerView for the TraversalSpec.path property. The skip property is set to false, so the PropertyCollector will collect data from the path objects (the virtual machines in the container view).
```
TraversalSpec tSpec = new TraversalSpec();
tSpec.setName("traverseEntities");
tSpec.setPath("view");
tSpec.setSkip(false);
tSpec.setType("ContainerView");
```
Add the TraversalSpec to the ObjectSpec.selectSet array.
```
oSpec.getSelectSet().add(tSpec);
```
Identify the properties to be retrieved.
The example program creates a PropertySpec data object to specify the properties to be collected. The type property is set to VirtualMachine to match the object selections in the container view. The pathSet property identifies one or more properties in the type object.

This example specifies the VirtualMachine.name property.
```
PropertySpec pSpec = new PropertySpec();
pSpec.setType("VirtualMachine");
pSpec.getPathSet().add("name");
```
Add the object and property specifications to the property filter specification.
A PropertyFilterSpec must have at least one ObjectSpec and one PropertySpec.
```
PropertyFilterSpec fSpec = new PropertyFilterSpec();
fSpec.getObjectSet().add(oSpec);
fSpec.getPropSet().add(pSpec);
```

Create a list for the filters and add the spec to it.

List<PropertyFilterSpec> fSpecList = new ArrayList<PropertyFilterSpec>();
fSpecList.add(fSpec);

Retrieve the data.
To invoke a single property collection operation, call the RetrievePropertiesEx method. The example application passes the populated PropertyFilterSpec and an empty options structure to the method. The default for the RetrieveOptions.maxObjects specifies that no maximum for the number of objects that can be returned is set. The PropertyCollector can impose a maximum. If the number of collected objects is greater than the maximum, the PropertyCollector returns a token value in the RetrieveResult data object and this token is used to retrieve the remaining properties using the ContinueRetrievePropertiesEx API method. For more information, see Server Data Transmission.
```
RetrieveOptions ro = new RetrieveOptions();
RetrieveResult props = methods.retrievePropertiesEx(propColl,fSpecList,ro);
```

Print the virtual machine names.

The following code fragment walks the list of ObjectContent objects returned in the RetrieveResult object. For each object (ObjectContent), the inner loop prints the name-value pairs.

if (props != null) {
   for (ObjectContent oc : props.getObjects()) {
   String vmName = null;
   String path = null;
   List<DynamicProperty> dps = oc.getPropSet();
   if (dps != null) {
      for (DynamicProperty dp : dps) {
         vmName = (String) dp.getVal();
         path = dp.getName();
         System.out.println(path + " = " + vmName);
      }
   }
}