Adobe® Flex® 4 Language Reference
Show Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
mx.data 
DataManager 
Packagemx.data
Classpublic class DataManager
InheritanceDataManager Inheritance Object
Implements IEventDispatcher
Subclasses DataService, RPCDataManager

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

The DataManager class provides synchronization functionality with objects on the server for all instances of a specific data type. The DataManager provides synchronization, replication, conflict detection, change tracking and occasionally connected services.

The DataManager is an abstract class. Typically you construct either a DataService that extends the DataManager or define one or more RPCDataManagers in conjunction with an RPC service such as an HTTPService, WebService or RemoteObject.

To get Single Managed Objects the DataManager.getItem() and DataManager.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 DataManager.releaseCollection() method is called.

When an item previously retrieved using DataManager.getItem() or DataManager.createItem() is no longer needed or should not receive or create updates, the DataManager.releaseItem() method should be called. The DataManager.createItem() and DataManager.getItem() methods return an ItemReference. This object can be used to release a specific instance of a single managed object. Unlike the DataManager.releaseItem() method, calling ItemReference.releaseItem() will release a specific instance of an SMO. DataManager.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 DataManager.getItem() and DataManager.createItem() matches the number of calls to DataManager.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 DataManager.getItem() method or DataManager.commit() operation when there are uncommitted updates will attempt to establish a connection to the remote destination. To force a DataManager to become disconnected use the DataManager.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 DataManager.disconnect() may terminate the connection.

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

Each DataManager has a dataStore property that returns an object of type mx.data.DataStore. This object stores the uncommitted changes for one or more DataManager objects. By default, a DataManager shares the same DataManager 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 DataManager commits changes for all DataManager using the shared data store. This preserves the order of operations in the event there are dependencies between the changes in the associated DataManager objects.

DataManager and DataStore dispatch result and fault events for all operations that require a remote call. NOTE: if you create two DataManager 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 DataManager instance for a destination, and you use a different instance to initiate an operation, the first DataManager instance will still receive those events. Each operation you initiate on a DataManager 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 DataManager. DataManager 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 DataManager 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 DataManager, 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 DataManager.conflicts.resolved property.

DataManager 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 DataManager.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 DataManager.merge() is made.

The DataManager.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 DataManager.revertChanges() is made to undo the changes as part of a fault handler.

See also



Public Properties
 PropertyDefined By
  adapter : DataServiceAdapter = null
An instance of a class which controls interaction with the server.
DataManager
  autoCommit : Boolean
Indicates if changes to the local cache are automatically committed.
DataManager
  autoConnect : Boolean
Indicates if this service should attempt to connect for any operations that require a connection.
DataManager
  autoMerge : Boolean
If set to false, when changes are pushed from the remote destination to the client they are not immediately applied.
DataManager
  autoSaveCache : Boolean
The local cache of data and changes can be stored to disk.
DataManager
  autoSyncEnabled : Boolean
When true, fill(), createItem() and getItem() requests return items which listen for updates made to these items from the remote destination.
DataManager
  cacheID : String
Provides access to the cache identifier for this service.
DataManager
  commitRequired : Boolean
[read-only] Indicates if there are changes that have not been committed and the commit() method should be called.
DataManager
  conflictDetector : ConflictDetector
Provides access to the current implementation being used to detect conflicts for remote operations pushed to this DataService.
DataManager
  conflicts : Conflicts
[read-only] Contains a Conflicts object, an ArrayList of Conflict instances.
DataManager
  connected : Boolean
[read-only] Indicates if the DataService is connected to the remote destination.
DataManager
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  dataStore : DataStore
Contains an object of type mx.data.DataStore.
DataManager
  deleteItemOnRemoveFromFill : Boolean
By default when you call the removeItemAt() method on a managed filled collection, it issues a delete item call to the server to physically remove the item.
DataManager
  hierarchicalEventsDefault : Boolean
Associations optionally list for property change events on properties of the associated instances.
DataManager
  indexReferences : Boolean
To tune the speed of your application, set this property to false if you have a small number of fills or references to items managed by this data service from association properties of other items.
DataManager
  isInitialized : Boolean
[read-only] Indicates if the metadata associated with this service is initialized.
DataManager
  manualSync : ManualSyncConfiguration
The manualSync property provides access to the ManualSyncConfiguration instance for each data service.
DataManager
  maxFrequency : uint
Determines the maximum number of messages per second the DataManager wants to receive.
DataManager
  mergeRequired : Boolean
[read-only] Indicates if there are any pending changes that must be merged.
DataManager
  pageSize : int
Provides access to the current page size setting for all collections.
DataManager
  pagingEnabled : Boolean
[read-only] Indicates if the remote destination is configured to allow paged requests.
DataManager
  priority : int
The default message priority for the messages sent by the data service.
DataManager
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  requestTimeout : int
Provides access to the request timeout in seconds for an operation.
DataManager
  resetCollectionOnFill : Boolean
When true, after the fill operation completes, a RESET event is sent.
DataManager
  resubscribeAttempts : int
Controls the number of times a disconnected data service will attempt to resubscribe.
DataManager
  resubscribeInterval : int
Controls the delay, in milliseconds, between resubscribe attempts.
DataManager
  subscribed : Boolean
[read-only] Indicates if the DataService is subscribed to the remote destination.
DataManager
  throwItemPendingErrors : Boolean
Set this property to false if you want to suppress the throwing of item pending errors when lazily fetched or unpaged data is accessed.
DataManager
Public Methods
 MethodDefined By
  
Constructs an instance of the DataService with the specified destination.
DataManager
  
Clears any data stored to disk with a previous call to saveCache() or when autoSaveCache was set to true
DataManager
  
Clears the data specified by the passed descriptor from the local store.
DataManager
  
commit(itemsOrCollections:Array = null, cascadeCommit:Boolean = false):mx.rpc:AsyncToken
Commits pending changes for all collections currently managed by the DataStore associated with this data service.
DataManager
  
Forces a connection attempt by this service to the remote destination.
DataManager
  
Calls a count method on the remote destination.
DataManager
  
Requests that the specified item be created in the remote store.
DataManager
  
Requests that the specified item be deleted from the remote store.
DataManager
  
Disconnects the DataService's network connection.
DataManager
  
executeQuery(queryName:String, propertySpecifier:PropertySpecifier, ... args):mx.rpc:AsyncToken
Executes a query with the provided name and arguments.
DataManager
  
