Introduction

In August 2005, IBM, Microsoft, IONA®, BEA® and partners jointly released a family of Web services specifications that enables applications to invoke Web services in a transactional fashion. These specifications include:

• WS-AtomicTransaction (WS-AT), which handles short-lived transactional activities. As with other transactional systems such as Java™ Transaction API (JTA) or Customer Information Control System (CICS), you can take advantage of WS-AT to ensure that all resource updates made by Web services partcipants are either completed or rolled back as one unit of work.
• WS-BusinessActivity (WS-BA), which addresses coordination of long-running activities and supports the concept of compensation.
• WS-Coordination (WS-Coor), which provides the underlying mechanism for the creation and exchange of transaction context.

WebSphere Application Server V6 and V6.1, WebSphere Process Server V6, CICS Transaction Server V3.1 and Microsoft .NET 3.0 Windows Communication Framework (WCF) support WS-AT.

This article explains the basic concepts of WS-AT and guides you through the key steps in building transactional Web services between WebSphere Application Server and Microsoft .NET 3.0. It is intended for Web services developers, architects and administrators, who want to build and deploy transactional Web services across different platforms. You should have basic understanding of Java programming, Web services development, WSDL and SOAP.

Back to top

The big picture

WS-AT is typically used to coordinate activities performed by Web services participants so that all updates are completed in a single unit of work. For example, a retail business may want to ensure that inventory is available and payment is received before committing to a shipment. The InventoryService, PaymentService and ShipmentService can reside in different systems with heterogeneous technology stacks or even across organizational boundaries. WS-AT ensures that invocation of these three Web services is performed in a transactional fashion, providing Atomicity, Consistency, Isolation and Durability (ACID) semantics to the application.

Because the underlying platforms provide this quality of service, Web services developers don't need to develop custom error handling logic or issue manual reversals in case of failures or timeout conditions.

Figure 1 shows an example in which the order processing functionality (SubmitOrder.jsp) updates multiple systems using Web services calls to three service providers: InventoryService, PaymentService and ShipmentService. These service providers are running on different operating environments accessing different databases and/or resources. With the help of WS-AT, all updates are coordinated by a global transaction.

Back to top

Prerequisites

To complete the example in this article, you need the following software installed on a Microsoft Windows™ XP platform.

• IBM Rational Application Developer V7 or WebSphere Application Server Toolkit (hereafter called AST) V6.1. You can download a trial version of Rational Application Developer.
• Update Installer for WebSphere V6.1, which is a prerequisite for installing the WebSphere Application Server FixPack 9.
• WebSphere Application Server FixPack 9 (for 6.1.0.9) installed onto the WebSphere Application Server V6.1 Test Environment that comes with Rational Application Developer or on a standalone WebSphere Application Server. You must install this FixPack for WebSphere and .NET to interoperate successfully.
• Microsoft .NET Framework 3.0 Runtime
• Microsoft Windows SDK - March 2007 update. You can apply this update to Windows Vista or Windows XP.

WS-AT is operating system and platform neutral. For example, you can use WebSphere Application Server running on other distributed platforms such as Linux, AIX or zOS to interoperate transactionally with Microsoft .NET running on Microsoft platforms such as Windows Vista, Windows Server 2003 or Windows XP.

WebSphere Application Server V6 users must use WebSphere Application Server V6.0.2.19 (or higher) to interoperate with Microsoft .NET using WS-AT.

Back to top

Getting started

Figure 2 summarizes the high-level steps for building transactional Web service consumers and providers.

These steps are described in the following sections.

Back to top

Step 1: Develop a transactional Web service provider using Rational Application Developer

The example in this article follows a top-down approach. First, we'll create a WSDL document to describe the service interface HelloWorldTX, then we'll generate a service implementation, and finally we'll introduce transactional support to the service endpoint.

Create a WSDL document

To host the service provider, you need to create a Java® 2 Platform, Enterprise Edition® (J2EE) enterprise application project with the appropriate Web module by doing the following:

1. Enable J2EE and Web services developer capabilities in Rational Application Developer by selecting Windows => Preferences => General => Capabilities, and check Web Developer and Web service Developer.
2. Create a new J2EE project by selecting File => New => Project. Select J2EE – Enterprise Application Project and click Next.
3. Enter HelloWorldTX as the Project Name, select WebSphere Application Server v6.1 as the Target Runtime, then click Next.
4. Accept the defaults for Project Facets and click Next.
5. Create a new Web module by selecting New Module. Uncheck Application Client Module, EJB Module and Connector Module, then click Finish.
6. Click Finish to complete the creation of J2EE project
7. In the J2EE perspective, expand the new HelloWorldTX project, right-click WebContent and select New => Other = > Web Services => WSDL and click Next
8. Enter HelloWorldTX.wsdl as the File Name and click Next and Finish to accept the defaults
9. Download the sample HelloWorldTX.wsdl and cut and paste its content into your newly created HelloWorldTX.wsdl file.

