WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

Endpoint
Name:sqlTransactionOverlay
Description:
Id:mod-db:sqlTransactionOverlay
Category:transparent overlay

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.

Parameters

The mod-db:sqlTransactionOverlay prototype has the following initialisation parameters:

NameRulesTypingDefaultDescription
configurationOptionalStringres:/etc/ConfigRDBMS.xml
Connection pool that is going to be transacted
spaceMandatorySpace(none)
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:

<overlay>
  <prototype>mod-db:sqlTransactionOverlay</prototype>
  <space>
    < !--wrapped space...-->
  </space>
</overlay>
Import Requirements

To use sqlTransactionOverlay transparent overlay you must import the module urn:org:netkernel:mod:db:

<import>
  <uri>urn:org:netkernel:mod:db</uri>
</import>

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.

Overview

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...

  1. The sqlTransactionOverlay intercepts the request.
  2. It issues a second request for a transactional JDBC connection from the res:/RDBMSConfig connection resource specified in its configuration.
  3. It constructs a transient injected space and inserts this into the request scope of the intercepted request for your service (the small inserted cloud in the diagram).
  4. The transacted connection is placed as resource in this injected space with the same identifier res:/RDBMSConfig as the connection pool resource - effectively masking the external configuration by the transient local transacted resource.
  5. Your service is then invoked with the request that was intercepted.
  6. Any request you make to an active:sqlXXXX service should now specify the configuration argument and this must be same the identifier as was used to configure the transaction overlay (see for example active:sqlUpdate).It follows that when your request to the active:sqlXXXX tool is made, it will use the transacted connection obtained from the inserted transient transaction space.

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.

Basic Configuration Architecture

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:

<rootspace name="Data Layer">
  < !-- define the connection pool configuration -->
  <fileset>
    <regex>res:/etc/ConfigRDBMS.xml</regex>
  </fileset>
  < !-- import mod db -->
  <import>
    <uri>urn:org:netkernel:mod:db</uri>
  </import>
  < !-- instantiate transaction overlay -->
  <overlay>
    <prototype>mod-db:sqlTransactionOverlay</prototype>
    <configuration>res:/etc/ConfigRDBMS.xml</configuration>
    <space>
      < !-- transactional service -->
      <accessor>
        <grammar>
          <active>
            <identifier>active:transactionService</identifier>
            <argument name="some-argument" />
          </active>
        </grammar>
        <class>...</class>
      </accessor>
      < !-- important! - declare import to mod db inside overlay -->
      <import>
        <uri>urn:org:netkernel:mod:db</uri>
      </import>
    </space>
  </overlay>
</rootspace>

Mode of operation

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.