A Flex client application uses a client-side DataService component to receive data from, and send data to, the server-side Data Management Service. A DataService component can fill a client-side ArrayCollection object with data and manage synchronization of the ArrayCollection object data with the versions of data in other clients and on the server. You can create DataService components in MXML or ActionScript.

A DataService component requires a valid Data Management Service destination. You define destinations in the data-management-config.xml configuration file. For information about Data Management Service destinations, see Data Management Service configuration.

Creating a DataService component

A DataService component manages the interaction with a server-side Data Management Service destination. You can create a DataService component in MXML or ActionScript.

The following example shows MXML code for creating a DataService component. The DataService component destination property must reference a valid server-side Data Management Service destination.

<?xml version="1.0"?>
<!-- ds\datamanagement\DataServiceMXML.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:DataService id="ds" destination="contact"/>
</mx:Application>

The following example shows ActionScript code for creating the same DataService component:

<?xml version="1.0"?>
<!-- ds\datamanagement\DataServiceAS.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="initApp();">
    <mx:Script>
        <![CDATA[
            import mx.data.DataService;
            public var ds:DataService;
            
            public function initApp():void {
                ds = new DataService("contact");
            }
        ]]>
    </mx:Script>
</mx:Application>

When you create a DataService component in ActionScript, you must import the mx.data.DataService class and declare a variable of type DataService, for which you set the value to a new DataService object.

Getting a set of data from a destination

When you call a DataService component fill() method, you fill an ArrayCollection object with the data from a Data Management Service destination. You can create an ArrayCollection object in MXML or ActionScript. The ArrayCollection API provides a set of methods and properties for manipulating a set of data; for information, see the Adobe Flex 3 Developer Guide.

To release an ArrayCollection object that you filled, you call the DataService component releaseCollection() method. If you call the fill() method again on the same ArrayCollection object with the same parameters, it fetches a fresh copy of the data. If you call the fill() method again with different parameters, it releases the first fill and then fetches the new one.

The first parameter of a fill() method is the id value of the ArrayCollection to fill. The values of any additional parameters depend on the type of server-side destination that you call.

For example, when you call a destination that uses the Java adapter with a custom assembler, the arguments following the id of the ArrayCollection could be the arguments of a corresponding server-side method that is declared in the destination. The Data Management destination is responsible for interpreting the query parameters. The HibernateAssembler and SQLAssembler use a common pattern: the first parameter is the name of the query; the second parameter specifies an object that contains the values for the arguments to that query (if any) by using a name-value format, as the following example shows:

...

var myFirstName:String = "...";
myService.fill(myCollection, "getByFirstName", {firstName:myFirstName});
...

The value of the myFirstName variable is substituted into the query expecting a parameter named firstName.

For more information, see Data Management Service configuration.

Populating an ArrayCollection and data provider control with data

To populate a data provider control, such as a DataGrid control, with data, you can use data binding to bind a managed ArrayCollection object to the data provider control dataProvider property. When you set the associated DataService component autoCommit property to true, changes to data in the DataGrid are automatically sent to the Data Management Service destination.

The following example shows an ArrayCollection object that is bound to a DataGrid control dataProvider property:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns="*" backgroundColor="#FFFFFF">
    
    <mx:ArrayCollection id="products"/> 
    <mx:DataService id="ds" destination="inventory"/>
    <Product/>
    
    <mx:DataGrid dataProvider="{products}" editable="true" width="100%" height="100%">
        <mx:columns>
            <mx:DataGridColumn dataField="name" headerText="Name"/>
            <mx:DataGridColumn dataField="category" headerText="Category"/>
            <mx:DataGridColumn dataField="price" headerText="Price"/>
            <mx:DataGridColumn dataField="image" headerText="Image"/>
            <mx:DataGridColumn dataField="description" headerText="Description"/>
        </mx:columns>
    </mx:DataGrid>
    
    <mx:Button label="Get Data" click="ds.fill(products)"/> 
    