Generate a service implementation

To generate a service implementation, complete the following steps:

1. Right-click HelloWorldTX.wsdl, select Web Services => Generate Java bean skeleton and click Finish.
2. Modify the generated HelloWorldTXSOAPImpl.java to return “Hello, ” + in;.

Enable WS-AT transactional support

In WebSphere Application Server, WS-AT transactional support is specified using deployment descriptors. No special Java coding is necessary.

1. Expand HelloWorldTXWeb => WebContent => WEB-INF and open web.xml.
2. On the Servlets tab, select the HelloWorldTXSOAPImpl servlet
3. Scroll down the list of options on the right. Under WebSphere Extensions => Global Transaction, check Execute using Web Services Atomic Transaction on incoming requests.
4. Press Ctrl+S to save the changes to the Web deployment descriptor (web.xml).

   This instructs the WebSphere runtime to process any received WS-AT context and dispatch the application component under a global transaction that is coordinated by the external requester.

At this point, your HelloWorldTX Web service is ready for consumption.

Back to top

Step 2: Develop a transactional Web service consumer using Microsoft .NET Framework 3.0

Microsoft .NET Framework 3.0 supports transactional Web services. Your service consumer can be a standalone .NET application or a Web application running in Internet Information Services (IIS.) In this article, we'll build a standalone C# client application that accesses the HelloWorldTX service in WebSphere.

The following steps describe how to build your C# client from scratch using the WSDL document. You can also download the pre-built .NET client provided with this article.

