Index Changes

Transaction Participation and Propagation

The HTTP/SOAP BC has been integrated with the WSIT WS-TX functionality providing transaction participation and propagation. The WSIT WS-TX is an implementation of WS-AtomicTransaction (a subset of WS-Coordination) and is available via the Metro project. This example shows how to use transaction with HTTP/SAOP BC and demonstrates transaction propagation with the BP SE.

What this example demonstrates

  • Developers use existing Java Transaction APIs (JTA) to initiate and complete the transaction.
  • Invocations of transacted web service operations flow transactional context from client to web service.
  • Transactional context import from web service client to HTTP/SOAP BC.
  • Transaction propagation from HTTP/SOAP BC to BP SE and from BP SE to HTTP/SOAP BC.
  • Transactional context flow resuming from HTTP/SOAP BC to web service.
  • Persistent resources updated with client-created transactions are all committed or rolled back as a single atomic transaction.
  • After the client-side code commits or aborts the JTA transaction, the client confirms that all operations in the transaction succeeded or failed by using calls to verify methods on the transacted web service.

Architecture of the example

SampleServiceClient, a WSIT servlet that initiates the transaction interact with the following components running on the service-side:
  • SoapWSATCompositeApp, a web service implemented as a JBI Composite Application using the HTTP/SOAP BC and BP SE. The SoapWSATCompositApp exposes the same transacted WSDL operations (having the same WS-AT policy assertions) as that of the SimpleService and will serve as a proxy to the SimpleService.
  • SimpleService, a web service implemented as a Java servlet with transacted operations. The Edit Web Service Attributes feature in the NetBeans IDE WSIT plug-in is used to configure Transaction Attributes of each web service operation. The SampleServiceClient does not interact directly with this web service. However it interacts with the SoapWSATCompositeApp web service which in turn interacts with the SimpleService.
  • SimpleServiceASCMTEJB, a web service implemented as container-managed transaction enterprise bean (CMT EJB). No configuration is necessary for this case.
  • LibraryFacadeWebServiceBean, a web service that uses the Java Persistence API (JPA) with two JDBC resources

In this test case, the managed Java EE resources participating in a distributed transaction have its transacted updates all committed or rolled back.

The servlet-based web service operations (SimpleService) and the CMT EJB transacted web service (SimpleServiceASCMTEJB) operations manipulate two JMS resources:

  • jms/ConnectionFactory, an XATransaction connection factory
  • jms/Queue, a JMS queue

The LibraryFacadeWebServiceBean web service operations manipulate the JDBC resources:

  • connectionPool, an XATransaction JDBC connection pool
  • jdbc/javaProgrammingLibrary, a JDBC connection resource

This test case shows how to use transaction with HTTP/SOAP BC and BP SE (with BP process atomic="yes"). To validate the test, XATransaction-enabled JMS and JDBC resources are used. The SampleServiceClient client is configured to run on one GlassFish instance (domain2) and the service running on the other GlassFish instance (domain1).

http://wiki.open-esb.java.net/attach/HTTPBCWSAtomicTransaction/soapbc-bpse-trnx-arch.png
Figure 1 - Architecture



Details of the Composite Application (SoapWSATCompositeApp)

In this example, the "inbound" HTTP/SOAP BC receives a transacted SOAP message. Upon receiving the message, the JAX-WS/Metro stack will have already imported the transaction initiated by the servlet client and "attached" the transactional context to the thread invoking the HTTP/SAOP BC's AsyncJBIProvider. To comply with the transaction propagation protocol, as required by the Transaction Propagation Systemic Quality, the HTTP/SOAP BC will propagate the imported WS-AT transaction to the BP SE in the JBI MessageExchange. The BP SE, in turn, propagates the transaction back to the HTTP/SOAP BC during a BPEL "invoke" activity. The "invoke" activity is used to invoke the servlet-based SimpleService web service via the "outbound" HTTP/SOAP BC. The "outbound" HTTP/SOAP BC will resume the transactional context on the invoking, outbound thread where by the JAX-WS/Metro stack will handle propagating the transaction to the SimpleService web service. Every WSDL operation in every web service participating in this example have WS-AtomicTransaction assertions to enable transaction processing.

http://wiki.open-esb.java.net/attach/HTTPBCWSAtomicTransaction/soapwsatcompapp.png
Figure 2 - Service Assembly