Fills the specified ListCollectionView based on the associated fill method of the destination.
DataManager
  
fillSubset(value:ListCollectionView, ps:PropertySpecifier, ... args):mx.rpc:AsyncToken
Fills the specified ListCollectionView based on the associated fill method of the destination.
DataManager
  
findItem(queryName:String, propertySpecifier:PropertySpecifier, ... args):mx.rpc:AsyncToken
Executes a query which returns a single item.
DataManager
  
Returns an ArrayCollection or a single managed object (SMO) from the the local store.
DataManager
  
This method will fill the specified ListCollectionView with CacheDataDescriptor(s).
DataManager
  
This method will fill the specified ListCollectionView with all cache identifiers previously used in the application.
DataManager
  
getItem(identity:Object, defaultValue:Object = null):ItemReference
Makes an asynchronous request for an item matching the specified identity.
DataManager
  
Looks up the supplied item with the given identity.
DataManager
  
Returns page information for the specified collection.
DataManager
  
Returns the pending operation in the message cache for the specified item.
DataManager
 Inherited
Indicates whether an object has a specified property defined.
Object
  
Forces initialization of the DataStore.
DataManager
  
Returns true if the passed collection is managed by this service.
DataManager
  
Returns true if the passed collection is using paging features.
DataManager
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
  
isRangeResident(view:ListCollectionView, startIndex:int, numberOfItems:int):Boolean
Returns true if the supplied range of items is all paged in.
DataManager
  
Merges any pending updates into the managed set of objects.
DataManager
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
  
Refreshes all data managed by this data service.
DataManager
  
Refreshes an array collection previously filled with the fill method or managed as a managed association.
DataManager
  
release(clear:Boolean = true, copyStillManagedItems:Boolean = true):void
Releases all managed collections and items for the DataService.
DataManager
  
releaseCollection(view:ListCollectionView, clear:Boolean = false, copyStillManagedItems:Boolean = true):void
Releases any item within the specified collection from management by this service.
DataManager
  
releaseItem(item:IManaged, copyStillManagedItems:Boolean = true, enableStillManagedCheck:Boolean = true):IManaged
Releases the specified item from management by this service.
DataManager
  
releaseItemsFromCollection(collection:ListCollectionView, startIndex:int, numberOfItems:int):int
Releases a range of items in the collection.
DataManager
  
Releases the value for a single-valued association.
DataManager
  
Reverts any uncommitted changes to the specified item.
DataManager
  
Reverts the changes for any item contained in the specified collection which should be managed by this data service.
DataManager
  
This method will save the current state of the DataService cache.
DataManager
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
  
updateItem(item:Object, origItem:Object = null, changes:Array = null):mx.rpc:AsyncToken
Triggers an update for the specified item.
DataManager
 Inherited
Returns the primitive value of the specified object.
Object
Protected Methods
 MethodDefined By
  
Queues a fault if this data manager has not yet been initialized.
DataManager
Events
 Event Summary Defined By
  The DataConflictEvent.CONFLICT event is dispatched when a conflict is detected between either pending local changes and changes submitted by another client, or when changes submitted by this client are conflicting with those in the remote destination.DataManager
  The DataServiceFaultEvent.FAULT event is dispatched when a service call fails due to an error.DataManager
  The MessageEvent.MESSAGE event is dispatched when the remote destination pushes a notification of a data operation.DataManager
  The PropertyChangeEvent.PROPERTY_CHANGE event is dispatched when a property of this service changes.DataManager
  The ResultEvent.RESULT event is dispatched when a service call successfully returns.DataManager
Property Detail

adapter

property
public var adapter:DataServiceAdapter = null

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

An instance of a class which controls interaction with the server.

autoCommit

property 
autoCommit:Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Indicates if changes to the local cache are automatically committed. Committed changes are sent to the remote service immediately.

The default value is true.



Implementation
    public function get autoCommit():Boolean
    public function set autoCommit(value:Boolean):void

autoConnect

property 
autoConnect:Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Indicates if this service should attempt to connect for any operations that require a connection. Operations like fill(), getItem(), and count() attempt to connect if the service is disconnected and autoConnect is set to true. Use this property to control occasionally connected application behavior.

The default value is true.



Implementation
    public function get autoConnect():Boolean
    public function set autoConnect(value:Boolean):void

autoMerge

property 
autoMerge:Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

If set to false, when changes are pushed from the remote destination to the client they are not immediately applied. Instead, the mergeRequired property is set to true.

An event handler can be registered to listen for change events on this property to be notified of when a merge needs to be applied.

To merge changes, call the merge() method and all changes are applied.

Uncommited changes can not be committed when there are any changes that need to be merged.

If paging is enabled all requests for non local items are cached until merge() is called. Once merge() is called, the cached requests are processed.

The default value is true.



Implementation
    public function get autoMerge():Boolean
    public function set autoMerge(value:Boolean):void

autoSaveCache

property 
autoSaveCache:Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

The local cache of data and changes can be stored to disk. When autoSaveCache is true each time a change is made or a remote request is returned, that data will be saved to disk. If there is a problem saving the data either because the disk is full or write permissions have been denied a FaultEvent will be dispatched or a Fault will be thrown.

Setting this value to false (the default) will not save any data or changes to disk. To force the current data and changes to be saved to disk use the saveCache method.

The default value is false.



Implementation
    public function get autoSaveCache():Boolean
    public function set autoSaveCache(value:Boolean):void

See also

autoSyncEnabled

property 
autoSyncEnabled:Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

When true, fill(), createItem() and getItem() requests return items which listen for updates made to these items from the remote destination. When a change is made to this property value, it only affects future calls to these methods, not existing collections or items.

Also note that when a mix of collections retrieved with autoSyncEnabled and those that were filled without autoSyncEnabled, any items appearing in both collections still receive update events.

The default value is true.



Implementation
    public function get autoSyncEnabled():Boolean
    public function set autoSyncEnabled(value:Boolean):void

cacheID

property 
cacheID:String

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Provides access to the cache identifier for this service. A cache identifier must be set prior to performing any operations that require interaction with data stored locally on disk. If a cache identifier is not set, all cache methods and properties are considered inconsistent and a DataServiceError is thrown during any operation that requires data from the local disk. This property provides a unique "session" identifier for data stored locally. A developer must set this property to a unique value for the application.

