Adobe® Flex® 4 Language Reference
Show Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
mx.data 
DataStore 
Packagemx.data
Classpublic class DataStore
InheritanceDataStore Inheritance EventDispatcher Inheritance Object

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

A DataStore batches transactions for one or more DataService instances. It manages the set of pending changes destined for the server and also stores the set of conflicts received from the server. By default, if your DataService does not have managed associations, it automatically gets its own independent DataStore. Each call to the commit() method send only changes made to that DataService.

When you use managed associations, the default changes so that all DataService instances that share the same set of channels and have the same value of the use-transactions flag share the same DataStore. When you are sharing a DataStore, a single call to the commit() method applies to all changes made by all DataService instances sharing that DataStore. The default changes because with managed associations, it is possible that changes between destinations can have dependencies so it is important to preserve the order of operations on the client when sending messages to the server.

If you want to change the default, you can create your own DataStore and manually assign it to the dataStore property of one or more DataService instances. Do this when you first initialize your DataService, before you have issued any other DataService api calls such as fill or getItem. Note: All DataServices which share the same DataStore must be using the same set of channels and the same setting for useTransactions flag. Settings that are not consistent will throw an error.

See also



Public Properties
 PropertyDefined By
  autoCommit : Boolean
If set to true, operations that modify the state managed by the DataService are committed immediately.
DataStore
  autoCommitCollectionChanges : Boolean = true
When set to true, any changes made to a collection are committed immediately if the autoCommit property is true.
DataStore
  autoCommitPropertyChanges : Boolean = true
When set to true and the autoCommit property is set to true, any property value change automatically leads to a "commit" for that change.
DataStore
  autoConnect : Boolean
Indicates if this service should attempt to connect for any operations that require a connection.
DataStore
  autoConnectInterval : int = 5000
Time interval in milliseconds to wait between attempts to connect to the server when the autoConnect property is true.
DataStore
  autoMerge : Boolean
Controls how changes that other clients make are merged into this client's current view of the data.
DataStore
  autoSaveCache : Boolean
The local cache of data and changes can be stored to disk.
DataStore
  cacheID : String
Provides access to the cache identifier for this service.
DataStore
  channelSet : ChannelSet
Provides access to the ChannelSet used by the this DataStore.
DataStore
  commitQueueMode : int
Controls when a committed batch of changes is sent to the server when you call commit on a second batch while the client is still waiting for a reply from a previously committed batch.
DataStore
  commitRequired : Boolean
[read-only] Indicates if there are pending updates that must be committed.
DataStore
  conflicts : Conflicts
[read-only] The list of conflicts for all managed items.
DataStore
  connected : Boolean
[read-only] Indicates whether the DataStore is connected.
DataStore
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  currentBatch : MessageBatch
[read-only] The current batch of changes waiting to be committed to the server when you autoCommit=false.
DataStore
  destination : String
[read-only] The destination for this DataStore.
DataStore
  detectConflictsOnRefresh : Boolean = true
A flag you can set to disable conflict detection during the refresh/reconnect operation.
DataStore
  identifier : String
The identifier of this DataStore.
DataStore
  isInitialized : Boolean
[read-only] Indicates when this DataStore is initialized and ready for use.
DataStore
  mergeRequired : Boolean
[read-only] Indicates if there are any pending changes that must be merged.
DataStore
  priority : int
The default message priority for the messages sent by the DataStore.
DataStore
  processingServerChanges : Boolean
Indicates whether or not pushed server changes are currently being merged into the client's view of the managed objects.
DataStore
 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.
DataStore
  restoreCommittedUnsentBatchesOnFault : Boolean = false
When the client receives an error processing a message, setting this property to true causes it to "uncommit" any batches which you've committed but have not yet been sent to the server.
DataStore
  saveCacheMinIntervalMillis : int = 0
This time interval can be set to reduce the frequency of how often the cache is saved.
DataStore
  throwErrorOnIDChange : Boolean = true
