VMware vSphere SDKs and Tools 8.0

8.0 7.0 6.7 6.5

Processing Data Service Queries

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

Content feedback and comments