A value of null or empty string is considered unset. Requests for data by methods like fill() and getItem() will attempt to access the local data on disk first if the cacheID has been set. If the cacheID is not set, no attempt to access any local data will be made.



Implementation
    public function get cacheID():String
    public function set cacheID(value:String):void

commitRequired

property 
commitRequired:Boolean  [read-only]

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Indicates if there are changes that have not been committed and the commit() method should be called. When this property changes, an event is dispatched. This property can be used within an application to provide visual feedback.

This property can be used as the source for data binding. When this property is modified, it dispatches the propertyChange event.



Implementation
    public function get commitRequired():Boolean

conflictDetector

property 
conflictDetector:ConflictDetector

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Provides access to the current implementation being used to detect conflicts for remote operations pushed to this DataService.



Implementation
    public function get conflictDetector():ConflictDetector
    public function set conflictDetector(value:ConflictDetector):void

conflicts

property 
conflicts:Conflicts  [read-only]

Contains a Conflicts object, an ArrayList of Conflict instances.

Conflicts must be resolved before commit() can be called. Conflicts can be resolved by going through the conflicts, resolving each conflict individually or by calling the acceptAllClient() method or acceptAllServer() method on this property.

This property can be used as the source for data binding. When this property is modified, it dispatches the propertyChange event.



Implementation
    public function get conflicts():Conflicts

connected

property 
connected:Boolean  [read-only]

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Indicates if the DataService is connected to the remote destination.

This property can be used as the source for data binding. When this property is modified, it dispatches the propertyChange event.



Implementation
    public function get connected():Boolean

dataStore

property 
dataStore:DataStore

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Contains an object of type mx.data.DataStore. The DataStore manages the set of incoming and outgoing changes for one or more DataServices, which may have references between them. When you commit on a DataStore, all of the pending changes of each DataService using that DataStore are committed.

By default, a DataService shares the same DataStore with other DataServices if they have managed association properties and share the same set of channels. If you are sharing DataStores, a commit call on one DataService commits changes for all DataServices using that data store. This preserves the order of operations in case there are dependencies between the changes in your uncommitted batches.

This property can be used as the source for data binding. When this property is modified, it dispatches the propertyChange event.



Implementation
    public function get dataStore():DataStore
    public function set dataStore(value:DataStore):void

deleteItemOnRemoveFromFill

property 
deleteItemOnRemoveFromFill:Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

By default when you call the removeItemAt() method on a managed filled collection, it issues a delete item call to the server to physically remove the item. This allows you to use code which uses a managed collection and an unmanaged collection in the same way. Other times though, you might want to remove the item from the collection on the client without deleting it from the server. In that case, set this flag to false before you call the removeItemAt() method.

Note that this does not affect collections which are associations - just those which were used with the fill() method.

The default value is true.



Implementation
    public function get deleteItemOnRemoveFromFill():Boolean
    public function set deleteItemOnRemoveFromFill(value:Boolean):void

hierarchicalEventsDefault

property 
hierarchicalEventsDefault:Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Associations optionally list for property change events on properties of the associated instances. You can set this on the association with the hierarchical-events attribute. If you do not set the hierarchical-events attribute, the associations for a particular destination use this property to determine the default.

The default is false. For objects that live in a tree (rather than a cyclic graph), you may want to set this to true for a destination as a convenience. If you use properties of your properties in an item renderer for instance, setting this to true for that association property will cause the grid to refresh when these properties of properties change. The system is smart enough to avoid sending recursive events or creating large chains of events, such as parent.child[0].child[1].child[3].

The default value is false.



Implementation
    public function get hierarchicalEventsDefault():Boolean
    public function set hierarchicalEventsDefault(value:Boolean):void

indexReferences

property 
indexReferences:Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

To tune the speed of your application, set this property to false if you have a small number of fills or references to items managed by this data service from association properties of other items.



Implementation
    public function get indexReferences():Boolean
    public function set indexReferences(value:Boolean):void

isInitialized

property 
isInitialized:Boolean  [read-only]

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Indicates if the metadata associated with this service is initialized.

This property can be used as the source for data binding. When this property is modified, it dispatches the propertyChange event.



Implementation
    public function get isInitialized():Boolean

manualSync

property 
manualSync:ManualSyncConfiguration

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

The manualSync property provides access to the ManualSyncConfiguration instance for each data service. This class allows you to subscribe to changes made by other clients or on the server and it allows you to control how your changes are published to other clients which subscribe using this interface.



Implementation
    public function get manualSync():ManualSyncConfiguration
    public function set manualSync(value:ManualSyncConfiguration):void

maxFrequency

property 
maxFrequency:uint

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Determines the maximum number of messages per second the DataManager wants to receive. A server that understands this value uses it as an input while it determines how fast to send messages to the DataManager.

The default value is 0, which means DataManager does not have a preference for the message rate. Note that this property should be set before the DataManager subscribes and any changes after subscription do not have an effect until the DataManager unsubscribes and resubscribes.

The default value is 0.



Implementation
    public function get maxFrequency():uint
    public function set maxFrequency(value:uint):void

mergeRequired

property 
mergeRequired:Boolean  [read-only]

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Indicates if there are any pending changes that must be merged.

This property can be used as the source for data binding. When this property is modified, it dispatches the propertyChange event.



Implementation
    public function get mergeRequired():Boolean

pageSize

property 
pageSize:int

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Provides access to the current page size setting for all collections.



Implementation
    public function get pageSize():int
    public function set pageSize(value:int):void

pagingEnabled

property 
pagingEnabled:Boolean  [read-only]

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Indicates if the remote destination is configured to allow paged requests.



Implementation
    public function get pagingEnabled():Boolean

priority

property 
priority:int

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

The default message priority for the messages sent by the data service. The valid values are 0 to 9 (0 being lowest) and -1 means that the data service does not have a priority set. Note that if the message already has a priority defined, that takes precedence over this priority.



Implementation
    public function get priority():int
    public function set priority(value:int):void

requestTimeout

property 
requestTimeout:int

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Provides access to the request timeout in seconds for an operation. A value less than or equal to zero prevents request timeout. When a current operation times out due to the requestTimeout limit being reached a fault will be dispatched for that operation, indicating that the request was timed out. Note that when an operation times out, it is possible the server did in fact receive that operation. This can leave your client state out of sync with the server.



Implementation
    public function get requestTimeout():int
    public function set requestTimeout(value:int):void

resetCollectionOnFill

property 
resetCollectionOnFill:Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

