View comments | RSS feed

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

void	addItemToFill(String destination, List fillParameters, int position, Object item) Adds the supplied item to the fill.
void	addItemWithIdToFill(String destination, List fillParameters, int position, Map itemIdentity) This method is like addItemToFill but takes a Map with just the id properties to identify the item.
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.
Map	getProducerDefaultHeaders(String destination)
Object[]	getProducerSubtopics(String destination)
boolean	getSendMessagesToPeers()
UserTransaction	getUserTransaction() Returns the user transaction associated with this data service transaction.
boolean	isRefill()
boolean	isRemoveCommiter()
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	removeItemFromFill(String destination, List fillParameters, int position, Object item) Like addItemToFill but removes the item from the collection instead.
void	removeItemWithIdFromFill(String destination, List fillParameters, int position, Map itemIdentity) Like addItemWithIdToFill but removes the item from the filled collection instead.
void	rollback() Rollsback this transaction.
void	setProducerDefaultHeaders(String destination, Map headers) When using manual message routing on clients, clients can subscribe to changes using a selector expression which involves values in message headers.
void	setProducerSubtopics(String destination, Object[] ps) When using manual message routing on clients, clients can subscribe to changes published to certain subtopics.
void	setRemoveCommiter(boolean removeCommiter)
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

equals, 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 message for any fills whose membership has 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 for this destination 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).

addItemToFill

public void addItemToFill(String destination,
                          List fillParameters,
                          int position,
                          Object item)

Adds the supplied item to the fill. You call this method when you want to explicitly add an item to a single filled collection which is managed by one or more clients. This change will be routed to any clients which have executed fill with the same parameter values you use here with the autoSyncEnabled flag set to true. If you are not using autoSyncEnabled, you can still route changes to clients by using the manual sync feature. In that case, clients subscribe to a set of subtopics or use a selector expression. You would set the ProducerSubtopics property and/or DefaultHeaders property on this transaction, then call this method. Any consumers which have a subscription which matches the subtopics and headers will receive a change to update their filled collection to include this item.

Parameters:

destination - the destination the client used to execute the fill

fillParameters - a set of fill parameters which equal the values used by the client (note: hashCode and equals must be well defined on each class you use as fill parameters)

position - the desired position of the new item in the list

item - an object with at least populated id properties. This item should already exist and should be fetchable via the getItem method on the assembler for this destination in case the client needs to fetch it.

removeItemFromFill

public void removeItemFromFill(String destination,
                               List fillParameters,
                               int position,
                               Object item)

Like addItemToFill but removes the item from the collection instead. You provide an expected position for this item but the item will be removed from the collection even if it is not at that position on the client.

Parameters:

destination - the destination the client used to execute the fill

fillParameters - a set of fill parameters which equal the values used by the client (note: hashCode and equals must be well defined on each class you use as fill parameters)

position - the expected position of the item in the list to remove. The item will be removed even if it is not found at this position.

item - an object with at least populated id properties.

addItemWithIdToFill

public void addItemWithIdToFill(String destination,
                                List fillParameters,
                                int position,
                                Map itemIdentity)

This method is like addItemToFill but takes a Map with just the id properties to identify the item.

Parameters:

destination - the destination the client used to execute the fill

fillParameters - a set of fill parameters which equal the values used by the client (note: hashCode and equals must be well defined on each class you use as fill parameters)

position - the expected position of the item in the list to remove. The item will be removed even if it is not found at this position.

itemIdentity - a Map with a key/value for each id property for items in this destination. The id property classes should implement equals and hashCode properly.

removeItemWithIdFromFill

public void removeItemWithIdFromFill(String destination,
                                     List fillParameters,
                                     int position,
                                     Map itemIdentity)

Like addItemWithIdToFill but removes the item from the filled collection instead.

Parameters:

destination - the destination the client used to execute the fill

fillParameters - a set of fill parameters which equal the values used by the client (note: hashCode and equals must be well defined on each class you use as fill parameters)

position - the expected position of the item in the list to remove. The item will be removed even if it is not found at this position.

itemIdentity - a Map with a key/value for each id property for items in this destination. The id property classes should implement equals and hashCode properly.

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()

setProducerSubtopics

public void setProducerSubtopics(String destination,
                                 Object[] ps)

When using manual message routing on clients, clients can subscribe to changes published to certain subtopics. In this case, you can use set the subtopics for a specific destination. This controls which clients receive which changes for that destination. Any clients subscribed to any of the subtopics in this list will receive changes queued. This value is consulted at the time the createItem, updateItem, etc. method is invoked for a matching destination. You should supply an array of String objects defining the subtopics. For efficiency, this array is not copied but instead is inserted directly into the message. If you need to modify the array, make a copy before providing it to this method.

Parameters:

destination - Any messages sent to this destination in this transaction will be routed to these subtopics.

ps - the array of topic names (usually strings).

getProducerSubtopics

public Object[] getProducerSubtopics(String destination)

setProducerDefaultHeaders

public void setProducerDefaultHeaders(String destination,
                                      Map headers)

When using manual message routing on clients, clients can subscribe to changes using a selector expression which involves values in message headers. You can use this property to control which clients receive which changes. Any clients whose subscription has a selector expression which matches this headers in the list will receive messages (as long as the subtopic, if any also matches). The values in this Map do not override any values already in the message (i.e. any internal message headers used by the system). The values are copied out of this map into the headers of this message so you do not need to make your own copy of these headers.

getProducerDefaultHeaders

public Map getProducerDefaultHeaders(String destination)

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()

isRemoveCommiter

public boolean isRemoveCommiter()

setRemoveCommiter

public void setRemoveCommiter(boolean removeCommiter)