The mediator class of your extension can use the DAM API to create requests for data.

Your mediator class creates data requests by dispatching one or more data request Frinje events specified in the API. The DAM responds to each data request by generating a data response event. You can annotate a method in your mediator class to handle the data response event and update the associated view class with the new information.

The DAM API contains several different kinds of data request events. Requests can retrieve a single property for a single object in the vSphere environment, or requests can retrieve multiple properties for an object by using a data model class to specify those properties. Requests can be targeted to a specific vSphere object, or you can specify a constraint to request data on all objects that match your defined criteria.

Your mediator requests data from DAM by dispatching data request events. To dispatch the events in the DAM API, your mediator class declaration must include an [Event] annotation for each type of event it dispatches, and the class must extend the base SDK class EventDispatcher.

For data requests that retrieve a single property, you must specify the name of the property to retrieve using a String type.

The DAM can return either a response with data about a single vSphere object, or a response with data about multiple vSphere objects. The DAM always returns one of these two responses, depending on the type of request. For requests sent by using a data model class, the DAM returns a data response with an object of the data model class type, or an array of such objects for multiple objects. For requests sent for a single property, the DAM returns the property value in a generic DataObject wrapper, or an array of generic DataObjects for multiple objects.

Your mediator class can listen for and handle data response events by annotating a class method with the [ResponseHandler] annotation. You specify the type of event for which the method listens in the [ResponseHandler] annotation.

The following table contains the types of data request events, the resulting data response events, and the associated result types included in the DAM API.

Data Request and Data Response Events

Request Event

Result Type

Description

DataByModelRequest

Instance of specified data model class

Retrieves multiple properties for a given vSphere or custom object, specified by a data model class.

PropertyRequest

Appropriate subtype of DataObject with the property value in the value field

Retrieves a single property for a given vSphere or custom object. The property name is specified using a String value.

DataByConstraintRequest

ArrayCollection of instances of specified data model class

Retrieves properties specified by data model for vSphere or custom objects that match the given constraint.

DataByQuerySpecRequest

ArrayCollection of ObjectDataObject (property-value map)

Retrieves data specified by query specification.

The following example mediator class that interfaces with the DAM by dispatching data request events and handling data response events. The class MyDataViewMediator extends the EventDispatcher base class, and the declaration has an [Event] annotation for each of the data request events that the class can dispatch.

Each of the methods that the class uses to handle data response events contains a [ResponseHandler] annotation with the method declaration.

In the example, the MyDataViewMediator class dispatches a DataByModelRequest event, a PropertyRequest event, and a DataByConstraintRequest event in the requestData method.

The DataByConstraintRequest specifies the constraint by using the createConstraintForRelationship method. In the example, the constraint specifies the virtual machine objects related to the host object specified by hostRef, which represent all virtual machines related to the given host.

[Event(name="{com.vmware.data.query.events.DataByModelRequest.REQUEST_ID}", 
       type="com.vmware.data.query.events.DataByModelRequest")]
[Event(name="{com.vmware.data.query.events.PropertyRequest.REQUEST_ID}", 
       type="com.vmware.data.query.events.PropertyRequest")]
[Event(name="{com.vmware.data.query.events.DataByConstraintRequest.REQUEST_ID}", 
       type="com.vmware.data.query.events.DataByConstraintRequest")]
 
public class MyDataViewMediator extends EventDispatcher {
 
    // Requests
    private function requestData(event:Event): void {
 
        // data-model request event
        var VmDataRequest:DataByModelRequest = DataByModelRequest.newInstance(vmRef, MyVmData);
        // vmRef is the target object reference; MyVmData is the data model class
        dispatchEvent(VmDataRequest);
 
        // single-property request event
        var VmGuestInfoRequest:PropertyRequest = PropertyRequest.newInstance(vmRef, "guest");
        // vmRef is the target object reference; single property specified as String
        dispatchEvent(VmGuestInfoRequest);
 
        // request by constraint
        var VmListRequest:DataByConstraintRequest = DataByConstraintRequest.newInstance(
                  QuerySpecUtil.createConstraintForRelationship(hostRef, "vm"), MyVmData);
        dispatchEvent(vmListRequest);
    }
 
    // Responses
    [ResponseHandler(name="{com.vmware.data.query.events.DataByModelRequest.RESPONSE_ID}")]
    public function onMyVmDataRetrieved(request:DataByModelRequest, result:MyVmData):void {
    // use MyVmData result
    }
    [ResponseHandler(name="{com.vmware.data.query.events.PropertyRequest.RESPONSE_ID}")]
    public function onVmGuestInfoRetrieved(request:PropertyRequest, result:StringDataObject):void {
    // use string result from result.value
    }
    [ResponseHandler(name="{com.vmware.data.query.events.DataByConstraintRequest.RESPONSE_ID}")]
    public function onVmListRetrieved(request:DataByConstraintRequest, result:ArrayCollection):void {
    // result is an ArrayCollection of MyVmData objects
    }
}

Data response events contain an additional error property that you can use to obtain more information about the results of a failed data request. The error property is available as an optional parameter to the response handler method.

[Event(name="{com.vmware.data.query.events.DataByConstraintRequest.REQUEST_ID}", 
       type="com.vmware.data.query.events.DataByConstraintRequest")]
 
public class MyDataViewMediator extends EventDispatcher {
    // Skip request method; show only response method.
    [ResponseHandler(name="{com.vmware.data.query.events.DataByConstraintRequest.RESPONSE_ID}")]
    public function onDataRetrieved(request:DataByConstraintRequest,
                                    result:ArrayCollection,
                                    error:Error):void {
      if (error != null) {
          _logger.debug(“onDataRetrieved error: “ + error.message);
          return;
      }
    // Valid result has been received.
    _view.datastoreItems = result;
  }
}

For more information, see the ActionScript API reference included with the vSphere Web Client SDK.