When true, after the fill operation completes, a RESET event is sent. If false, just send incremental ADD/REMOVE events for each item returned from the fill result. Setting this property affects any fills you initiate. Changing it after a fill has started does not affect the behavior of the outstanding fill.

The default value is true.



Implementation
    public function get resetCollectionOnFill():Boolean
    public function set resetCollectionOnFill(value:Boolean):void

resubscribeAttempts

property 
resubscribeAttempts:int

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Controls the number of times a disconnected data service will attempt to resubscribe. The default, -1 means to continually resubscribe until the client is able to reconnect.

The default value is -1.



Implementation
    public function get resubscribeAttempts():int
    public function set resubscribeAttempts(value:int):void

resubscribeInterval

property 
resubscribeInterval:int

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Controls the delay, in milliseconds, between resubscribe attempts. The default is 5000, meaning attempt to resubscribe once every 5 seconds.

The default value is 5000.



Implementation
    public function get resubscribeInterval():int
    public function set resubscribeInterval(value:int):void

subscribed

property 
subscribed:Boolean  [read-only]

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Indicates if the DataService is subscribed to the remote destination.

This property can be used as the source for data binding. When this property is modified, it dispatches the propertyChange event.



Implementation
    public function get subscribed():Boolean

throwItemPendingErrors

property 
throwItemPendingErrors:Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Set this property to false if you want to suppress the throwing of item pending errors when lazily fetched or unpaged data is accessed. Instead of throwing the error, null is returned for a property value or a getItemAt() call in an ArrayCollection.

The size() method returns 0 elements for a list whose size has not yet been fetched from the server. When the element is returned from the server the appropriate PropertyChangeEvent and CollectionEvent events are dispatched.



Implementation
    public function get throwItemPendingErrors():Boolean
    public function set throwItemPendingErrors(value:Boolean):void
Constructor Detail

DataManager

()Constructor
public function DataManager()

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Constructs an instance of the DataService with the specified destination. The destination must be a reference to a destination configured in the services-config.xml file.

Method Detail

checkImplementation

()method
protected function checkImplementation():void

Queues a fault if this data manager has not yet been initialized.

clearCache

()method 
public function clearCache(value:Object = null):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Clears any data stored to disk with a previous call to saveCache() or when autoSaveCache was set to true

Parameters

value:Object (default = null) — Object reference to either a managed single object or ArrayCollection.

Returns
mx.rpc:AsyncToken — AsyncToken which can be used to respond to the success or failure of the operation.

clearCacheData

()method 
public function clearCacheData(descriptor:CacheDataDescriptor):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Clears the data specified by the passed descriptor from the local store.

Parameters

descriptor:CacheDataDescriptor — Reference to the descriptor for the data that should be removed from the local cache.

Returns
mx.rpc:AsyncToken — Reference to the token that can be used to determine when the result or fault has occurred for this operation.

commit

()method 
public function commit(itemsOrCollections:Array = null, cascadeCommit:Boolean = false):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Commits pending changes for all collections currently managed by the DataStore associated with this data service. Calling this method is equivalent to calling dataStore.commit().

When the autoCommit property is true, transactions are not used and you do not need to call this method. To use transactions, set the autoCommit property to false and call this method directly to commit a batch of changes.

You typically just call "commit()" with no arguments which will commit all pending changes. You can supply optional arguments to commit a subset of the pending changes. You must resolve all outstanding conflicts before you can commit changes to any item in the DataStore.

If the assembler is configured to have use-transactions set to true, all changes are committed atomically. If any operation fails, none of the operations in the batch are applied. If use-transactions is set to false, the operations are each committed individually until a failure occurs at which point processing stops. Any changes that occur before the error are applied, any changes which occur after the error are not applied. When an error occurs when processing a batch, the changes are put back into the uncommitted queue. You need to call revertChanges if you want to remove the changes which caused the error.

By default, the commit method will commit all pending changes for all items which have been created, modified, and deleted for this DataStore. If you want to commit a subset of these changes, you can specify a combination of managed ArrayCollection instances and/or managed items which define the subset of changes you want included in the batch. For each array collection you specify, any changes made either to the membership or order of items in that array collection or any changes to items in that array collection are committed. You can also specify a list of individual managed items so that only changes for those items are committed. If you specify any objects in the itemsOrCollections parameter which are not managed collections or items, a DataServiceError is thrown.

If you are using the itemsOrCollections parameter and your items have association properties which refer to other items, you can use the cascadeCommit parameter to control whether or not changes made to associated items are also included in batch. For example, if you specify a Group item in the items parameter, and the Group instance has a members property which refers to a list of Person instances when cascadeCommit is true changes to any Person instance will also be included in the set of changes committed. If cascadeCommit is false, only changes to the Group would be included. Use cascadeCommit=true to ensure that any dependent changes are included in the batch.

Parameters

itemsOrCollections:Array (default = null) — This is an optional parameter which defaults to null when you want to commit all pending changes. If you want to commit a subset of the pending changes use this argument to specify a list of managed ListCollectionView instances and/or managed items. ListCollectionView objects are most typically ArrayCollections you have provided to your fill method. The items appropriate for this method are any managed version of the item. These are any items you retrieve from getItem, createItem or using the getItemAt method from a managed collection. Only changes for the items defined by any of the values in this array will be committed.
 
cascadeCommit:Boolean (default = false) — If true, also commit changes made to any associated items supplied in this list.

Returns
mx.rpc:AsyncToken — AsyncToken that is returned in call property of either the ResultEvent.RESULT or in the FaultEvent.FAULT. Custom data can be attached to this object and inspected later during the event handling phase. If no changes have been made to the relevant items, null is returned instead of an AsyncToken.

Throws
Error — if initialization is in progress. This may occur when a runtime destination is referenced and commit is called before this service has been initialized, or if the cacheID has been set and the local cache has not been loaded. In each situation waiting for the result or fault on a token returned from a call to initialize or from a previous operation, before calling commit will avoid the error.

connect

()method 
public function connect():mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Forces a connection attempt by this service to the remote destination. This method may be used in conjunction with the autoConnect property and disconnect() method to control connection status.

Returns
mx.rpc:AsyncToken — AsyncToken reference to the token that will identify this operation in a result or fault event dispatched from this service. When calling connect() the token's result handler will always be called and the result will be the current value of this service's connected property.

count

