DataManager  - AS3 LiveCycle Data Services

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

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

The default value is true for DataService instances, which are data managers used with the server-side Data Management Service.

The default value is false for RPCDataManager instances, which are data managers that provide client-side data management functionality to RPC service components such as RemoteObject, HTTPMultiService, and WebService.

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.

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.

You can store the local cache of data and changes to disk. When the autoSaveCache property is true, each time a change is made or a remote request is returned, that data is 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 is dispatched or a Fault is thrown.

Setting this value to false (the default) does 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.

Related API Elements

When true, fill(), createItem() and getItem() requests return items that 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 for a mix of collections retrieved with autoSyncEnabled and collections filled without autoSyncEnabled, any items appearing in both collections still receive update events.

The default value is true.

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 an empty string is considered unset. Requests for data by methods like fill() and getItem() 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.

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.

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

Contains a Conflicts object, which is an ArrayList of Conflict instances.

Conflicts must be resolved before you call the commit() method. 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.

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.

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

By default, a DataManager instance shares the same DataStore with other DataManager instances if they have managed association properties and share the same set of channels. If you are sharing DataStores, a commit call on one DataManager commits changes for all DataManagers 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.

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 lets you use code that uses a managed collection and an unmanaged collection in the same way. However, at other times, 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 that are associations. It only affects collections that were used with the fill() method.

The default value is true.

This flag determines whether the application should query against the local store when it is not connected. By default when the offline adapter is configured to support dynamic query execution, invoking fill() will not query the local store when the application is not connected. If fallBackToLocalFill is set to true, then the local store queried as well when the application is disconnected.

Associations optionally list property change events on properties of the associated instances. You can set this on the association with the hierarchical-events configuration 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 value is false. For objects 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 causes 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.

Indicates if changes to managed collections should be ignored instead of being communicated to the server on a commit.

The default value is false.

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 DataManager from association properties of other items.

Indicates whether the metadata associated with this DataManager instance is initialized.

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

Provides access to the ManualSyncConfiguration instance for each DataManager instance. The ManualSyncConfiguration class lets you subscribe to changes made by other clients or on the server and it lets you control how your changes are published to other clients that subscribe using this interface.

Determines the maximum number of messages per second the DataManager instance can 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.

Indicates whether 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.

Returns an object of type mx.data.DataServiceOfflineAdapter. The Offline Adapter controls the implementation of how objects are persisted to the local store(SQLLite/LSO).

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

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

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

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.

When the property is true, after the fill operation completes, a RESET event is sent. When this property is false, just incremental ADD/REMOVE events are sent 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.

Controls the number of times a disconnected DataManager instance attempts to resubscribe to its destination. The default -1 means to continually resubscribe until the client is able to reconnect.

The default value is -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.

Indicates if the DataManager instance 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.

Set this property to false if you want to suppress 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 for which the 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.

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.

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

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

Parameters

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

Parameters

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

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 to 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 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

Indicates if there are pending changes for this particular object. Allows for granular enablement on the UI. (see commitRequired for bindable property for notification).

Parameters

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.

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>
      

Parameters

Related API Elements

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

Parameters

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

Parameters

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

Executes a query with the provided name and arguments. You typically use this method with an RPCDataManager instance 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 DataManager instance by calling the release() method.

Call the refreshCollection() method to refresh the contents of any collections returned by this method.

Parameters

Fills the specified ListCollectionView (collection) instance based on the associated fill method of the destination. For example, for a LiveCycle Data Services destination that uses a Hibernate assembler, the first parameter of the fill() method is the collection to fill, the second parameter is the Hibernate query to execute, and any other parameters are Hibernate query parameters. The same format applies to the fill() methods used in service-wrapper classes for model-driven development.

The following example shows a fill() method for a destination that uses a Hibernate assembler. The assembler has a query named getByDescription that takes a query parameter named description:

     ProductService.fill(ac, "getByDescription", description);
     

For a LiveCycle Data Services destination that uses the fill-method approach in which you declare fill methods in XML elements in the destination configuration, if the following <fill-method> elements are in the destination configuration:

            <fill-method>
                <name>loadPersons</name>
                <params>java.lang.String,java.lang.String</params>
            </fill-method>
     
            <fill-method>
                <name>loadPersons</name>
                <security-constraint ref="sample-users" />
            </fill-method>
      

Parameters

Fills the specified ListCollectionView (collection) instance 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.

Parameters

Executes a query that returns a single item.

Parameters

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

Parameters

Fills the specified ListCollectionView (collection) instance with CacheDataDescriptor instances. If no argument is specified, all associated CacheDataDescriptor instances for cached data under this service are returned.

Parameters

Fills the specified ListCollectionView (collection) instance with all cache identifiers previously used in the application.

Parameters

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 instance. 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 instance, 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 instance, you can call the releaseItem() method on the DataManager with the item itself.

Parameters

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 call to the getItem method, this call does not make a request to the server and does not add an additional reference to the item.

Parameters

Returns page information for the specified collection.

Parameters

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

Forces initialization of the DataStore.

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

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

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

Parameters

Fills the specified ListCollectionView based on the associated <fill-method> elements based on the data from the local store. It will invoke the offlineAdapter.executeOfflineQuery() API to query the data and will not attempt to query the remote destination even if the application is connected. This is ideally used where the data is synced to the client and local queries are executed against that.

Parameters

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 DataManager instances that share this DataStore instance.

Refreshes all data managed by this DataManager instance. Fills, get item requests, and page requests are made to the server to re-fetch all of the managed items. Call the DataStore.refresh() method to also refresh all associated items for lazy = true associations.

Refreshes a 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

Releases all managed collections and items for the DataManager instance.

Parameters

Related API Elements

Releases any item within the specified collection from management by this DataManager instance. 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

Releases the specified item from management by this DataManager instance. If you hold onto an ItemReference instance, you should call the releaseItem() method on the ItemReference instance 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

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

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

Reverts any uncommitted changes to the specified item. Or if no item is supplied, it reverts 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 the dataStore.revertChanges() method.

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 returns false. If no item is supplied and there are no changes this method returns false. Otherwise, it returns true.

Parameters

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

Parameters

This method saves the current state of the DataManager instance's cache. The cache includes in-memory items and changes made to those items that have not been sent to the remote destination.

Parameters

Related API Elements

         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
      

Triggers an update for the specified item. If you call this with the managed instance it commits any changes you have made to that item and returns 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 the autoCommit is set to true, the changes for this item are committed immediately. If it is set to false, the changes are queued until the commit() method is called.

Parameters

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 properties of the event object have the following values:

The DataManagerFaultEvent.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 properties of the event object have the following values:

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 value of this constant is "message".

The properties of the event object have the following values:

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

• commitRequired
• mergeRequired
• connected

The properties of the event object have the following values:

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 properties of the event object have the following values: