flex.data
Class DataServiceTransaction

java.lang.Object
  flex.data.DataServiceTransaction

public class DataServiceTransaction

extends Object

A DataServiceTransaction instance is created for each operation that modifies the state of objects managed by Data Management Services. You can use this class from server-side code to push changes to managed data stored on clients as long as they have the autoSyncEnabled property set to true.

If you want to add additional changes from within your sync method, createItem, updateItem, or deleteItem methods there is already an instance of the DataServiceTransaction created so you just need to call the static getCurrentDataServiceTransaction method and then call the updateItem, deleteItem, and createItem methods to trigger additional changes which are sent along with the original batch of changes only if the entire batch completes successfully. If the current transaction is rolled back, these changes will not be pushed to clients.

If you are in code in the same web application as Data Management Services, but are not in the midst of an existing assembler operation you begin a new DataServiceTransaction using the static begin method. This returns a DataServiceTransaction object. You can use the updateItem, createItem, deleteItem and refreshFill methods to queue up a batch of changes. When you call commit, those changes are pushed out to clients.

If you call begin with the useJTA parameter of true, a JTA UserTransaction is started in conjunction with the DataServiceTransaction. You can retrieve the UserTransaction via the getUserTransaction method. When you call commit on the DataServiceTransaction in this case, the UserTransaction is committed first. Only if that succeeds is the batch of messages pushed to the client.

You also use this class to register for synchronizations events before and after completion of the transaction. This is useful in some cases when implementing Assemblers because you need to know when the transaction is committed.

Each DataServiceTransaction is stored in thread local state and so it is assumed that it will only be operated on by one thread at a time. It is not threadsafe.

To roll back a transaction, you can either call setRollbackOnly or you can mark the UserTransaction object as rolled back as you would in a normal J2EE application.

Field Summary

static String	LOG_CATEGORY
static String	USER_TX_JNDI_NAME

Method Summary

static DataServiceTransaction	begin(boolean useJTA) This version of the begin method uses the default MessageBroker.
static DataServiceTransaction	begin(String serverId, boolean useJTA) Starts a DataServiceTransaction that you can use to send changes to clients.
void	commit() Clients can call this method to commit the transaction.
void	createItem(String destination, Object item) You use this method to indicate to to the Data Management Service that a new item has been created.
void	deleteItem(String destination, Object item) Sends a deleteItem method to the clients that are sync'd to sequences that contain this item.
void	deleteItemWithId(String destination, Map identity) This version of the deleteItem method does not provide for conflict detection if the item has been modified before the delete occurs; it is deleted.
Map	getAttributeMap() A map of values scoped to the FDMS transaction.
static DataServiceTransaction	getCurrentDataServiceTransaction() Returns the current DataServiceTransaction if one has been associated with the current thread.
static UserTransaction	getCurrentUserTransaction() If the current DataServiceTransaction was started with JTA mode, you can access the UserTransaction from the DataServiceTransaction.
boolean	getSendMessagesToPeers()
UserTransaction	getUserTransaction() Returns the user transaction associated with this data service transaction.
boolean	isRefill()
void	refreshFill(String destination, List fillParameters) For a matching list of auto-sync'd fills, re-executes the fill method, compares the identities of the items returned to the those returned the last time we executed it with autoSyncEnabled=true.
void	registerSynchronization(Synchronization synchronization) Registers a synchronization listener with this transaction.
void	rollback() Rollsback this transaction.
void	setRollbackOnly() Marks the DataServiceTransaction so we rollback the transaction instead of committing it when it completes.
void	setSendMessagesToPeers(boolean stp) When you call the updateItem, createItem, and the deleteItem methods, normally these messages are sent to other peers in the cluster so they are distributed by those nodes to clients connected to them.
void	updateItem(String destination, Object newVersion, Object previousVersion, String[] changes) Send an update event to clients subscribed to this message.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

USER_TX_JNDI_NAME

public static final String USER_TX_JNDI_NAME

See Also:

Constant Field Values

LOG_CATEGORY

public static final String LOG_CATEGORY

See Also:

Constant Field Values

Method Detail

getCurrentDataServiceTransaction

public static DataServiceTransaction getCurrentDataServiceTransaction()