()method 
public function count(... args):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Calls a count method on the remote destination. The count method called is based on the associated <count-method> tags and the parameters passed. For example, if the following count("firstName", "Bob") call was made and <count-method> tags exist or are referenced in the services-config.xml under the associated destination:

            <count-method>
                <name>getCount</name>
                <params>java.lang.String,java.lang.String</params>
                <security-run-as name="freddie" password="nightmare" />
            </count-method>
     
            <count-method>
                <name>getCount</name>
                <security-constraint ref="sample-users" />
            </count-method>
      
The first <count-method> with the run-as security setting is invoked because it contains two parameters, which matches the <params> tag types and count.

Parameters

... args — List of arguments that should be passed to the remote destination.

Returns
mx.rpc:AsyncToken — Object returned in the call property of the ResultEvent.RESULT or in the FaultEvent.FAULT. Custom data can be attached to this object and inspected later during the event handling phase.

See also

createItem

()method 
public function createItem(item:Object):ItemReference

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Requests that the specified item be created in the remote store. If an error occurs a DataConflictEvent is dispatched.

Parameters

item:Object — Object that should be created in the remote store.

Returns
ItemReference — ItemReference (which extends AsyncToken). This reference is returned in the token property of either the ResultEvent.RESULT or in the FaultEvent.FAULT. Custom data can be attached to this object and inspected later during the event handling phase. The result property of this object is bindable and can be used to bind the item returned. This result object is set to null if the item is removed from another client. If you hold on to ItemReference objects in your application, you should call the releaseItem() method in the ItemReference when you are finished with this reference to the item. If you do not hold onto the ItemReferences, you can use the releaseItem() method on the DataService, which takes the instance of the item itself to release. When createItem() fails, it returns a fault. However, the item is still pending. You must call release() to remove it.

deleteItem

()method 
public function deleteItem(item:Object):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Requests that the specified item be deleted from the remote store. If an error occurs a DataConflictEvent will be dispatched.

Parameters

item:Object — The Object that should be deleted in the remote store.

Returns
mx.rpc:AsyncToken — AsyncToken that will be returned in the token property of either the ResultEvent.RESULT or in the FaultEvent.FAULT. Custom data can be attached to this object and inspected later during the event handling phase.

disconnect

()method 
public function disconnect():void

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Disconnects the DataService's network connection. This method does not wait for outstanding network operations to complete.

executeQuery

()method 
public function executeQuery(queryName:String, propertySpecifier:PropertySpecifier, ... args):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Executes a query with the provided name and arguments. You typically use this method with the RPCDataManager where queries have a specific name. You can also use this method with queries defined using the more general fill method approach as long as the first parameter to the fill method is a string value. The queryName is used as the first fill parameter.

Note that when you are finished with the objects returned by this method, you should call releaseCollection() method for collection results or releaseItem for single valued item results. Alternatively you can release all managed references retrieved from this data manager by calling the release() method.

Use refreshCollection to refresh the contents of any collections returned by this method.

Parameters

queryName:String — The name of the operation to invoke.
 
propertySpecifier:PropertySpecifier — set of properties to be retrieved.
 
... args — the list of arguments to the query.

Returns
mx.rpc:AsyncToken — AsyncToken bind to the result property of the AsyncToken to retrieve the result. Otherwise, you can listen for the result property change event, add one or more responders to the token and add additional information as dynamic properties of the token to keep track of the results of the operation.

fill

()method 
public function fill(value:ListCollectionView, ... args):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Fills the specified ListCollectionView based on the associated fill method of the destination. For example, for a LiveCycle Data Services destination that uses the fill-method approach, if the following <fill-method> elements exist or are referenced in the services-config.xml file under the associated destination:

            <fill-method>
                <name>loadPersons</name>
                <params>java.lang.String,java.lang.String</params>
                <security-run-as name="freddie" password="nightmare" />
            </fill-method>
     
            <fill-method>
                <name>loadPersons</name>
                <security-constraint ref="sample-users" />
            </fill-method>
      
Then calling fill(myCollection, ["firstName", "Bob"]) invokes the first <fill-method> with the run-as security setting since it contains two parameters, matching the <params> tag types and count. Likewise, calling fill(myCollection) invokes the second <fill-method> tag as it contains no <params> tag. Any pending changes to items in this collection are tossed. Also note that any data in the collection is cleared when you call fill. You can call fill using a previously filled collection as well. In this case, if the fill parameters are the same, the collection is cleared and the fill method on the server is called again. If the fill parameters are different the old collection is released and the new collection is filled.

Parameters

value:ListCollectionView — Reference to the collection that should be filled with the specified arguments.
 
... args — Variable list of arguments that should be passed to the remote destination.

Returns
mx.rpc:AsyncToken — AsyncToken You can use this token to register one or more callback functions to receive result or fault events from this fill operation. This token is also returned in the call property of the ResultEvent.RESULT or in the FaultEvent.FAULT. Custom data can be attached to this object and inspected later during the event handling phase.

fillSubset

()method 
public function fillSubset(value:ListCollectionView, ps:PropertySpecifier, ... args):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Fills the specified ListCollectionView based on the associated fill method of the destination. Only a subset of the properties are populated on each object, as specified in the propertySpecifier parameter. For example, for a LiveCycle Data Services destination that uses the fill-method approach, if the following <fill-method> elements exist or are referenced in the services-config.xml file under the associated destination:

            <fill-method>
                <name>loadPersons</name>
                <params>java.lang.String,java.lang.String</params>
                <security-run-as name="freddie" password="nightmare" />
            </fill-method>
     
            <fill-method>
                <name>loadPersons</name>
                <security-constraint ref="sample-users" />
            </fill-method>
      
Then calling fillSubset(myCollection, ["firstName", "Bob"]) invokes the first <fill-method> with the run-as security setting since it contains two parameters, matching the <params> tag types and count. Likewise, calling fillSubset(myCollection) invokes the second <fill-method> tag as it contains no <params> tag. Any pending changes to items in this collection are tossed. Also note that any data in the collection is cleared when you call fillSubset. You can call fillSubset using a previously filled collection as well. In this case, if the fill parameters are the same, the collection is cleared and the fill method on the server is called again. If the fill parameters are different the old collection is released and the new collection is filled.

Parameters

value:ListCollectionView — Reference to the collection that should be filled with the specified arguments.
 
ps:PropertySpecifier — A PropertySpecifier object to be passed to the server's fill implementation, specifying what subset of properties should be populated on each item.
 
