Package	mx.data
Class	public class DataService
Inheritance	DataService DataManager Object
Subclasses	DataService

A DataService is constructed specifying the desired destination. These destinations are generally configured from the services-config.xml file.

There are two different sets of methods that retrieve data from the specified remote destination. The first are for collection managed objects. The second are for Single Managed Objects (SMOs).

For the collection managed objects the DataService.fill() method is used. This method populates an ArrayCollection with objects that this services will manage.

To get SMOs the DataService.getItem() and DataService.createItem() methods are used.

When a previously filled ArrayCollection is no longer needed, or the items within that collection should no longer receive or create updates, the DataService.releaseCollection() method is called.

When an item previously retrieved using DataService.getItem() or DataService.createItem() is no longer needed or should not receive or create updates, the DataService.releaseItem() method should be called. The DataService.createItem() and DataService.getItem() methods return an ItemReference. This object can be used to release a specific instance of a single managed object. Unlike the DataService.releaseItem() method, calling ItemReference.releaseItem() will release a specific instance of an SMO. DataService.releaseItem() will release the first SMO that it finds with a matching identity to that specified. This is normally okay as long as the number of calls to DataService.getItem() and DataService.createItem() matches the number of calls to DataService.releaseItem().

A connection to the remote destination is created automatically the first time any methods that require a connection are called. For example, calling the DataService.fill() method or DataService.commit() operation when there are uncommitted updates will attempt to establish a connection to the remote destination. To force a DataService to become disconnected use the DataService.disconnect() method. This method can be used to clean up remote destination resources when no longer needed. Because other services may be using the same physical connection calling DataService.disconnect() may terminate the connection.

The bindable property connected indicates the current state of the associated DataService connection.

If a remote destination has declared any security constraints for an operation, credentials must be provided. Credentials are set via the DataService.setCredentials() call. This turns into a login command at the remote destination. To change credentials or invalidate the current session DataService.logout() can be called. When called the DataService.logout() method will release all local managed data. It is equivalent to calling DataService.release().

Each DataService has a dataStore property that returns an object of type mx.data.DataStore. This object stores the uncommitted changes for one or more DataService objects. By default, a DataService shares the same DataStore with other data services if they have managed association properties and share the same set of channels. When sharing DataStores, a commit() method call on one DataService commits changes for all DataService using the shared data store. This preserves the order of operations in the event there are dependencies between the changes in the associated DataService objects.

DataService and DataStore dispatch result and fault events for all operations that require a remote call.

NOTE: if you create two DataService instances that point to the same destination both of those instances will share the same collection of managed objects, and will dispatch the same set of events. For example, if you add an event listener to one DataService instance for a destination, and you use a different instance to initiate an operation, the first DataService instance will still receive those events. Each operation you initiate on a DataService returns an AsyncToken. You can add an event responder to that token to receive a result event specific for that operation. This approach often produces cleaner code than adding a result or fault event handler globally for a given destination.

Data binding can be used on properties of any managed instances for a DataService. DataService will also dispatch a "message" event when a remote operation occurs for any managed object. For example when a locally managed item is updated by a remote process a message will be pushed to all DataService instances that are still managing that item. This message is dispatched as a MessageEvent.MESSAGE event.

When a conflict is detected either at the remote destination in response to a change committed by the DataService, or due to a pushed change which conflicts with a local uncommitted change, a conflict event is dispatched. These events can be handled by listening for the DataConflictEvent.CONFLICT. Data binding can be employed to update UI controls by binding to the DataService.conflicts.resolved property.

DataService supports the following data synchronization configuration modes:

• autoCommit - when true each change is immediately sent to the remote destination once detected. When this is false, an explicit call to commit must be made. The bindable DataService.commitRequiredproperty can be used to determine whether or not there are uncommitted changes.
• autoSyncEnabled - This affects any fill, getItem or createItem calls made and determines whether managed instances listen for changes made to these objects by other clients or using the server push api at the remote destination.
• autoMerge property controls whether or not changes received from a remote destination are applied immediately or queued up until a call to DataService.merge() is made.

The DataService.revertChanges() method is used to revert changes for a specific item or for all items. When an error occurs for a remote destination operation, the committed changes are put back into the uncommitted queue so the data stays in sync with the remote destination data. If the changes are in error, typically a call to DataService.revertChanges() is made to undo the changes as part of a fault handler.

The mx.data.mxml.DataService class is an MXML-specific subclass of mx.data.DataService that allows binding to the properties of a DataService.

Show MXML Syntax

Hide MXML Syntax

  <mx:DataService
   Properties
   autoCommit="true"
   autoMerge="true"
   autoSaveCache="false"
   autoSyncEnabled="true"
   conflictDetector="No default."
   dataStore="No default."
   destination="No default."
   pageSize="No default."
   id="No default."
 
   Events
   conflict="No default."
   fault="No default."
   message="No default."
   propertyChange="No default."
   result="No default."
 />
 

See also