com.smartgwt.client.docs

Interface TransactionChaining

public interface TransactionChaining

Transaction Chaining

Transaction Chaining allows queues of DSRequests to be "chained" together, such that later DSRequests in the queue can use the results of previous requests in the queue. This allows you to declaratively handle various situations where information only becomes available during the processing of a queue.

Transaction Chaining is only available with Power Edition licenses or better. See the Editions & Pricing page for details.

As an example of Transaction Chaining, consider an application that needs to do a master-detail add, which involves saving a new Record representing a sales order to an order DataSource, and also saving several related Records representing individual items in the order to an orderItem DataSource. The Records for the individual orderItems need to set up foreign keys referencing the primary key assigned to the Record for the order, but the primary key of the order record is assigned only when the Record is inserted into the database; it cannot be known up-front.

You could resolve this programmatically - for example, you could use DMIs to store and retrieve the PK value using servletRequest attributes - but Transaction Chaining gives you an elegant, declarative, code-free alternative, giving you a way to declare that the foreignKey value for the orderItem records should use the primary key value resulting from the creation of the order record earlier in the same queue.

As another example, consider an application that allows a user to submit a free-form question which must be persisted to the database like a normal update, but which should initially show the user a list of previously-provided answers that appear to be relevant. The operation that handles the add of the question categorizes it by analyzing the text, and the category is added to the record inserted into the database, and thus to the record returned in the response. Now, via transaction chaining, a "fetch" operation later in the queue can pick up the newly assigned category and use it in criteria to fetch the list of related answers.

Transaction Chaining is implemented by specifying DSRequestModifiers in OperationBinding.values and OperationBinding.criteria. These two properties provide a general means of declaratively modifying DSRequests server-side, and transaction chaining is only one of their uses. They can also be used, for example, to implement security rules, by adding the currently-authorized user to the criteria of all fetch requests.

Specifically for transaction chaining, you specify criteria and/or values entries on the operationBinding where the value property references the special $responseData Velocity context variable - see the "value" link for more details. Alternatively, you can use the RPCManager APIs getFirstResponse() and getLastResponse() to get access to the same information, either programmatically from DMI or custom DataSource Java code, or in Velocity expressions via the $rpc context variable.

See Also:

DSRequestModifier, com.smartgwt.client.docs.serverds.DSRequestModifier#getValue, com.smartgwt.client.docs.serverds.DSRequestModifier#getStart, com.smartgwt.client.docs.serverds.DSRequestModifier#getEnd, OperationBinding.criteria, OperationBinding.values