1. Start a Windows SDK command shell by selecting Windows SDK => CMD Shell.
2. Create a working directory to store your client source code (for example, C:\HelloWorldTXConsoleClient) and change to that directory.
3. Copy HelloWorldTX.wsdl from your Rational Application Developer workspace to your working directory.
4. Generate a C# proxy class by issuing the command : svcutil HelloWorldTX.wsdl.
5. Add the TransactionFlowAttribute attribute to the generated HelloWorldTX.cs source file as shown in Listing 1:
   
   Listing 1. HelloWorldTX Interface in C#
   

   public interface HelloWorldTX { // CODEGEN: Generating message contract since element name in from namespace is not marked nillable [System.ServiceModel.TransactionFlowAttribute(System.ServiceModel.Trans actionFlowOption.Mandatory)] [System.ServiceModel.OperationContractAttribute Action="http://helloworldtx.example.wsat.ibm.com/ sayHello", ReplyAction="*")] sayHelloResponse sayHello(sayHelloRequest request);

   
   
6. Create a simple HelloWorldTXConsoleClient C# class to trigger the invocation of the Web service operation. Listing 2 shows a sample HelloWorldTXConsoleClient.cs.
   
   Listing 2. HelloWorldTXConsoleClient.cs
   

   using System; using System.Transactions; namespace HelloWorldTXConsoleClient { class HelloWorldTXConsoleClient { static void Main(string[] args) { // start transaction using (TransactionScope transScope = new TransactionScope(TransactionScopeOption.RequiresNew)) { HelloWorldTXClient proxy = new HelloWorldTXClient(); Console.WriteLine("Invoking HelloWorldTX service..."); // invoke HelloWorldTX running on WebSphere with WS-AT String response = proxy.sayHello("World"); transScope.Complete(); Console.WriteLine("Transaction completed successfully. Response = " + response); } }

   
   
7. Create a HelloWorldTXConsoleClient.exe.config file, as shown in Listing 3, for specifying the client endpoint and transfer protocols. A custom binding is required for this scenario, instead of the standard wsHttpBinding in .NET, because wsHttpBinding uses SOAP 1.2 by default. WebSphere Application Server V6.1, on the other hand, supports SOAP 1.1.
   
   Listing 3. HelloWorldTXConsoleClient.exe.config
   

   <?xml version="1.0" encoding="utf-8"?> <configuration> <system.serviceModel> <bindings> <customBinding> <binding name="Soap11AddressingBinding" transactionFlow="true"> <textMessageEncoding messageVersion="Soap11WSAddressing10" /> <transactionFlow transactionProtocol= "WSAtomicTransactionOctober2004"/> <httpTransport/> </binding> </customBinding> </bindings> <client> <endpoint address="http://localhost:9080/ HelloWorldTXWeb/services/HelloWorldTXSOAP" binding="customBinding" bindingConfiguration="Soap11AddressingBinding" contract="HelloWorldTX" name="HelloWorldTXSOAP" /> </client> </system.serviceModel> </configuration>

   
   
8. Compile all source files by entering the following command at the Windows SDK command shell prompt:
   csc HelloWorldTX.cs HelloWorldTXConsoleClient.cs /reference: "%ProgramFiles%\Reference Assemblies\Microsoft\Framework\v3.0\System.ServiceModel.dll"; "%ProgramFiles%\Reference Assemblies\Microsoft\Framework\v3.0\System.Runtime.Serialization.dll".
9. Confirm that the HelloWorldTXConsoleClient.exe is produced successfully.

Back to top

Step 3: Enable network access in Microsoft Distributed Transaction Coordinator (MSDTC)

In Windows XP, support for distributed transaction and WS-AT is disabled by default. To enable it, do the following:

1. Install the Update for Windows Communication Foundation (KB912817).
2. Install the WS-AtomicTransaction Configuration MMC Snap-in (WsatUI.dll) (WsatUI.dll), and register the DLL by entering the following command:
   C:/> regasm /codebase "%PROGRAMFILES%\Microsoft SDKs\Windows\v6.0\Bin\WsatUI.dll"
3. Enable DTC network access by doing the following:
   • Select Control Panel => Administrative Tools => Component Services. Under Console Root, expand Component Services => Computers.
   • Right-click My Computer in MMC, select Properties, then click the MSDTC tab.
   • Click Security Configuration.
   • In the Security Configuration dialog, check the following options, as shown in Figure 3: Network DTC Access, Allow Remote Clients, Allow Inbound, Allow Outbound, Enable TIP Transactions, Enable XA Transactions.
     
     Figure 3. Security configuration
     
     
     
   • Click OK and then OK again to exit.

Back to top

Step 4: Set up WebSphere security, SSL certificates and transaction service for WS-AT message exchange

WebSphere Application Server supports either secure or non-secure exchange of transaction protocol messages (for example, Register, Prepare, Commit, Rollback.) However, Microsoft .NET requires the protocol messages to be secured using SSL mutual authentication. This means that you need to configure SSL security and set up certificates before WS-AT can operate across the two platforms.

In a production environment, a certificate from a recognized certificate authority would be used for each participant. However, for the sake of simplicity in this example, we'll produce a self-signed certificate for both WebSphere and .NET. To do this, complete the following steps:

1. Enable WebSphere Global Security using the WebSphere administrative console. Under Security => Secure administration, applications, and infrastructure, click Security Configuration Wizard.
   • Check Enable Application Security and click Next.
   • Select Local Operating System and click Next.
   • Enter <your-operating-system-userid> as the Primary administrative user name and click Next.
   • Click Finish.
2. Create a self-signed certificate using the administrative console as follows:
   • Select Security => SSL certificate and key management => Key Store and Certificates => NodeDefaultKeyStore => Personal certificates => Create a self-signed certificate.
   • Specify the following, then click OK:
     • Alias = <your_hostname>
     • Common Name = <your_hostname>. (The common name on the certificate must match the DNS name of your machine with suffix.)
     • Organization = <your_organization_name>
   • Click Save Changes to Master Configuration.
3. To assign the newly created certificate as the default, select Security => SSL certificate and key management > SSL configurations => NodeDefaultSSLSettings, then select the newly created certificates for Default server certificate alias and Default client certificate alias. Then click OK.
4. Import the signer certificate into the trust store by selecting Security => SSL certificate and key management => Key stores and certificates, then selecting both NodeDefaultKeyStore and NodeDefaultTrustStore and clicking Exchange signers.
5. Select the newly created certificate and add it to the NodeDefaultTrustStore by selecting it and clicking Add, then OK.
6. Configure the WebSphere transaction service, by doing the following:
   • Select Servers => Application servers => server1 => Container Services => Transaction Service
   • Uncheck Enable protocol security. This must be disabled for .NET interoperability. Protocol messages will still be secured using SSL transport-level security, but role-based authorization of received protocol messages is disabled. Role-based authorization of transaction protocol messages is supported only for WebSphere-to-WebSphere interactions.
   • For HTTPS proxy prefix, enter https://<your_websphere_server_hostname>:9443. If you are not using default ports (as configured for the WCInboundDefaultSecure Web container transport chain), replace 9443 with your SSL Inbound port. Note: If the WebSphere server is behind an HTTPS proxy, you should use the host name of the HTTPS proxy.
   • Click OK.
7. Optionally, enable WebSphere Web services message tracing to verify that WS-AT is working properly. Select Troubleshooting => Logs and Trace => server1 => Diagnostic Trace => Change Log Level Details, then add the following trace specification: com.ibm.ws.webservices.trace.MessageTrace=finest and click OK.
8. Save your changes and stop WebSphere Application Server.
9. If you're using Rational Application Developer or the WebSphere Application Server Toolkit, open your server configuration and expand the Security section. Check Security is enabled on this server and enter the user ID and password you used to enable WebSphere Global Security. Press Ctrl+S to save the changes.
10. Restart WebSphere Application Server.

Back to top

Step 5: Import SSL certificates and configure WS-AT in Windows XP

MSDTC is responsible for transaction management and the handling of WS-AT messages. You can configure MSDTC by following the steps below. For WS-AT to work, you must import your SSL certificate into the LocalMachine Certificate Store, instead of the User Certificate Store, because the MSDTC process operates in a different security context.

1. Select Start => Run => mmc to open the Microsoft Management Console.
2. In MMC, select File => Add/Remove Snap-in => Add => Certificates => Add => Computer Account => Next => Local Computer => Finish => Close => OK.
3. Expand Certificates, Personal
4. Select Action, All Tasks, Import…, Next, Browse…
• Filename = %WAS_HOME%\profiles\<your-server>\config\cells\<your-cell>\nodes\<your-node>\key.p12
• Password = WebAS
• Place them into the Personal Certificate Store, Press Next and then Finish
5. Expand Certificates, Trusted Root Certificate Authority and repeat Step 4 above to import the certificate into the trust CA store as well
6. Close MMC
7. Click Start => Control Panel => Administrative Tools => Component Services => Computers => My Computer.
8. Right-click My Computer, select Properties, then select the WS-AT tab. On the WS-AT tab, do the following:
   • Check Enable WS-Atomic Transaction network support.
   • In the Endpoint certificate field, click Select and choose the newly imported certificate (with your hostname as alias).
   • In the Authorized certificates field, click Select, as shown in Figure 4.
     
     Figure 4. Configure WS-AT
     
     
     
   • Check the newly created certificate and click OK, as shown in Figure 5.
     
     Figure 5. Select Authorized Certificate dialog
     
     
     
9. Click OK and restart MSDTC as prompted.

Back to top

Step 6: Test the end-to-end message flows

Now you're ready to test the end-to-end message flows between .NET and WebSphere. Start your .NET client application by running HelloWorldTXConsoleClient.exe from the command prompt. If everything works properly, you should see the Hello, World response message coming back.

To verify that a transactional message exchange has taken place, open %WAS_HOME%/profiles/<your-server>/logs/server1/trace.log, and search for wsat to find the detailed trace of WS-AT message exchanges. Figure 6 shows the entire sequence of message flows.

As you can see, multiple SOAP message exchanges are required to process transactional Web service invocations. In this example, application SOAP messages and WS-AT transaction message exchanges use different endpoint URLs and TCP ports.

Back to top

Troubleshooting hints and tips

If you encounter problems with the end-to-end flow, check the WebSphere MessageTrace in trace.log to see the progression of the message exchanges. Following are some things to check:

• Request 1: Does the application request from .NET contain SOAP headers with transaction context? If not, confirm that your client code is running in a transaction and that the required System.ServiceModel.TransactionFlowAttribute has been added to the generated proxy class HelloWorldTX.cs.
• Request 2: Is WebSphere Transaction Service able to register with MSDTC? If not, verify that the target URL in Request 2 is correct. It should be https://<your_hostname>/WsatService/Registration/Coordinator/. Also verify that the SSL certificate setup procedures are completed successfully on both Windows and the WebSphere admistrative console.
• WebSphere WS-AT and Transaction Trace: Enable this trace specification (WSCoor=all:Transaction=all) using the WebSphere administrative console to reveal any issues with the transaction handshake. The exception information in the FFDC directory is also very useful in identifying root causes.
• MSDTC / WS-AT Transaction Bridge Trace: Create a file named msdtc.exe.config in %windir%\system32 to capture details of the transaction handshake as described in this forum thread.
• If your service consumer or service provider update any resources (for example, using JDBC), ensure that an XA-compliant JDBC driver is configured and XADataSource is used in the application logic.

Back to top

Conclusion

WS-AT opens up a new set of Web service use cases that were previously very challenging to implement. It shields application developers from the complexity of transaction error and timeout handling related to remote Web services invocation.

In this article, you've learned the basic concepts of WS-AT and how to apply it in a heterogeneous Web services environment. You've also learned how to invoke WebSphere Web services transactionally from a Microsoft .NET environment, along with some common problem-solving techniques on both platforms.

Back to top

Acknowledgments

The author would like to thank the following people for their invaluable comments and contributions to this article:

• Ian Robinson, WebSphere Transaction Architect, IBM Hursley Lab, UK
• Jon Hawkes, WS-AT Developer, IBM Hursley Lab, UK
• Jackie Paradis, Senior I/T Specialist, IBM Global Business Services, Canada

Back to top

Downloads

Information about download methods

Resources

Learn

• WS-AtomicTransaction Specification, October, 2004 (PDF): This specification defines the atomic transaction coordination type that is to be used with the extensible coordination framework described in the WS-Coordination specification.
  
  
• WebSphere Information Center: This topic in the Information Center describes Web Services Atomic Transaction Support.
  
  
• Configuring WS-AtomicTransaction Support in Microsoft Windows: This topic in the MSDN library describes how you can configure WS-AtomicTransaction support by using the WS-AtomicTransaction Configuration Utility.
  
  
• Transactional Web Services with WS-AtomicTransaction: This article explains a simple way of using WS-AtomicTransaction to create distributed transactions across Web services.
  
  
• Enable atomic transaction support for Web services in CICS, developerWorks 2005: Learn about Web services in IBM CICS Transaction Server for Z/OS Version 3.1 and how you can enable atomic transactions to provide commit and recovery functionality between applications across programming languages and platforms.
  
  
• CICS Transaction Server V3.1 Information Center: Configuring CICS for Web services transactions: This topic in the Information Center describes how to configure CICS for Web services transactions.
  
  
• OASIS Web Services Transaction (WS-TX) Technical Committee: Get more information on the OASIS WS-TX TC.
  
  
• developerWorks WebSphere Web services zone: Get technical resources, such as articles, tutorials, and downloads, on WebSphere Web services solutions.
  
  

Get products and technologies

• WS-AtomicTransaction MMC Snap-in: Get the WS-AT Configuration MMC Snap-in that is used to configure a portion of the WS-AT on both local and remote machines.
  
  
• Rational Application Developer for WebSphere Software V7.0: Trial: Get the trial version of Rational Application Developer V7.
  
  
• Update installer for WebSphere V6.1: Get this prerequisite for installing the WebSphere Application Server FixPack 9.
  
  
• WebSphere Application Server FixPack 9 (for 6.1.0.9): Download the FixPack for WebSphere Application Server V6.1.
  
  
• Microsoft .NET Framework 3.0 Runtime: Download the required .NET runtime.
  
  
• Microsoft Windows SDK - March 2007 update: Get the Windows SDK.
  
  
• Update for Windows Communication Foundation (KB912817): Get this update, which adds support for the WS-AT protocol to MSDTC.
  
  

About the author

Billy Lo is a Senior I/T Architect with IBM Global Business Services in Toronto, Canada. He consults with customers on using Web services technologies to build service-oriented business applications using heterogeneous platforms such as WebSphere, CICS, Microsoft .NET, BEA WebLogic and Apache Axis. Billy is a frequent speaker at conferences on Web services development and interoperability. You can reach him at blo@ca.ibm.com.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• The big picture
• Prerequisites
• Getting started
• Step 1: Develop a transactional Web service provider using Rational Application Developer
• Step 2: Develop a transactional Web service consumer using Microsoft .NET Framework 3.0
• Step 3: Enable network access in Microsoft Distributed Transaction Coordinator (MSDTC)
• Step 4: Set up WebSphere security, SSL certificates and transaction service for WS-AT message exchange
• Step 5: Import SSL certificates and configure WS-AT in Windows XP
• Step 6: Test the end-to-end message flows
• Troubleshooting hints and tips
• Conclusion
• Acknowledgments
• Downloads
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational Application Developer for WebSphere Software
• Demo: Build, test and deploy JAX-WS Web services
• Webcast: Webcast: Develop innovative applications efficiently using the right application foundation in today's economy
• Briefing: Software development conference
• Buy: Rational Application Developer for WebSphere Software

My developerWorks community

Dig deeper into WebSphere on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers