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 theIResourceReferenceinterface. 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 anObject. 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 theandororoperator, passed as a string. The combined subconstraints inCompositeConstraintare contained in an array ofConstraintobjects.
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.