... args — Variable list of arguments that should be passed to the remote destination.

Returns
mx.rpc:AsyncToken — AsyncToken You can use this token to register one or more callback functions to receive result or fault events from this fill operation. This token is also returned in the call property of the ResultEvent.RESULT or in the FaultEvent.FAULT. Custom data can be attached to this object and inspected later during the event handling phase.

findItem

()method 
public function findItem(queryName:String, propertySpecifier:PropertySpecifier, ... args):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Executes a query which returns a single item.

Parameters

queryName:String — The name of the operation to invoke.
 
propertySpecifier:PropertySpecifier — set of properties to be retrieved.
 
... args — the list of arguments to the query.

Returns
mx.rpc:AsyncToken — AsyncToken bind to the result property of the AsyncToken to retrieve the result. Otherwise, you can listen for the result property change event, add one or more responders to the token and add additional information as dynamic properties of the token to keep track of the results of the operation.

getCacheData

()method 
public function getCacheData(descriptor:CacheDataDescriptor):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Returns an ArrayCollection or a single managed object (SMO) from the the local store. Calling this method will not update the last accessed time.

Parameters

descriptor:CacheDataDescriptor — CacheDataDescriptor for the desired cache data.

Returns
mx.rpc:AsyncToken — AsyncToken reference to the token that can be used to determine when the result or fault has occurred for this operation. The result property of the AsyncToken or on the associated event will contain a new instance of an unmanaged ArrayCollection or ItemReference for each call.

getCacheDescriptors

()method 
public function getCacheDescriptors(view:ListCollectionView, options:uint = 0, item:Object = null):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This method will fill the specified ListCollectionView with CacheDataDescriptor(s). If no argument is specified then all associated CacheDataDescriptors for cached data under this service will be returned.

Parameters

view:ListCollectionView — ListCollectionView reference to a collection that can be filled with the desired descriptors.
 
options:uint (default = 0) — Must be one of the following constants:
  • CacheDataDescriptor.FILL - indicates that only descriptors for filled collections should be returned collection.
  • CacheDataDescriptor.ITEM - indicates that only descriptor for managed items should be returned in the collection.
  • CacheDataDescriptor.ALL - [default] indicates that all descriptors should be returned.
 
item:Object (default = null) — Object reference to a specific ItemReference, managed item, or ListCollectionView, when specified this parameter overrides the options argument.

Returns
mx.rpc:AsyncToken — AsyncToken reference to the token that will identify this operation in a result or fault event dispatched from this service.

getCacheIDs

()method 
public function getCacheIDs(view:ListCollectionView):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This method will fill the specified ListCollectionView with all cache identifiers previously used in the application.

Parameters

view:ListCollectionView — ListcollectionView reference to a collection that should be filled with all cache identifiers previously used in the application.

Returns
mx.rpc:AsyncToken — AsyncToken reference to the token that will identify this operation in a result or fault event dispatched from this service.

getItem

()method 
public function getItem(identity:Object, defaultValue:Object = null):ItemReference

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Makes an asynchronous request for an item matching the specified identity. If you provide a defaultValue, and the item does not exist, the item is created instead using the information in the defaultValue. This method returns an ItemReference. If you receive a valid instance from the getItem() method call, you must call the releaseItem() method to release an instance of the item. If you hang onto the ItemReference, you should call the releaseItem() method on the reference to be sure you release the proper reference (in case your client has made more than one getItem() method call for the same item). If you do not hold onto the ItemReference, you can call the releaseItem() method on the DataService with the item itself.

Parameters

identity:Object — Object that contains the identity properties for the desired object.
 
defaultValue:Object (default = null) — An instance of the type with the default values that should be created if it doesn't exist.

Returns
ItemReference — ItemReference to the item you want to get. The ItemReference extends AsyncToken so you can use it to receive notification of when the item has been retrieved or when this call produces a fault. The ItemReference is returned as the token property in either the ResultEvent.RESULT or in the FaultEvent.FAULT if you are listening for events on the DataService object. Custom data can be attached to this object and inspected later during the event handling phase. You also can use data binding to bind to the result property of the ItemReference. This property is set to a valid value when the item is populated from the remote destination and is bindable so you can simply bind your user interface controls to the properties of the ItemReference's result property. If the item is removed from the server or another client, this reference is set to null. The ItemReference also has an invalid property which is set to true if the are errors returning the item or if the server returns null for an item.

getLocalItem

()method 
public function getLocalItem(identity:Object):Object

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Looks up the supplied item with the given identity. If the item is already managed on this client, the managed instance is returned. If not, null is returned. Unlike the getItem call, this call does not make a request to the server and does not add an additional reference to the item.

Parameters

identity:Object — Object that contains the identity properties for the desired object.

Returns
Object — The managed object or null if the item with this id is not yet managed on this client.

getPageInformation

()method 
public function getPageInformation(view:ListCollectionView):PageInformation

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Returns page information for the specified collection.

Parameters

view:ListCollectionView — Collection of interest.

Returns
PageInformation — Page information for the specified collection.

getPendingOperation

()method 
public function getPendingOperation(item:Object):uint

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Returns the pending operation in the message cache for the specified item. Use this method to provide visual feedback to a user of what type of change, if any, has been made to an item.

Parameters

item:Object — IManaged object that should be tested against.

Returns
uint — uint that indicates what pending operation has been performed. The following are valid operations for an item:
  • DataMessage.CREATE_OPERATION - indicates that a create is pending for the specified item.
  • DataMessage.DELETE_OPERATION - indicates that a delete is pending for the specified item.
  • DataMessage.UPDATE_OPERATION - indicates that updates are pending for the specified item.
  • DataMessage.UNKNOWN_OPERATION - indicates that no operations are pending for the specified item.

initialize

()method 
public function initialize():mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Forces initialization of the DataStore.

Returns
mx.rpc:AsyncToken — AsyncToken reference to the token that will identify this operation in a result or fault event dispatched from this service.

isCollectionManaged

()method 
public function isCollectionManaged(view:ListCollectionView):Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Returns true if the passed collection is managed by this service. If the collection is managed by this service it is safe to pass the collection to releaseCollection() to release it from management.

Parameters

view:ListCollectionView — The ListCollectionView reference to test whether it is managed by this service.

Returns
Boolean — True if the collection is managed by this service; otherwise false.

isCollectionPaged