A flag you can set to false to restore the LiveCycle Data Services 2.6 behavior of logging an error but not throwing an error when the UID property is changed.
DataStore
  uncommittedBatches : ArrayCollection
[read-only] The list of MessageBatches which are currently uncommitted.
DataStore
Public Methods
 MethodDefined By
  
DataStore(destination:String, useTransactions:Boolean, adapter:DataServiceAdapter = null)
Normally, a DataStore is created automatically for you but you can create your own DataStore and assign it to the dataStore property of a DataService.
DataStore
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
EventDispatcher
  
commit(itemsOrCollections:Array = null, cascadeCommit:Boolean = false):mx.rpc:AsyncToken
Commits pending changes for collections and items managed by this DataStore.
DataStore
  
Forces a connection attempt by this service to the remote destination.
DataStore
  
createBatch(itemsOrCollection:Array = null, cascadeCommit:Boolean = false, properties:Object = null):MessageBatch
Takes any changes specified by this operation, creates a new MessageBatch and puts that batch into the uncommittedBatches list.
DataStore
  
Forces all data services using this data store to be disconnected.
DataStore
 Inherited
Dispatches an event into the event flow.
EventDispatcher
  
This method will fill the specified ListCollectionView with all cache identifiers previously used in the application.
DataStore
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
  
Log the user out from the current destination.
DataStore
  
Merges any pending updates into the managed set of objects.
DataStore
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
  
Refetch all data managed on the client.
DataStore
  
release(clear:Boolean = true, copyStillManagedItems:Boolean = true):void
Release all data managed on the client.
DataStore
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
  
Reverts all pending (uncommitted) changes for all DataServices managed by this DataStore.
DataStore
  
Reverts all pending (uncommitted) changes for any items in the specified managed collection.
DataStore
  
setCredentials(username:String, password:String):void
Set the credentials for this DataStore destination.
DataStore
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
  
Set the credentials for the 3rd party of this DataStore destination.
DataStore
 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
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
  Dispatched when a conflict is detected between either pending changes on this client and changes submitted by another client, or when changes submitted by this client result detect a conflict error at the remote destination.DataStore
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
  The FaultEvent.FAULT event is dispatched when the commit call returns an error.DataStore
  The ResultEvent.RESULT event is dispatched when the commit call successfully returns.DataStore
Public Constants
 ConstantDefined By
  CQ_AUTO : int = 1
[static] Specifies to check for simple dependencies between any outstanding batches and the next batch to commit.
DataStore
  CQ_NOWAIT : int = 3
[static] Specifies to send the second batch immediately, not checking for dependencies.
DataStore
  CQ_ONE_AT_A_TIME : int = 0
[static] Specifies to wait for a previous batch to complete before committing a new batch.
DataStore
Property Detail

autoCommit

property
autoCommit:Boolean

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

If set to true, operations that modify the state managed by the DataService are committed immediately. If set to false, you must explicitly call the commit() method to send the changes to the server.

The default value is true.



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

autoCommitCollectionChanges

property 
public var autoCommitCollectionChanges:Boolean = true

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

When set to true, any changes made to a collection are committed immediately if the autoCommit property is true. When it is set to false, any add/remove operations you perform on a collection are not committed immediately.

The default value is true.

autoCommitPropertyChanges

property 
public var autoCommitPropertyChanges:Boolean = true

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

When set to true and the autoCommit property is set to true, any property value change automatically leads to a "commit" for that change. If false, changing the property on a VO will not automatically cause a commit call. To commit an update, you instead can call the commit() method explicitly, or you can call the DataManager.updateItem() method to commit changes to just that item.

The default value is true.

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



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

autoConnectInterval

property 
public var autoConnectInterval:int = 5000

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

Time interval in milliseconds to wait between attempts to connect to the server when the autoConnect property is true.

The default value is 5000.

autoMerge

