Web Services Atomic Transaction support in the application server
The Web Services Atomic Transaction (WS-AT) support in the application server provides transactional quality of service to the web services environment. Distributed web services applications, and the resources they use, can take part in distributed global transactions.
- WS-AT is a specific coordination type that defines protocols for atomic transactions. The specifications are:
- Web Services Coordination (WS-COOR) specifies a
CoordinationContext and a Registration service with which participant web services can enlist to
take part in the protocols that are offered by specific coordination types. The specifications are:
- Web Services Coordination Version 1.0
- Web Services Coordination Version 1.1
- Web Services Coordination Version 1.2
The WS-AT support is support for an interoperability protocol that introduces no new programming interfaces for transactional support. Global transaction demarcation is provided by standard enterprise application use of the Java™ Transaction API (JTA) UserTransaction interface. If an application component that is running under a global transaction makes a web services request, a WS-AT CoordinationContext is implicitly propagated to the target web service, but only if the appropriate application deployment descriptors have been set, as described in the topic about configuring transactional deployment attributes.
If the application server is the system hosting the target endpoint for a web services request that contains a WS-AT CoordinationContext, the application server automatically establishes a subordinate JTA transaction in the target runtime environment that becomes the transactional context under which the target web service application runs.
The following figure, shows a transaction context shared between two application servers for a web services request that contains a WS-AT CoordinationContext.
You can configure the policies for the WS-AtomicTransaction protocol. You can configure whether a client propagates, and a server receives, a WS-AT context. To ensure that a client always sends WS-AtomicTransaction context when it makes an outbound service request, you must associate a policy set with the client, where the policy set must include the WS-Transaction policy type, and this policy type must have a WS-AtomicTransaction setting of Mandatory. Alternatively, if you know that the client always invokes remote endpoints that include the WS-AtomicTransaction ATAssertion policy type attribute, you can configure the client to apply the WS-Policy configuration of the provider so that the client adopts the mandatory policy of the provider automatically.
To ensure that any requests that a web services provider receives include a WS-AtomicTransaction context, you must associate a policy set with the provider, where the policy set must include the WS-Transaction policy type, and this policy type must have a WS-AtomicTransaction setting of Mandatory.
To ensure that a client or provider never use WS-AtomicTransaction context, you must associate a policy set with the client or provider, where the policy set includes the WS-Transaction policy type, and this policy type must have a WS-AtomicTransaction setting of Never. You might use this configuration for environments where you do not want web services requests to create a tight coupling between a client and a provider, for example when there are requests between enterprises.
If there is no policy set associated with a client or provider, or the WS-Transaction policy type is not included in the policy set, the default WS-Transaction behavior is used.
WS-AT support restrictions
In this version of the application server, WS-AT contexts cannot be started from a non-recoverable client process.
Application design
WS-AT is a two-phase commit transaction protocol and is suitable for short duration transactions only.
An atomic transaction coordinates resource managers that isolate transactional updates by holding transactional locks on resources. Therefore, it is generally not recommended that WS-AT transactions are distributed across enterprise domains. Inter-enterprise transactions typically require a looser semantic than two-phase commit, and in such scenarios, it can be more appropriate to use a compensating business transaction, for example, as part of a Business Process Execution Language (BPEL) process, or by using Web Services Business Activity (WS-BA).
WS-AT is most appropriate for distributing transaction context across web services that are deployed in a single enterprise. Only request-response message exchange patterns carry transaction context because the originator (application or container) of a transaction must be sure that all business tasks that are run under that transaction have finished before requesting the completion of a transaction. Web services invoked by a one-way request never run under the transaction of the requesting client.
The effect of service faults on WS-AT transactions is similar to the effect of Enterprise JavaBeans (EJB) application exceptions on transactions, as described in the EJB specification. If a service that is running under a requester WS-AT transaction returns a fault, the application server does not automatically mark the transaction rollback-only. The exception handler of the requester chooses whether the transaction can progress and chooses whether to mark the transaction rollback-only. If the requester is running in the application server, the standard JTA or EJB APIs can be used to mark the transaction rollback-only. The service component that generates the fault might, itself, mark the transaction rollback-only before returning the fault. If the implementation of the service component encounters a system exception, it typically allows its container to handle the exception. Application server containers automatically mark any received transaction context rollback-only when handling a system exception that is generated by a service implementation.
Application development
There are no specific development tasks required for web services applications to take advantage of WS-AT.
For JAX-RPC applications, there are some application deployment descriptors that you must set appropriately, as described in the topic about configuring transactional deployment attributes. The JAX-RPC run time supports WS-AT 1.0.
For JAX-WS applications, enable WS-AT support by creating a policy set, adding the WS-Transaction policy type to the policy set, optionally configuring the policy type, and attaching the policy set to the application or client that will be involved in the WS-AT communication. The JAX-WS run time supports WS-AT 1.0, WS-AT 1.1, WS-AT 1.2 and the WS-Policy assertion for WS-AT.
When the JAX-WS runtime receives an inbound request, WS-Transaction 1.0, WS-Transaction 1.1 and WS-Transaction 1.2 specification levels are supported. When an outbound JAX-WS request is sent, only one specification level can be used. If WS-Transaction WS-Policy assertions are available, either from the Web Services Description Language (WSDL) of the target web service, or from the WS-Transaction policy type of the client, the specification level that is applicable to the client and the target web service is used. For example, if the hosting environment of the target web service supports only WS-Transaction 1.0, WS-AT 1.0 is used. If both specification levels are applicable, or if no WS-Transaction WS-Policy assertions are available, the default WS-Transaction specification level that is set in the Transaction service settings is used.
- For a client, if the client does not consider the policy of the provider, the client does not send any WS-AT or Web Services Business Activity (WS-BA) context. This behavior is equivalent to a WS-Transaction policy setting of Never.
- For a client, if the client considers the policy of the provider, the client sends WS-AT or WS-BA context if the policy of the provider includes WS-AT or WS-BA assertions. This behavior is equivalent to a WS-Transaction policy setting of Supports.
- For a server, the server does not receive any WS-AT or WS-BA context. This behavior is equivalent to a WS-Transaction policy configuration setting of Never.
Application developers do not have to explicitly register WS-AT participants. The application server run time takes responsibility for the registration of WS-AT participants, in the same way as the registration of XAResources in the JTA transaction to which the WS-AT transaction is federated. At transaction completion time, all XAResources and WS-AT participants are coordinated atomically by the application server transaction service.
If a JTA transaction is active on the thread when a web services application request is made, the transaction is propagated across on the web services request and established in the target environment. This process is similar to the distribution of transaction context over IIOP, as described in the EJB specification. Any transactional work performed in the target environment becomes part of the same global transaction.
WS-Transaction policy assertions
If you configure the policies for the WS-Transaction protocol for a provider, this configuration affects the assertions that are included in any WSDL that is generated for the web service with which the policy type is associated. The WS-Policy assertion that is used to describe the transactional requirements of a client or provider that uses WS-AtomicTransaction is ATAssertion. If the WS-Transaction policy type has a WS-AtomicTransaction setting of Mandatory or Supports, a policy assertion is included in the WSDL.
The application server can also parse, understand, and apply such assertions that are in WSDL that it parses.
The following example shows WSDL where the WS-AtomicTransaction ATAssertion indicates that an endpoint must be invoked with WS-AT context included in the request message, and that the context can be in WS-Transaction 1.0 or 1.1 format. There are two namespaces and there are two assertions; one for each WS-Transaction specification level, that use the WS-Policy ExactlyOne operator to show that the client must choose which specification level to use.
<wsdl:definitions targetNamespace="bank.example.com"
xmlns:tns="bank.example.com"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wsat11="http://docs.oasis-open.org/ws-tx/wsat/2006/06"
xmlns:wsat10="http://schemas.xmlsoap.org/ws/2004/10/wsat"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsp:Policy wsu:Id="ATPolicy">
<wsp:ExactlyOne>
<wsat11:ATAssertion />
<wsat10:ATAssertion />
<!-- omitted assertions -->
</wsp:ExactlyOne />
</wsp:Policy>
<!-- omitted elements -->
<wsdl:binding name="BankBinding" type="tns:BankPortType">
<!-- omitted elements -->
<wsdl:operation name="TransferFunds">
<wsp:PolicyReference URI="#ATPolicy" wsdl:required="true"/>
<!-- omitted elements -->
</wsdl:operation>
</wsdl:binding>
</wsdl:definitions>