Using the Data Access Manager Library

When you create your data view Flex classes using the MVC architecture pattern and Frinje framework, you can use the Data Access Manager library included in the vSphere Web Client SDK. The DAM library is a Flex library that communicates with the vSphere Web Client Data Service. Using DAM and the Data Service is the principal way to retrieve information about objects in the vSphere environment.

In general, the mediator class in a data view extension uses the DAM library to request data from the vSphere environment. The mediator class then updates the extension’s view class to reflect the new information. The DAM also includes a data refresh mechanism that you can use to handle data changes implicitly. You can include a data update specification with your data request, so that DAM can assign updated data to GUI elements in your view class without the need for extra code to do so.

Data Access Manager Workflow

The DAM API consists of Frinje events, such as requests for data or responses to data requests. To use DAM, your Flex classes must dispatch the request events and listen for the associated responses. You indicate which events your classes can receive by using Frinje metadata annotations.

To use the Data Access Manager library, you must build your extension Flex classes as follows.

1

Create an annotated data model class in your plug-in module. The data model class must extend the DataObject base class. The data model class describes the information that the extension’s mediator class must retrieve using DAM. The mediator references the data model class when dispatching data request events or receiving data response events. To query for a single property of a given vSphere object, you do not need to create a data model class, and can proceed to Step 2.

2

In your extension’s mediator class, create and dispatch one or more data request events. Data request events include both a reference to the target vSphere object, and a data model class as described in Step 1. Optionally, the data request can also include a data update specification that will cause DAM to send notifications whenever the values of the requested properties change. For data requests events that retrieve a single property, you specify the property name using a string value and do not need to include a data model class.

3	The DAM sends a data response event, which contains a DataObject with the values of the requested properties, as specified in the data model class in Step 1. You must annotate a method in your extension’s mediator class to receive the data response event.

4	In your data response event handler method, update your extension’s user interface elements using the data in the data response event.

Creating the Data Model Class

You create a data model class in your extension to describe the information needed from the DAM. When you create a data model class, you specify the type of vSphere or custom object to which the request pertains, and the specific properties of that object that you need to retrieve. For example, you can create a data model class to request information on a Virtual Machine object, and include the name and powerState properties in the data request.

Example: Data Model Class shows an example data model class.

Example: Data Model Class

package com.myExtension.model {

import com.vmware.core.model.DataObject

 

// data model class annotation and declaration

[Model(type="VirtualMachine")]

public class MyVmData extends DataObject {

 

//properties to retrieve, specified by annotation

[Model(property="name")]

public var myVmName:String;

 

[Model(property="runtime.powerState")]

public var myVmPowerState:String;

}

}

 

Class Declaration

The data model class must extend the DataObject class and use the [Model] annotation tag. Typically, you create the data model class as a separate class or package in your plug-in module. This package must import the package com.vmware.core.model.DataObject from the vSphere Web Client SDK.

The type tag in the [Model] annotation is optional. If you specify the type tag in the annotation, the data model class can retrieve properties only for objects of the specified type. You can create a data model class to request common properties for multiple object types, or you can use the type tag in the [Model] annotation to make the data model class specific to a particular vSphere object type.

In Example: Data Model Class, the class MyVmData has a [Model] annotation and extends DataObject. In the example, the object type VirtualMachine is specified, indicating that the data model retrieves information on Virtual Machine objects.

Declaring the Properties to Retrieve

In the data model class, you must specify a class property for each data property to retrieve through DAM. When you declare each property, you must include a [Model] annotation with a property tag. The annotation associates the class property with the associated data property for the vSphere object. When you use the data model class in a data request, DAM retrieves the data specified in the annotation from the vSphere environment, and assigns the value to the associated class property.

When you use the data model class in a data request, the DAM returns only properties that have the [Model] annotation. Properties without the annotation are ignored.

In Example: Data Model Class, the class MyVmData includes the myVmName and myVmPowerState annotated properties. Each property includes an annotation that specifies the DAM data property associated with the class property.

Retrieving Properties for Related Objects

You can specify and annotate class properties to retrieve data on related objects, such as the host associated with a given virtual machine object. You use the relation tag in the [Model] annotation for the class property to specify that the property requested from the DAM is for a related object.

Example: Data Model Class with a Related Object Property Annotation shows a data model class with a property annotated for the DAM to retrieve data from a related object. In the example, the property myVmHostName is annotated for the DAM to retrieve the name property for the host object related to the target virtual machine object.

Example: Data Model Class with a Related Object Property Annotation

[Model(type="VirtualMachine")]

public class MyVmData extends DataObject {

[Model(relation="runtime.host", property="name")]

public var myVmHostName:String;

}

 

You can retrieve properties over multihop relationships by specifying each hop separated by a comma. Example: Data Model Class with a Multi-hop Relationship Annotation shows a property annotated to retrieve data over a multi-hop relationship. In the example, the myDatacenterName property is annotated to retrieve the name property for a Datacenter object associated with the Host for a given Virtual Machine.

Example: Data Model Class with a Multi-hop Relationship Annotation

[Model(type="VirtualMachine")]

public class MyVmData extends DataObject{

[Model(relation="runtime.host,cluster", property="name")]

public var myDatacenterName:String;

}

 

You can also retrieve properties for an object relationship with multiple cardinality, where the relationship is one-to-many. For example, one such relationship is that of a virtual machine object to multiple related network objects. When you retrieve a related property of this type, the associated class property in the data model class must be of type Array or ArrayCollection.

Nested Data Models

The annotated properties in a data model class can be single properties, or they can be nested data model classes. To specify a class property as a nested data model class, as opposed to a single property, you omit the property tag from the [Model] annotation when declaring the class property.