()method 
public function isCollectionPaged(view:ListCollectionView):Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Returns true if the passed collection is using paging features. If the collection is paged by this service it is safe to pass the collection to releaseItemsFromCollection() to release individual items in the collection from management.

Parameters

view:ListCollectionView — The ListCollectionView reference to test whether it is managed by this service.

Returns
Boolean — True if the collection is using paging otherwise false.

isRangeResident

()method 
public function isRangeResident(view:ListCollectionView, startIndex:int, numberOfItems:int):Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Returns true if the supplied range of items is all paged in. Otherwise returns false.

Parameters

view:ListCollectionView — A ListCollectionView managed by this data service.
 
startIndex:int — The starting index in the ListCollectionView.
 
numberOfItems:int — The number of items in the ListCollectionView.

Returns
Booleantrue if the collection is all resident, false if any of the items in the supplied range are not resident.

merge

()method 
public function merge():void

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Merges any pending updates into the managed set of objects. The process of merging changes detect conflicts and process any pending item requests. This merges all messages for any other DataService instances that share this same data store.

refresh

()method 
public function refresh():mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Refreshes all data managed by this data service. Fills, getItems, and page requests will be made to the server to re-fetch all items managed by this type. Use DataStore.refresh() to also refresh all associated items for lazy = true associations.

Returns
mx.rpc:AsyncToken — AsyncToken You can use this token to register one or more callback functions for the result or fault events of the refresh operation.

refreshCollection

()method 
public function refreshCollection(value:ListCollectionView):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Refreshes an array collection previously filled with the fill method or managed as a managed association. This method makes a request to the server, fetches the new version of any resident items in the collection using the fill parameters original used with this collection or by fetching the property from the parent item. If any changes are found, they merged into the collection in an incremental fashion.

Parameters

value:ListCollectionView — A ListCollectionView managed by this data service.

Returns
mx.rpc:AsyncToken — AsyncToken You can use this token to register one or more callback functions to receive result or fault events from this refresh operation. Null is returned if there is nothing to refresh for a paged collection. This token is also returned in the call property of the ResultEvent.RESULT or in the FaultEvent.FAULT. Custom data can be attached to this object and inspected later during the event handling phase.

release

()method 
public function release(clear:Boolean = true, copyStillManagedItems:Boolean = true):void

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Releases all managed collections and items for the DataService.

Parameters

clear:Boolean (default = true) — Boolean indicating if the all items should be removed from the list. In addition no copies will be made of any item.
 
copyStillManagedItems:Boolean (default = true) — if after releasing this data service references from managed associations from another data services might hold references to some of these managed objects. In that case, some managed collections in this data service might still be actively managed. If you pass true for this flag, these references are either removed (clear=true) or cloned (clear=flase). If you pass in false for this flag, those active references are left alone. Using false is the fastest way to clear the state of the system. Using true ensures you don't have any managed state in references to collections or items you retrieved from this data service.

See also

releaseCollection

()method 
public function releaseCollection(view:ListCollectionView, clear:Boolean = false, copyStillManagedItems:Boolean = true):void

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Releases any item within the specified collection from management by this service. If the item exists in more than one collection, a copy of the item is made. Any uncommitted changes made to an item that exists only in this collection are released, including deletes, creates and updates.

Parameters

view:ListCollectionView — ListCollectionView reference that should no longer receive remote updates.
 
clear:Boolean (default = false) — Indicates if the all items should be removed from the list. In addition no copies will be made of any item.
 
copyStillManagedItems:Boolean (default = true) — Indicates if there are other managed references to items in this collection, this parameter controls whether copies of those items are made so that after this call you are guaranteed that there are no longer any managed items in the collection. Specifying both clear and this option as false will result in the fastest way to release managed references.

releaseItem

()method 
public function releaseItem(item:IManaged, copyStillManagedItems:Boolean = true, enableStillManagedCheck:Boolean = true):IManaged

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Releases the specified item from management by this service. If you hold onto ItemReferences, you should call the releaseItem() method on the ItemReference to be sure you release the proper reference in the case where you might have made more than one getItem call which retrieves the same item from different parts of your client application.

This call releases any associated resources, including nested properties. The specified item no longer receives updates from the remote destination. In addition if there are any uncommited changes to this item and it does not appear in any other collection these changes will also be released. If the specified item exists in more than one collection then the value handed back will be a copy of the original unless the allowCopy parameter is set to false.

Parameters

item:IManaged — IManaged reference to the item to be released.
 
copyStillManagedItems:Boolean (default = true) — Boolean indicating if we should make copies of the items which are still managed in the graph of objects. Passing a value of false will clear the reference to these items.
 
enableStillManagedCheck:Boolean (default = true) — Boolean pass a value of false for this parameter to disable either the copy or the clear of still managed items. In that case your returned value will always be the original managed value you released and if another reference is still using that item, it will continue to be managed even after the release.

Returns
IManaged — The released item which will be a copy if copyStillManagedItems=false and the item is managed by another reference.

releaseItemsFromCollection

()method 
public function releaseItemsFromCollection(collection:ListCollectionView, startIndex:int, numberOfItems:int):int

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Releases a range of items in the collection. When paging through a large collection you may want to free up resources occupied by items in the collection and stop subscribing for updates for those items. You specify the startIndex of the first item you want to release and the number of items to release. If an item at that position is not yet paged that index is skipped.

Parameters

collection:ListCollectionView — A managed ListCollectionView.
 
startIndex:int — The index of the first item to release.
 
numberOfItems:int — The number of items to release starting at position. numberOfItems should be greater than 0 and startIndex + numberOfItems should be less than collection.length.

Returns
int — The number of references released.

releaseReference

()method 
public function releaseReference(item:Object, propName:String):Boolean

Releases the value for a single-valued association. If the value is not paged in false is returned. If the value is paged in, that reference is released and true is returned. If this was the last reference to the specific item, the next attempt to access that item will cause the ItemPendingError and the value to be fetched again.

Parameters

item:Object — The parent item containing a property which is a single valued association.
 
propName:String — The name of the property referring to a single valued association.

Returns
Boolean — true if the value was released.

revertChanges

()method 
public function revertChanges(item:IManaged = null):Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Reverts any uncommitted changes to the specified item. Or if no item is supplied, it will revert all uncommitted changes. If you revert a create operation, it removes the item. If you revert a delete, it adds the item back in. Reverting an update restores the original properties of the item that were in place before you started changing it. Calling this method is equivalent to calling dataStore.revertChanges().