As mentioned, this Composite Application serves as a proxy to the servlet-based SimpleService. As such it simple receives the message from the client and "forwards" the message to the SimpleService web service. The BPEL process uses a "pick" activity with "onMessage" activities for each of the WSDL operations defined - this is so that we have one BPEL that can "implement" all the WSDL operations. For transaction propagation to work, the BPEL "process" element has the "{http://www.sun.com/wsbpel/2.0/process/executable/SUNExtension/Transaction}atomic" attribute set to "yes". Note that at the time of this writing, there was no tooling to add this attribute to the BPEL "process"; this needs to be done using the editor in source (raw text) mode. Refer to this wiki for details, http://wiki.open-esb.java.net/Wiki.jsp?page=MEprocessingAndPropertyPropagation.

http://wiki.open-esb.java.net/attach/HTTPBCWSAtomicTransaction/soapwsatbpel.png
Figure 3 - BPEL Process


How to Build, Deploy, and Run the Example

  1. Download the sample kit for the original WS-TX example from the WSIT tutorial.
    The original package is needed for the scripts which set up the transactional environment (i.e., set up the JDBC and JMS resources needed by the sample). Note that the SampleService and SampleServiceClient projects in this package will NOT be used. Instead, the attached SampleService.zip(info) and SampleServiceClient.zip(info) will be used. These contain modifications to work with the SoapWSATCompositeApp Composite Application.
  2. Ensure that properties that point to your local Application Server (or GlassFish) and WSIT Tutorial installations have been set.
    1. Copy file tut-install/wsittutorial/examples/bp-project/build.properties.sample to file tut-install/wsittutorial/examples/bp-project/build.properties.
    2. Set the javaee.home and wsit.tutorial.home properties in the file tut-install/wsittutorial/examples/bp-project/build.properties.
    3. Ensure that Application Server (or GlassFish) and at least Ant 1.6.5 have been installed and are on the path.
      Application Server (or GlassFish) includes Ant 1.6.5, which can be found in the as-install/lib/ant/bin directory.
  3. Set up your environment. To configure your environment to run the example:
    1. Change to the tut-install/wsittutorial/examples/wstx/basicWSTX/SampleService directory:
      cd tut-install/wsittutorial/examples/wstx/basicWSTX/SampleService
    2. Issue the following command to configure your environment to run the example:
      ant setup
      This step performs the following configuration tasks for you:
      1. Starts domain1.
      2. Creates the resources (jms/Queue and XATransaction jms/ConnectionFactory) used in the example.
      3. Creates and sets up two Application Server (or GlassFish) domains.
        The domains can be created either on one machine or on two different machines. These steps show you how to do it on one machine. The first domain, domain1, is created as part of the Application Server (or GlassFish) installation.
      4. Establishes trust between the two domains by installing each domain’s s1as security certificate in the other domain’s truststore.
  4. Use the NetBeans IDE to create a database connection.
    1. Start the NetBeans IDE.
    2. In the Services tab, right-click Databases and select New Connection.
      The New Database Connection dialog displays.
    3. Type jdbc:derby//localhost:1527/wstxSampleDB;create=true in the Database URL field.
    4. Type app in the User Name field.
    5. Type app in the Password field.
    6. Select the Remember password checkbox.
    7. Click OK.
  5. Register the Application Server (or GlassFish) server instances (domain1 and domain2) in the NetBeans IDE.
    1. If Sun Java System Application Server (domain1) is already registered, go to Step 4g. If it is not, go to Step 4b.
    2. In the Services tab, right-click Servers, and select Add Server.
      The Add Server Instance dialog appears.
    3. Choose the server (Sun Java System Application Server (or GlassFish V2) from the drop—down list and give it a descriptive name, such as Sun Java System Application Server - domain1 (Server), and then click Next.
      The Platform Location dialog displays.
    4. Click Browse, navigate to the location where the Application Server (or GlassFish server) is installed, then click Choose.
    5. Make sure that the Register Local Default Domain radio button has been selected.
    6. Use the drop-down list to select domain1, then click Next.
      The Domain Admin Login Info dialog displays.
    7. Type admin in the Admin Username field.
    8. Type adminadmin in the Admin Password field.
    9. Click Finish.
      The server instance you just registered is the one in which you will run the web service (SampleService).
    10. Right-click Servers and select Add Server.
      The Add Server Instance dialog appears.
    11. Choose the server (Sun Java System Application Server (or GlassFish V2) from the drop—down list and give it a descriptive name, such as Sun Java System Application Server - domain2 (Client), and then click Next.
      The Platform Location dialog displays.
    12. Click Browse, navigate to the location where the Application Server (or GlassFish server) is installed, then click Choose.
    13. Make sure that the Register Local Default Domain radio button has been selected.
    14. Use the drop-down list to select domain2, then click Next.
      The Domain Admin Login Info dialog displays.
    15. Type admin in the Admin Username field.
    16. Type adminadmin in the Admin Password field.
    17. Click Finish.
      The server instance you just registered is the one in which you will run the web service client (SampleServiceClient).
  6. Download the SampleService.zip(info) file and extract the SampleService project.
  7. Open the SampleService project and associate the SampleService web service with the appropriate instance (domain1) of the Application Server (or GlassFish server).
    1. Select File, then Open Project.
    2. Browse to the directory where the SampleService is extracted and select the SampleService project.
    3. Select the Open as Main Project check box.
    4. Select the Open Required Projects check box.
    5. Click Open Project.
      The SampleService project and two required projects, SampleService-ejb and SampleService-war, are opened and are shown in the Projects tab.
    6. In the Projects tab, right-click SampleService, select Properties, then select the Run category.
    7. Use the Server drop—down list to point to the default domain, domain1, for the Application Server (or Glassfish) server instance you registered in Step 4.
    8. Click OK.
  8. Resolve references to or add the Toplink Essentials Library to the SampleService-ejb project.
    The SampleService-ejb project references the Toplink Essentials Library Module that is included with NetBeans IDE. To verify whether the reference to this library is resolved in your NetBeans IDE environment:
    1. Right click the SampleService-ejb project and select Properties.
    2. Select the Libraries category.
      You should see Toplink Essentials in the Compile-time Libraries pane of the Compile tab.
    3. If you do not see the library, click Add Library to display the Add Library dialog.
    4. Locate and select Toplink Essentials and then click Add Library.
      You should now see Toplink Essentials in the Compile-time Libraries pane of the Compile tab.
    5. Click OK.
      To verify that you have Toplink Essentials library in NetBeans IDE, select Tools and then Library Manager. You should see "Toplink Essentials" in the left pane. If you don't, you can create the library yourself using the two Toplink JAR files in the Application Server (or GlassFish) lib directory and then resolve the reference to the newly created library.
  9. Check the proper transaction attributes for each mapping (wsdl:binding /wsdl:operation) in the SimpleService-war web service.
    To check/set the transaction attributes for the SampleService-war web service:
    1. In the Projects tab, expand the SampleService-war node.
    2. Expand the Web Services node.
    3. Right-click SimpleService and select Edit Web Service Attributes.
    4. In the Quality of Service tab, expand the five operation nodes and then expand the method nodes under each operation node. Use the Transaction drop-down list to check/set the appropriate transaction attribute for each method:
      1. Ensure that init is set to Required.
      2. Ensure that publishRequired is set to Required.
      3. Ensure that verify is set to Required.
      4. Ensure that getMessage is set to Required. If any other operations are displayed, ignore them.
      5. Click OK.
        Transaction attributes for SampleServiceASCMTEJB do not need to be set; EJB 3.0 transaction attributes are used.
        The transaction attribute settings for the SampleService-war are stored in the file SampleService\SampleService-war\web\WEB-INF\wsit-wstx.sample.service.Simple.xml.
  10. Deploy the SampleService web service.
    Right-click SampleService and select Undeploy and Deploy. NetBeans IDE will start domain1 and deploy the web service to that domain.
  11. Download the SoapWSATCompositeApp.zip(info) file and extract the SoapWSATCompositeApp and SoapWSATBPEL projects.
  12. Open the SoapWSATCompositeApp project and resolve the BPEL project by browsing to the SoapWSATPBEL project.
  13. Associate the SoapWSATCompositeApp project with the appropriate instance (domain1) of the Application Server (or GlassFish server).
  14. Build and Deploy the SoapWSATCompositeApp project.
  15. Download the SampleServiceClient.zip(info) file and extract the SampleServiceClient project.
  16. Open the SampleServiceClient project
  17. Register the SampleServiceClient client with the appropriate instance (domain2) of the Application Server (or GlassFish) server.
    1. Select File, then Open Project.
    2. Browse to the tut-install/wsittutorial/examples/wstx/basicWSTX/ directory and select the SampleServiceClient project.
    3. Select the Open as Main Project check box.
    4. Select the Open Required Projects check box.
    5. Click Open Project.
      The SampleServiceClient project is opened and is displayed in the Projects tab.
    6. In the Projects tab, right-click SampleServiceClient, select Properties, then select the Run category.
    7. Use the Server drop—down list to point to domain2.
    8. Click OK.
  18. Deploy and run the client (SampleServiceClient).
    Right-click SampleServiceClient and select Run.
    NetBeans IDE will start domain2, deploy the servlet and EJB CMT clients to that domain, then display the results for both in a pop-up browser window, as shown in Figure 4


http://wiki.open-esb.java.net/attach/HTTPBCWSAtomicTransaction/results_wsat.png
Figure 4 - Results from SampleServiceClient


JSPWiki v2.4.100
[RSS]
« Home Index Changes Prefs
This page (revision-12) was last changed on 13-Mar-08 15:00 PM, -0700 by jamestran