Returns the current DataServiceTransaction if one has been associated with the current thread. When you begin a DataServiceTransaction, it is automatically associated with your thread. If you want to add changes while in an adapter/assembler's sync method, you can use this method to get a reference to the existing DataServiceTransaction. In this case, you can call updateItem, createItem, deleteItem, and so forth, but you do not call commit or rollback yourself as this is done by the data services code when the sync method completes.

Returns:

the current DataServiceTransaction or null if there is no transaction currently associated with the current thread.

getCurrentUserTransaction

public static UserTransaction getCurrentUserTransaction()

If the current DataServiceTransaction was started with JTA mode, you can access the UserTransaction from the DataServiceTransaction.

Returns:

null if there is no JTA UserTransaction currently associated with the current DataServiceTransaction or if there is no DataServiceTransaction associated with the current thread.

begin

public static DataServiceTransaction begin(String serverId,
                                           boolean useJTA)

Starts a DataServiceTransaction that you can use to send changes to clients. Use this method when you want to push changes to clients when you are not in the midst of an adapter/assembler's method. If you are being called from within the context of an assembler method (or if you are not sure), you should call the getCurrentDataServiceTransaction method. If that returns null, you can then use this method to start one. If you call this method, you must either call commit or rollback to complete the transaction. You should make sure that this commit or rollback occurs no matter what else happens - it almost always must be in a finally block in your code. If you are in an assembler method, you should not commit or rollback the transaction as that happens in the data services code when it completes. Instead, if you want to rollback the transaction, call setRollbackOnly.

It is not legal to call this method while an existing transaction is in place (an error is thrown).

Parameters:

serverId - Identifies the MessageBroker that created the Data Management Services destination you want to manipulate using this api. Typically there is only one MessageBroker for each web application and in this case, you can pass in null. If you have more than one MessageBroker in your web application, provide the value for the messageBrokerId used to configure your MessageBrokerServlet in the web application's web.xml file as the serverId for this parameter.

useJTA - Specify this value of true if you want to start a JTA UserTransaction in addition to the DataServiceTransaction. Both will be committed/rolled back in tandem.

Returns:

the DataServiceTransaction started.

Throws:

DataServiceException - if either the serverId is invalid or if there is already a DataServiceTransaction actively associated with the current thread.

begin

public static DataServiceTransaction begin(boolean useJTA)

This version of the begin method uses the default MessageBroker. It is rare that you'd have more than one MessageBroker instance in your web application but in those cases in which you do, you can use the serverId to be sure you get the proper DataService.

See Also:

DataServiceTransaction.begin(String,boolean)

getUserTransaction

public UserTransaction getUserTransaction()

Returns the user transaction associated with this data service transaction. If this DataServiceTransaction was not created with JTA enabled, this returns null.

Returns:

UserTransaction the current JTA UserTransaction (or null if one is not associated with this DataServiceTransaction).

registerSynchronization

public void registerSynchronization(Synchronization synchronization)

Registers a synchronization listener with this transaction. This synchronization is called when you commit or rollback the DataServiceTransaction.

Parameters:

synchronization - Your instance that implements the javax.transaction.Synchronization interface.

setRollbackOnly

public void setRollbackOnly()

Marks the DataServiceTransaction so we rollback the transaction instead of committing it when it completes. If this DataServiceTransaction is using JTA for transactions, this method marks the JTA transaction for rollback only.

commit

public void commit()

Clients can call this method to commit the transaction. If this transaction was begun using JTA, the UserTransaction is committed. You should only use this method if you used the begin method to create the DataServiceTransaction. Otherwise, Data Management Services will commit or rollback the transaction as necessary.

rollback

public void rollback()

Rollsback this transaction. If this transaction was created with useJTA as true, the JTA transaction is rolled back. Otherwise, this transaction is just discarded and any changes applied are discarded. You should only use this method if you created the DataServiceTransaction with the begin method.

updateItem

public void updateItem(String destination,
                       Object newVersion,
                       Object previousVersion,
                       String[] changes)

Send an update event to clients subscribed to this message. Note that this method does not send the change to the adapter/assembler - it assumes that the changes have already been applied or are being applied in this JTA transaction. It only updates the clients with the new version of this data.