property 
autoMerge:Boolean

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

Controls how changes that other clients make are merged into this client's current view of the data. If this property is false, messages are queued up until the application invokes the merge() method explicitly. If this property is true, changes are applied as they come in. If the client has pending uncommitted changes made to an item that conflict with the merged changes, a conflict is generated and added to the list of unresolved conflicts for this client. You can listen for change events on this property to be notified when a merge needs to be applied.



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 locally use the saveCache method.



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

See also

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 DataServiceError will be thrown during any operation that requires data from the local disk. This property is 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.



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

channelSet

property 
channelSet:ChannelSet

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

Provides access to the ChannelSet used by the this DataStore. The ChannelSet can be manually constructed and assigned, or it will be dynamically created to use the configured Channels for the destinations using this DataStore. The channelSet should be the same for all DataService objects using the same DataStore.



Implementation
    public function get channelSet():ChannelSet
    public function set channelSet(value:ChannelSet):void

commitQueueMode

property 
commitQueueMode:int

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

Controls when a committed batch of changes is sent to the server when you call commit on a second batch while the client is still waiting for a reply from a previously committed batch. If the batch is immediately sent to the server, it can cause problems if changes in this batch are dependent upon changes made by the server when committing the previous batch. For example, you may be updating an item created by the server in the first batch. If the server assigned id has not yet been received by the client, the update will not include the proper id for that item. If the second batch always waits for the first batch to complete, it can increase the time it makes to perform a series of changes that are time dependent (e.g. if you are updating a cursor position over and over again).

The default mode is CQ_AUTO. This mode checks for simple dependencies between any outstanding batches and the next batch to commit. If it sees that there are none, it sends the new batch immediately. If it sees that it has an update or a delete which depend upon an outstanding create, it holds the update/delete until the create completes. This imposes some overhead on each commit to check for dependencies but is typically a good compromise between the other two modes, CQ_NOWAIT and CQ_ONE_AT_A_TIME.

CQ_NOWAIT will send the second batch immediately, not checking for dependencies. You might use this mode if you are assigning ids for new objects on the client and need to overlap batches to achieve performance goals.

CQ_ONE_AT_A_TIME will always wait for a previous batch to complete before committing a new batch. This mode simplifies error handling logic by ensuring the server will not receive a batch of changes missing changes made by the server in handling the previous batch. It also ensures that if an error occurs handling one batch that the server won't receive a second batch until the errors for the first one are resolved on the client.

The default value is CQ_AUTO.



Implementation
    public function get commitQueueMode():int
    public function set commitQueueMode(value:int):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 pending updates that must be committed.

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

conflicts

property 
conflicts:Conflicts  [read-only]

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

The list of conflicts for all managed items.

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 whether the DataStore is connected.

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

currentBatch

property 
currentBatch:MessageBatch  [read-only]

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

The current batch of changes waiting to be committed to the server when you autoCommit=false. You can use this property to iterate through the changes that will be applied when you call the commit() method. A batch can be committed or reverted independently of the other batches. The entire set of uncommitted batches is stored in the uncommittedBatches property. The value of the currentBatch property is always the last batch in the uncommittedBatches list.

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 currentBatch():MessageBatch

destination

property 
destination:String  [read-only]

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

The destination for this DataStore.



Implementation
    public function get destination():String

detectConflictsOnRefresh

property 
public var detectConflictsOnRefresh:Boolean = true

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

A flag you can set to disable conflict detection during the refresh/reconnect operation. In LiveCycle Data Services version 2.6.1, conflict detection was not done on refresh so you can set this to false to restore the 2.6.1 behavior.

The default value is true.

identifier

property 
identifier:String

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

The identifier of this DataStore. This optional property is used with cache configuration to uniquely identify this DataStore. This value must be session independent, that is, you should not create this identifier at runtime using a method like UIDUtil.createUID() If this value is not assigned one is calculated based on server configuration values for the associated channels.



