Pushing data changes from the server to clients

You use the flex.data.DataServiceTransaction class to push server-side data changes to clients. This class is documented in the public LiveCycle Data Services ES Javadoc API documentation. An instance of the DataServiceTransaction class is created for each operation that modifies the state of objects that the Data Management Service manages. You can use this object from server-side code to push changes to managed data stored on clients that have the autoSyncEnabled property of your DataService component set to true.

If you add changes from within a sync method, the Data Management Service creates an instance of the DataServiceTransaction class, so you can call its static getCurrentDataServiceTransaction() method and then call the updateItem(), deleteItem(), or createItem() methods to trigger additional changes. You should call these methods to apply changes you have persisted or will be persisting in this transaction. If the current transaction is rolled back, these changes are not pushed to clients.

To roll back a transaction, you mark the javax.transaction.UserTransaction instance as rolled back as you would in a normal J2EE application, or you can call the setRollbackOnly() method on the DataServiceTransaction.

The DataServiceTransaction class provides access to the current transaction in a thread local state, and holds messages to be pushed to clients when the transaction completes. You also use this class to register for synchronization events before and after completion of the transaction.

Each DataServiceTransaction instance is stored in thread-local state and it is assumed that it is only operated on one thread at a time. It is not thread safe.

If you use the DataServiceTransaction class from within a sync, update, create, or delete method of your assembler, do not use this class to indicate changes made to items that are already in the midst of being changed in this transaction. Doing so queues an additional change to that object instead of modifying the currently active one, which can create a conflict. Instead, you update the NewVersion instance with your changed property values and add any newly changed property values to the list of changed properties sent to you. For example, if after every update made to an instance, you want to change the versionId of that instance, you add the versionId to the list of changes and also update the versionId value in your newVersion instance.

If you are using the ChangeObject interface, you call the addChangedPropertyName() method to add the versionId property. If you are using theupdateItem() method, you just add that property to the list provided to your updateItem() method.

Refreshing fills from server code

The DataServiceTransaction.refreshFill() method lets you manually refresh a fill or matching set of fills from server code either as part of your assembler's sync method or from other server-side code. You specify a list of fill parameters that are used to create a matching list of fills that are currently being cached by active clients. This list can be null, which means that all fills on that destination match. If the list is non-null, therefreshFill() matches fills made by clients with the same number of parameters if all of the slots match based on the rules in the following table:

Value

Rule

Null value

Matches that slot unconditionally.

Class value

Matches a parameter in the slot of that type.

Any other value

Matches fill parameters by using the equals method.

There are two variants of the refreshFill() method. The simpler variant takes a destination and fill parameters as its two parameters. The other variant takes an additional parameter that specifies a PropertySpecifier instance. This variant compares the properties of all of the items in the collection. It could use the item cache to avoid updating all items if the item cache is enabled. It compares the properties of all items in the new version of the fill and sends update messages for any properties that have changed. If the item cache is disabled, this refreshFill() method sends update item events for all items in the collection just in case they have changed.

The DataServiceTransaction class also has addItemToFill() and removeItemFromFill() methods that you can use to make an explicit change to a filled collection actively managed by other clients. Use of these methods generates an update collection message in the DataServiceTransaction that is sent to the committing client, any clients that have called fill on that collection, and any clients that have subscribed to this change using the manual sync mode properties set in the DataServiceTransaction. This is an efficient way to modify a managed collection on clients without re-executing the entire query.

Note: When you compile code that uses LiveCycle Data Services ES Java APIs, you must include the messaging.jar and flex-messaging-common.jar files in your classpath.

http://livedocs.adobe.com/livecycle/8.2/programLC/programmer/lcds/help.html?content=dms_advanced_3.html