</mx:Application>

Sending changes from a managed ArrayCollection object

By default, the commit() method of a DataService component is automatically called when data changes in the ArrayCollection object that it manages. You can also call the commit() method manually and set a DataService component autoCommit property to false to allow only manual calls to the commit() method. It is important to set autoCommit to false when you are going to make more than one change in the same frame so that the DataService component can batch those changes and send them in one batch to the destination.

The following example shows a manual update operation on an item in an ArrayCollection object that a DataService component manages:

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="initApp();">
    <mx:Script>
        <![CDATA[
            import mx.data.DataService;
            import mx.collections.ArrayCollection;
            import samples.customer.Customer;
            ...
            public function initApp():void {
                var customers:ArrayCollection = new ArrayCollection(); 
                var customerService:DataService = new DataService("customers");
                customerService.autoCommit = false;
                var customer:Customer = customers.getItemAt(4);
                customer.city = "Oakland";
                customer.name = "CyberTech Enterprises";
                customerService.commit();
            }
                    ...
        ]]>
    </mx:Script>
</mx:Application>

The DataService component creates a single update message that includes the change to the customer.name and customer.city properties. This message is sent to the destination when the DataService component's commit() method is called.

The following example shows two manual update operations on an item in an ArrayCollection object that a DataService component manages:

...
var customer:Customer = customers.getItemAt(4); 
var oldName:String = customer.name;
customer.name = "CyberTech Enterprises"; 
customer.name = oldName;
customerService.commit();
...

If the update value is the same as the original value, there is no update operation issued. When there are multiple updates to the same item, only the latest one is issued. If it is same as original value, there is no update issued.

When the value of the customer.name property is changed to "CyberTech Enterprises", the DataService component creates a single update message. On the subsequent change back to the old name by using customer.name = oldName, the original update message for the customer name is removed. The result is that nothing is sent when the commit() method is called.

The following example shows the addition and removal of a customer to an ArrayCollection object that the DataService component manages:

<?xml version="1.0"?>
<!-- fds\datamanagement\AddRemoveItem.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="initApp();">
<mx:Script>
<![CDATA[
import mx.collections.ArrayCollection;
import mx.data.DataService;
import samples.customer.Customer; 
public function initApp():void {
var customers:ArrayCollection = new ArrayCollection(); 
var customerService:DataService = new DataService("customers");
customerService.autoCommit = false; 
customers.addItemAt(new Customer(), 4);
// Remove the previously added customer.
customers.removeItemAt(4); 
customerService.commit();
}
]]>
</mx:Script>
</mx:Application>

The DataService component attempts to log two updates that cancel out each other. When the addItemAt() method is called, the DataService component creates a create message for the customers destination. On the subsequent call to removeItemAt(4), the previous create message is removed. Nothing is sent when the commit() method is called.

Working with single data items

The mx.data.DataService class has several methods for working with individual data items. The following table describes these methods:

The following example shows a method that gets a specific data item when a DataGrid control changes. You get the item from the ResultEvent.result event. The identity value sent to the destination is companyId, which is set to the companyId of the currently selected item in the DataGrid control. The destination retrieves items based on their identity, which is specified in the destination definition in the data-management-config.xml configuration file.

<mx:Script>
    <![CDATA[
...
        private function companyChange() {
            dsCompany.getItem({companyId: dg.selectedItem.companyId});        
        }
    ]]>
</mx:Script>
...

Connecting to and disconnecting from a destination

A DataService component starts out disconnected from its server-side destination. The first time you perform an operation, the DataService component tries to connect to the destination. If the operation succeeds, a result event is sent to the DataService component. If the operation fails, a fault event is sent. You can call the DataService.disconnect() method to force a connected client to disconnect; in this case, the DataService component keeps a copy of its managed data and automatically resubscribes to pick up changes when you reconnect. You can also bind to the DataService.connected property, which indicates the current connected state of the DataService component.

You can also call DataService.release() method to release all managed objects fetched by a DataService component.