Implementation
    public function get identifier():String
    public function set identifier(value:String):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 when this DataStore is initialized and ready for use. This property is only needed when working with a runtime configured application or one that needs access to locally cached data on disk.

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

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

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 DataStore. The valid values are 0 to 9 (0 being lowest) and -1 means that the DataStore 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

processingServerChanges

property 
processingServerChanges:Boolean

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

Indicates whether or not pushed server changes are currently being merged into the client's view of the managed objects. This happens at any time when autoMerge is true. If autoMerge is false, this will only be set when you are explictly calling the merge method. The point of this flag is to let you know the difference between an asynchronous server pushed changed and one made by the user in your set methods.

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 processingServerChanges():Boolean
    public function set processingServerChanges(value:Boolean):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.



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

restoreCommittedUnsentBatchesOnFault

property 
public var restoreCommittedUnsentBatchesOnFault:Boolean = false

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

When the client receives an error processing a message, setting this property to true causes it to "uncommit" any batches which you've committed but have not yet been sent to the server. If you set the commitQueueMode property to ONE_AT_A_TIME and set this property to true, you can only deal with one batches errors at a time. Otherwise, it is possible to receive faults from a series of faults which can make resolving them a bit more complicated.

The default value is false.

saveCacheMinIntervalMillis

property 
public var saveCacheMinIntervalMillis:int = 0

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

This time interval can be set to reduce the frequency of how often the cache is saved. When the autoSaveCache property is true, LiveCycle Data Services saves the cache after each change. If you have a reasonable large cache, this can be expensive so you might want to reduce the frequency in which the cache is saved. If you set this property to 1000 milliseconds, the cache is saved no more than once per second.

The default value is 0.

throwErrorOnIDChange

property 
public var throwErrorOnIDChange:Boolean = true

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

A flag you can set to false to restore the LiveCycle Data Services 2.6 behavior of logging an error but not throwing an error when the UID property is changed.

The default value is true.

uncommittedBatches

property 
uncommittedBatches:ArrayCollection  [read-only]

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

The list of MessageBatches which are currently uncommitted. To preserve data integrity, in general the order of operations should not be altered so this list is read-only. You create a new batch by calling the createBatch() method. This method adds a new batch to the end of the uncommittedBatches list and sets currentBatch to be the last element in that list.

These properties are bindable so you can watch for the commitRequired flag in a particular batch to see if it has changes, or bind against the items property to get the list of MessageCacheItems waiting to be committed as part of that batch.

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 uncommittedBatches():ArrayCollection
Constructor Detail

DataStore

()Constructor
public function DataStore(destination:String, useTransactions:Boolean, adapter:DataServiceAdapter = null)

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

Normally, a DataStore is created automatically for you but you can create your own DataStore and assign it to the dataStore property of a DataService. To do this, you must ensure all data services that share the same data store use the same channel set and have the same value of the use-transactions configuration setting. Use this constructor to create a DataStore where the destination parameter contains the destination of one of the DataServices using this data store. This is just used to look up the channel set. You also should provide the value for the use-transactions flag for this data store.

Parameters
destination:String — A destination.
 
useTransactions:Booleantrue to use transactions.
 
adapter:DataServiceAdapter (default = null) — The adapter.
Method Detail

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 collections and items managed by this DataStore. 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.

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.

createBatch

()method 
public function createBatch(itemsOrCollection:Array = null, cascadeCommit:Boolean = false, properties:Object = null):MessageBatch

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

Takes any changes specified by this operation, creates a new MessageBatch and puts that batch into the uncommittedBatches list. If itemsOrCollection=null, the entire set of messages in the currentBatch are put into the new batch and a new batch is created as the currentBatch. You call this method when you want to partition a set of changes to mark a block of work that can be committed or reverted as a unit. For example, if you create a parent object and create a child which is associated with that parent, I might then call 'createBatch()' to put both of these changes into a group. If you do this twice, you'd have two batches each creating one parent and one child. You can then commit each group of changes independently as long as they are committed in the order in which the batches were created. You also could revert the most recent batch and it would leave the first batch unchanged. A simple multi-level"undo" system can be implemented this way simply by calling createBatch(null) after each operation.

