sqlTransactionOverlay is a transparent overlay. You must instantiate an instance of the overlay from its prototype, this will create a new instance within your application space.
The mod-db:sqlTransactionOverlay prototype has the following initialisation parameters:
Connection pool that is going to be transacted
A nested space definition which the overlay will delegate all requests in to.
Here is an auto-generated example of how to instantiate an instance of sqlTransactionOverlay:
To use sqlTransactionOverlay transparent overlay you must import the module urn:org:netkernel:mod:db:
Multiple SQL operations can be performed within a transaction if you use the sqlBatch accessor. However if you wish to transactionally perform two or more SQL updates separately, possibly interspersed with business logic, then you may use the sqlTransactionOverlay.
The transaction overlay is used to wrap the space in which your transactional active:sqlXXXX will be made. It is entirely open what services you implement in this space. All sql statements that you make in this space will occur within a managed transaction.
The architectural pattern for deploying the transaction overlay is shown below...
The essential requirement is that the overlay is provided with the resource identifier of the connection pool resource as its configuration parameter - for illustration lets call this "res:/RDBMSConfig".
When a request is made to your wrapped transactional process, inside the wrapped space, the following steps are taken...
Finally your service completes and returns a response. The transaction overlay intercepts the service's response, if the service was successful then the transaction is committed. If the service, or any sub-request within the space, throws an exception the sqlTransactionOverlay issues a rollback on the database transaction, and re-throws the exception to the original requestor of the service.
You must instantiate an instance of the transaction overlay within the data layer of your application. The connection pool must be defined outside this overlay. Also any non-transactional processes must be outside this overlay. Inside the overlay you must place all active:sqlXXXX processes which need to be transactional. Also you must import mod:db inside the overlay:
The transaction overlay transparently exposes all services contained within it's wrapped space. When any of these services are requested the request passes through the overlay. The overlay creates a transaction around the declared connection pool. (defined with the configuration parameter) This causes any internal active:sqlXXXX services that use the declared connection pool to operate within a single transaction.
When the service completes normally the transaction is committed. However if the service completes abnormally by throwing an exception the overlay will cause the transaction to rollback before the requestor of the service receives the exception response.