Omitting the property tag implicitly declares that the class member variable is a data model of the same object type as the parent data model. If the relation tag is specified, however, the class property is assumed to be a data model for the object type specified in the relation tag.

Example: Nested Data Model Classes shows a data model class with two class properties that are nested data models. The first property, myVmHardwareData, is another data model for Virtual Machine objects, the same as the parent data model. The second property, myHostDetails, is a data model for Host objects.

Example: Nested Data Model Classes

[Model(type="VirtualMachine")]

public class MyVmData extends DataObject{

[Model]

public var myVmHardwareData:VmHardwareData; // VmHardwareData is a VM data model

[Model(relation="runtime.host")]

public var myHostDetails:HostData; // HostData is a Host data model

}

 

You can use a nested data model to create an array of data model objects. Example: Nested Data Model Used to Create Array shows a data model class that uses a nested data model to create an array of objects based on the Host data model.

Example: Nested Data Model Used to Create Array

[Model(relation="runtime.host")]

public var HostList:Array; // array of Host objects using the HostData model

 

Important If the related object for which you want to retrieve data is a user-defined custom object, you must use a different syntax in your [Model(relation="..."] annotation. Your [Model] annotation must explicitly specify both the custom object type, and the nested data model that you use to define that type. Example: Related Data Model for Custom Object Type shows a data model class that uses a nested data model for a user-defined custom Chassis object.

Example: Related Data Model for Custom Object Type

[Model(relation="Chassis as comexample:Chassis", nestedModel="com.example.ChassisModelData"]

public var myChassisDetails:ChassisModelData; // Chassis object using the ChassisModelData model

 

In the example, the [Model(relation="..."] annotation specifies the exact object type for Chassis as comexample:Chassis. The annotation also includes an explicit nestedModel attribute that specifies the fully-qualified class name for the Chassis data model. Use this syntax for any custom object type that you include in a data model class.

Sending Data Requests and Handling Data Responses

Your extension’s mediator class 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. 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.

Data Request Events

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. See Example 5-16, on page 54. In the class methods, you use the dispatchEvent() method to dispatch each data request event.

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

Data Response Events

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 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. See Example 5-16, on page 54.

Request-to-Response Mapping

Data Request and Data Response Events 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	Get 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	Get 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	Get properties specified by data model for vSphere or custom objects that match the given constraint.
DataByQuerySpecRequest	ArrayCollection of ObjectDataObject (property-value map)	Get data specified by query specification.

Examples of Data Request and Data Response Events

Example 5-16, on page 54, shows an 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.

Example: Example Mediator Class Using DAM Interface

[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

}

}

 

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

Error Checking and Troubleshooting Your Data Requests

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. Example 5-17, on page 55, shows a code excerpt that demonstrates the use of this property.

Example: Example Mediator Class Using error Property

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

Data Refresh and Data Update Specifications

You can use the DAM’s data refresh mechanism to subscribe your Flex component to receive updated data from the vSphere environment. You can bind the requested data directly to elements in the view class, causing those elements to be updated whenever the requested data changes. To perform this binding, you must include a data update specification when you dispatch your data request event.

A data update specification is included in the SDK base class DataRequestInfo. You must create an instance of DataRequestInfo and set the DataUpdateSpec property, and then pass the DataRequestInfo object when you create your data request. See Example 5-18, on page 56.

The DAM data refresh mechanism has different modes of operation. You choose the mode of operation when you construct the DataUpdateSpec object in your DataRequestInfo object.

■	implicit. The DAM refreshes the data when the user performs an operation on the relevant object, or when the user clicks on the vSphere Web Client global Refresh button.

■	explicit. The DAM refreshes the data only if explicitly requested, such as when the user clicks the vSphere Web Client global Refresh button.

To create an implicit binding, you use the newImplicitInstance() method to construct the DataUpdateSpec object. To create an explicit binding, you use the newExplicitInstance() method.

Example 5-18, on page 56, shows an example mediator class that includes the DataRequestInfo and DataUpdateSpec objects to create an automatic binding in the data request. In the example, the DataUpdateSpec is constructed using the newImplicitInstance() method, resulting in an implicit binding.

Example: Mediator Class Using DAM Binding Specification for Data Refresh

import com.vmware.data.query.events.DataByModelRequest;

import com.vmware.data.query.DataUpdateSpec;

import com.vmware.data.query.events.DataRequestInfo;

 

[Event(name="{com.vmware.data.query.events.DataByModelRequest.REQUEST_ID}", type="com.vmware.data.query.events.DataByModelRequest")]

 

public class MyVmViewMediator extends EventDispatcher {

private function onStart():void {

var requestInfo:DataRequestInfo =

new DataRequestinfo(DataUpdateSpec.newImplicitInstance());

// create a DataRequestInfo with an implicit-mode DataUpdateSpec

 

var myRequest:DataByModelRequest = DataByModelRequest.newInstance(

vmRef,

MyVmData, // data model

requestInfo); // include the DataRequestInfo object when constructing the request

dispatchEvent(myRequest);

}

 

[ResponseHandler(name="{com.vmware.data.query.events.DataByModelRequest.RESPONSE_ID}")]

public function onDataRetrieved(request:DataByModelRequest, result:MyVmData):void {

_view.vmData = result;

}

}

 

In the example, the function onStart dispatches the initial DataByModelRequest. The initial request includes a DataRequestInfo object with an implicit DataUpdateSpec. The function onDataRetrieved is annotated to handle the response, and updates a UI control with the returned data. Because of the data update specification, the DAM calls onDataRetrieved when the data changes.