You can mark a batch with a set of user-defined properties with the MessageBatch.properties property (or the properties argument to this method). This information gets saved and restored with the batch when using the offline feature and can be used to identify the batch on the client. Values placed in here must be serializable (i.e. Objects or classes with [RemoteClass]).

If you supply a value for the itemsOrCollection parameter, a new batch is created which just has the changes for the item or collection of items. If you set cascadeCommit to true, any changes for associated items are also included in the set of messages split out into the new batch.

Parameters

itemsOrCollection:Array (default = null) — may be either an array of items or an array of managed collections. If the former, change messages for each of the items are split out into the new batch. If the latter, changes for each each item in each of the collections are split out into the new batch. If null, the entire set of messages in the currentBatch are put into the new batch and a new batch is created as the currentBatch.
 
cascadeCommit:Boolean (default = false) — when true, any changes for associated items are also included in the set of messages split out into the new batch.
 
properties:Object (default = null) — user-defined proeprties to mark the batch.

Returns
MessageBatch

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

Forces all data services using this data store to be disconnected.

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.

logout

()method 
public function logout():void

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

Log the user out from the current destination. Calling this method will log out all associated DataService instances.

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 can detect conflicts.

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

Refetch all data managed on the client.

Returns
mx.rpc:AsyncToken

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

Release all data managed on the client. This will free up the item and query caches on the client for all data as well as unsubscribing from any auto-sync'd data on the server.

Parameters

clear:Boolean (default = true) — 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) — 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.

revertChanges

()method 
public function revertChanges():Boolean

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

Reverts all pending (uncommitted) changes for all DataServices managed by this DataStore.

Returns
Boolean — true if any changes were reverted.

revertChangesForCollection

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

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

Reverts all pending (uncommitted) changes for any items in the specified managed collection.

Parameters

collection:ListCollectionView

Returns
Boolean — true if any changes were reverted

setCredentials

()method 
public function setCredentials(username:String, password:String):void

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

Set the credentials for this DataStore destination.

Parameters

username:String — The username for the destination
 
password:String — The password for the destination

setRemoteCredentials

()method 
public function setRemoteCredentials(username:String, password:String):void

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

Set the credentials for the 3rd party of this DataStore destination.

Parameters

username:String — The username for the destination
 
password:String — The password for the destination

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

Dispatched when a conflict is detected between either pending changes on this client and changes submitted by another client, or when changes submitted by this client result detect a conflict error at the remote destination. The DataStore dispatches conflict events for all destinations which share the DataStore, or you can listen for conflict events for a specific type on a DataService. Use the DataStore when you have an object with associations as in that case, you may need to resolve conflicts in a specific order to maintain integrity of those associations.

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.rpc.events.FaultEvent
property FaultEvent.type = mx.rpc.events.FaultEvent.FAULT

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

The FaultEvent.FAULT event is dispatched when the commit call returns an error.

The FAULT event type.

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.
faultThe Fault object that contains the details of what caused this event.
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.
tokenThe token that represents the call to the method. Used in the asynchronous completion token pattern.

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 the commit call successfully returns.

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

CQ_AUTO

Constant
public static const CQ_AUTO:int = 1

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

Specifies to check for simple dependencies between any outstanding batches and the next batch to commit.

CQ_NOWAIT

Constant 
public static const CQ_NOWAIT:int = 3

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

Specifies to send the second batch immediately, not checking for dependencies.

CQ_ONE_AT_A_TIME

Constant 
public static const CQ_ONE_AT_A_TIME:int = 0

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

Specifies to wait for a previous batch to complete before committing a new batch.