One situation in which you would use this method is after a fault has occurred. In that case, any failed changes are put back into the uncommitted changes list. At that point you can either modify those changes to fix the problem or revert them using this method to keep those changes from being resubmitted again.

If an item is supplied and this item doesn't have any changes this method will return false. If no item is supplied and there are no changes this method returns false. Otherwise, it returns true.

Parameters

item:IManaged (default = null) — reference to revert changes for or null to revert all changes.

Returns
Boolean — Boolean indicating if any changes were reverted.

revertChangesForCollection

()method 
public function revertChangesForCollection(collection:ListCollectionView = null):Boolean

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Reverts the changes for any item contained in the specified collection which should be managed by this data service.

Parameters

collection:ListCollectionView (default = null)

Returns
Boolean — Boolean true if any changes were reverted.

saveCache

()method 
public function saveCache(value:Object = null):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

This method will save the current state of the DataService cache. The cache includes in-memory items and changes made to those items that have not been sent to the remote destination.

Parameters

value:Object (default = null) — Object reference to either a managed ListCollectionView or object.

Returns
mx.rpc:AsyncToken — AsyncToken which can be used for notification of when the operation completes successfully or fails.

See also

autoSaveCache

Example  ( How to use this example )
         var customerService:DataService = new DataService("customers");
         var customers:ArrayCollection = new ArrayCollection();
         customerService.fill(customers);
         // ...
         var customer:Customer = Customer(customers[0]);
         customer.priority = "top";
         customerService.saveCache();
         // now all of the changes and items in the customers collection
         // will be persisted locally
      

updateItem

()method 
public function updateItem(item:Object, origItem:Object = null, changes:Array = null):mx.rpc:AsyncToken

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

Triggers an update for the specified item. If you call this with the managed instance it will commit any changes you've made to that item and return a token you can use to track those changes. If there are no pending changes for that item, a null token is returned. If you call this with another copy of the instance, it copies any changed properties in the changes array into the managed instance logging any changes and then commits those changes. If autoCommit is true, the changes for this item are committed immediately. If it is false, the changes are queued until commit is called.

Parameters

item:Object — item to be updated.
 
origItem:Object (default = null) — version of the item before changes were made. This version is used for conflict detection. May be null.
 
changes:Array (default = null) — array of property names that have been updated. Used for performance improvement. May be null.

Returns
mx.rpc:AsyncToken — an AsyncToken you can use to track the changes (i.e. a fault or result event is delivered when changes to this item are committed). If there are no changes to an item a null AsyncToken is returned and nothing is queued.
Event Detail

conflict

Event
Event Object Type: mx.data.events.DataConflictEvent
property DataConflictEvent.type = mx.data.events.DataConflictEvent.CONFLICT

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

The DataConflictEvent.CONFLICT event is dispatched when a conflict is detected between either pending local changes and changes submitted by another client, or when changes submitted by this client are conflicting with those in the remote destination. Each DataService sends conflict events only for items of this particular destination. Use the conflict event on the DataService if you need to handle conflicts for a set of related destinations at the same time.

The CONFLICT constant defines the value of the type property of the event object for a conflict event.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
cancelablefalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
conflict The Conflict object that holds the conflict that occurred.
message The Message associated with this event.
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

fault

Event  
Event Object Type: mx.data.events.DataServiceFaultEvent
property DataServiceFaultEvent.type = mx.data.events.DataServiceFaultEvent.FAULT

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

The DataServiceFaultEvent.FAULT event is dispatched when a service call fails due to an error. For example, a call to the fill() method dispatches this event if the call fails. You'll also get this event for each item which generates an error as part of a commit result. In this case, the DataServiceFaultEvent will contain the token returned by the commit, but the item and error message strings in the fault are specific to the item which caused the error.

The FAULT constant defines the value of the type property of the event object for a fault event.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
cancelabletrue, calling preventDefault() from the associated token's responder.fault method will prevent the service or operation from dispatching this event
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
fault The Fault object that holds the conflict that occurred.
item The item that generated the fault.
identity The identity of of the item that generated the fault.
message The Message associated with this event.
token The token that represents the call to the method. Used in the asynchronous completion token pattern.
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

message

Event  
Event Object Type: mx.messaging.events.MessageEvent
property MessageEvent.type = mx.messaging.events.MessageEvent.MESSAGE

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

The MessageEvent.MESSAGE event is dispatched when the remote destination pushes a notification of a data operation. For example, when data is updated in the remote destination an update operation is sent to all clients listening, this operation is converted to a message event on this DataService.

The MESSAGE event type; dispatched upon receipt of a message.

The value of this constant is "message".

The properties of the event object have the following values:

PropertyValue
bubblesfalse
cancelablefalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
messageThe message associated with this event.
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

propertyChange

Event  
Event Object Type: mx.events.PropertyChangeEvent
property PropertyChangeEvent.type = mx.events.PropertyChangeEvent.PROPERTY_CHANGE

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

The PropertyChangeEvent.PROPERTY_CHANGE event is dispatched when a property of this service changes. This happens for the following properties:

  • commitRequired
  • mergeRequired
  • connected

The PropertyChangeEvent.PROPERTY_CHANGE constant defines the value of the type property of the event object for a PropertyChange event.

The properties of the event object have the following values:

PropertyValue
bubblesDetermined by the constructor; defaults to false.
cancelableDetermined by the constructor; defaults to false.
kindThe kind of change; PropertyChangeEventKind.UPDATE or PropertyChangeEventKind.DELETE.
oldValueThe original property value.
newValueThe new property value, if any.
propertyThe property that changed.
sourceThe object that contains the property that changed.
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

result

Event  
Event Object Type: mx.rpc.events.ResultEvent
property ResultEvent.type = mx.rpc.events.ResultEvent.RESULT

Language Version: ActionScript 3.0
Product Version: LiveCycle Data Services 3
Runtime Versions: Flash Player 9, AIR 1.1

The ResultEvent.RESULT event is dispatched when a service call successfully returns. For example a call to fill() will dispatch this event if the call is successful.

The RESULT event type.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
cancelabletrue, preventDefault() from the associated token's responder.result method will prevent the service or operation from dispatching this event
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
message The Message associated with this event.
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.
resultResult that the RPC call returns.
tokenThe token that represents the indiviudal call to the method. Used in the asynchronous completion token pattern.