Data Service queries are passed to your Data Service Adapter through the com.vmware.data.query.RequestSpec object parameter.

A RequestSpec object consists of an array of objects of type com.vmware.data.query.QuerySpec, each of which represents an individual query. Each QuerySpec object defines the query target, the query constraints, and the expected formatting for the query results.

Query Target

A query target is a resource type for which your getData() method must retrieve properties. A QuerySpec can specify a number of targets within its ResourceSpec, by including an array of objects of type com.vmware.data.query.PropertySpec. Each target type is represented as a string in the field ResourceSpec.PropertySpec[x].type.

Your getData() method can determine what information it must retrieve by using the values in the PropertySpec objects. If the target is a VMware managed object, the value of the string is the name of the managed object type. For custom objects, see Resolving a Custom Target Object.

Handling Constraints

Within the QuerySpec object, the query constraints are represented as an object of type com.vmware.data.query.Constraint. A query can specify the following types of constraints, each of which is a subclass of the base Constraint class.

■

ObjectIdentityConstraint - Queries based on this constraint retrieve the properties of a known target object. For example, a query might retrieve the powered-on state of a given virtual machine. The object identifier can be a managed object type or any custom type that implements the IResourceReference interface. The identifier in this constraint includes the server GUID.

■

PropertyConstraint - Queries based on this constraint retrieve all objects with a given property value. For example, a query might retrieve all virtual machine objects with a power state of on. This constraint accepts the property name and comparator as strings, and the property value as an Object. This constraint is not bound to a specific server, and can be used to retrieve results from all vCenter Servers known to the client.

■

RelationalConstraint - Queries based on this constraint retrieve all objects that match the specified relationship with a given object. For example, a query might retrieve all virtual machine objects related to a given host object. The identifier in this constraint includes the server GUID.

■

CompositeConstraint - Composite queries allow the combination of multiple constraints using the and or or operator, passed as a string. The combined subconstraints in CompositeConstraint are contained in an array of Constraint objects.

When processing constraints, a best practice is to read the entire set of constraints and then determine the most efficient processing order. For example, you can process relational constraints first to retrieve a smaller number of objects that meet any included property constraints.

Specifying Result Sets

In the QuerySpec object, the expected formatting for the query results are included in an object of type com.vmware.data.query.ResultSpec. The properties of the ResultSpec object specify a maximum number of results for the query to return, provide an offset into the returned results, and set ordering for the returned results. Your getData() method must use the values of the ResultSpec properties to format the information it has retrieved.

Note

When a Data Service query requests a vSphere data object as a whole, rather than its properties, the response contains the data object in an unsupported format that VMware user interface elements understand. If your provider needs to use the Data Service to request a data object on behalf of a client, your provider should copy the data object from its query results into the result set that your provider is building in response to the client, without doing any kind of processing on the data object portion of the results.