You must supply a destination parameter and a new version of the object. If you supply a non-null previous version, this object is used to detect conflicts on the client in case the client's version of the data does not match the previous version. You may also supply a list of property names that have changed as a hint to the client to indicate which properties should be checked for conflicts and updated. If you supply null for the changes, all properties on the client are updated. These property names do not accept any kind of dot notation to specify that a property of a property has changed. Only top level property names are allowed.

Parameters:

destination - Name of the Data Management Services destination that is managing the item you want to update.

newVersion - New version of the item to update. The identity of the item is used to determine which item to update.

previousVersion - If not null, this contains a version of the item you intend to update. The client can detect a conflict if its version does not match the previousVersion. If you specify the value as null, a conflict is only detected if the client has pending changes for the item being updated.

changes - Array of property names which are to be updated. You can provide a null value to indicate that all property values may have changed.

createItem

public void createItem(String destination,
                       Object item)

You use this method to indicate to to the Data Management Service that a new item has been created. The Data Management Service goes through all sequences currently being managed by clients and determine whether this item belongs in each sequence. Usually it re-evaluates each fill method to make this determination (though you can control how this is done for each fill method). When it finds a sequence that contains this item, it then sends a create message for this item to each client subscribed for that sequence.

Note that this method does not send a create message to the adapter/assembler for this item. It assumes that your backend database has already been updated with the data or is being updated in this transaction. If this transaction is rolled back, no changes are applied.

Parameters:

destination - Name of the destination that is to be managing this newly created item.

item - New item to create.

deleteItem

public void deleteItem(String destination,
                       Object item)

Sends a deleteItem method to the clients that are sync'd to sequences that contain this item. It does not send a delete message to the adapter/assembler but instead assumes that this item is already have been deleted from the database or is being deleted in this transaction. If you rollback the transaction, this message is also rolled back.

This version of the delete method causes clients to generate a conflict if they have a version of the item that does not match the version of the item specified. You can use the deleteItemWithId method to unconditionally delete an item on the client if you do not have the original version.

Parameters:

destination - Name of the destination containing the item to be deleted.

item - Version of the item to delete. Clients can detect a conflict if this version of the item does not match the version they are currently managing.

deleteItemWithId

public void deleteItemWithId(String destination,
                             Map identity)

This version of the deleteItem method does not provide for conflict detection if the item has been modified before the delete occurs; it is deleted.

Parameters:

destination - Name of the destination containing the item to be deleted.

identity - A java.util.Map containing entries for each of the id properties for this item (the key is the id property name, the value is its value).

refreshFill

public void refreshFill(String destination,
                        List fillParameters)

For a matching list of auto-sync'd fills, re-executes the fill method, compares the identities of the items returned to the those returned the last time we executed it with autoSyncEnabled=true. It builds an update collection events for any fills that have changed. This contains the items that have been added to or removed from the list but does not look for changes made to the properties of those items. This update collection message is sent to clients along with the other messages in this transaction when you commit. If the transaction is rolled back, the fills are not updated.

If you want to update the property values of items, you'll need to use updateItem on the individual items that have changed.

If you provide null for the fill parameters argument, all auto-sync'd fills are refreshed. If you provide a list of fill parameters, we match that list of fill parameters against the list provided by the clients when they executed the fills. If the fill parameters match, that fill is refreshed. The matching algorithm works as follows. If you provide a value for a given fill parameter, the equals method is used on it to compare against the fill parameter value that the client used when it executed the fill. If you provide a null parameter value, it matches that slot for all fills. If you provide a Class, the value of the fill parameter must be an instance of that class.

Parameters:

destination - Destination on which the desired fills were created against.

fillParameters - Fill parameter pattern that defines the fills to be refreshed (see above for details).

setSendMessagesToPeers

public void setSendMessagesToPeers(boolean stp)

When you call the updateItem, createItem, and the deleteItem methods, normally these messages are sent to other peers in the cluster so they are distributed by those nodes to clients connected to them. If your code is arranging to send these updates from each instance in the cluster, set sendMessagesToPeers=false before you call the updateItem, createItem method, and so forth.

Parameters:

stp - True if you want to send these messages to peer servers which will then send these messages to clients connected to them.

getSendMessagesToPeers

public boolean getSendMessagesToPeers()

getAttributeMap

public Map getAttributeMap()

A map of values scoped to the FDMS transaction. Users can store temporary objects that should be shared across the transaction. These values are available for the duration of this DataServiceTransaction.

isRefill

public boolean isRefill()