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 principle 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 automatically handle data changes. You can include a data update specification with your data request, so that DAM can automatically assign updated data to GUI elements in your view class.
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.
|
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 wants to retrieve using DAM. The mediator references the data model class when dispatching data request events or receiving data response events. If you want to query for a single property of a given vSphere object, you do not need to create a data model class, and may 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 have changed. 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.
|
Your extension describes the information that you want to request using DAM by creating a data model class. 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 want 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.
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 the
type tag in the annotation is specified, the data model class can only be used to retrieve properties for objects of the specified type. You can create a data model class that can be used 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.
Within the data model class, you must specify a class property for each data property you want 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.
Only properties that have the [Model] annotation are retrieved through DAM when the data model class is used in a data request. Properties without the annotation are ignored.
In Example: Data Model Class, the class
MyVmData includes two annotated properties:
myVmName and
myVmPowerState. Each property includes an annotation that specifies the DAM data property associated with the class property.
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 specify that the property you want DAM to retrieve is for a related object by using the
relation tag in the
[Model] annotation for the class property.
Example: Data Model Class with a Related Object Property Annotation shows a data model class with a property annotated for DAM to retrieve data from a related object. In the example, the property
myVmHostName is annotated for DAM to retrieve the
name property for the Host object related to the target Virtual Machine object.
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.
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 retrieving a related property of this type, the associated class property in the data model class must be of type
Array or
ArrayCollection.
The annotated properties in a data model class can themselves be 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 themselves 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.
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.
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. You must use this syntax for any custom object type that you include inside a data model class.
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.
There are several different kinds of data request events in the DAM API. 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: Example Mediator Class Using DAM Interface. In the class methods, you use the
dispatchEvent() method to dispatch each data request event.
DAM sends two kinds of data responses: a response with data about a single vSphere object, and a response with data about multiple vSphere objects. DAM always returns one of these two responses, depending on the type of request. For requests sent using a data model class, DAM will return 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, DAM will return the property value in a generic
DataObject wrapper, or an array of generic
DataObjects for multiple objects.
Data Request and Data Response Events shows the different kinds of data request events, the resulting data response events, and the associated result types included in the DAM API.
Example: Example Mediator Class Using DAM Interface shows an example mediator class that interfaces with 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 the each of the data request events that the class can dispatch.
In the example, the MyDataViewMediator class dispatches three data request events in the
requestData method: a
DataByModelRequest, a
PropertyRequest, and a
DataByConstraintRequest.
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.
Data response events contain several additional properties which you can use to obtain more information about the results of the data request. These properties include the total number of results returned by the request, a time stamp, any errors returned, and the query specification used to retrieve the data from the Data Service. See the ActionScript API reference included with the vSphere Web Client SDK for more information.
You can use 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 automatically 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: Mediator Class Using DAM Binding Specification for Data Refresh.
|
■
|
implicit – The data will be refreshed if the user performs an operation on the relevant object, or the user clicks on the vSphere Web Client global Refresh button.
|
|
■
|
explicit – The data will be refreshed 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: Mediator Class Using DAM Binding Specification for Data Refresh 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.
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. Due to the data update specification,
onDataRetrieved is called automatically by DAM when the data changes.