Web Services interoperability between Apache Axis2 and the WebSphere Web Services Feature

Pack, Part 1

Test basic SOAP and WS-Addressing interoperability

Andrew A. DasStaff Software Engineer WebSphere Application Server Feature Pack for Web ServicesIBM, Research Triangle Park, NCMarch 2008

© Copyright International Business Machines Corporation 2008. All rights reserved.

This article describes how to use the IBM WebSphere Application Server Version 6.1 Feature Pack for Web Services Service Endpoint Interface samples to achieve interoperability with Apache Axis2. It provides step-by-step configurations and programming information for achieving basic Web services interoperability for SOAP 1.1, SOAP 1.2, WS-Addressing, and asynchronous client behavior.

This article is intended for Web services developers and architects who plan to develop Web services across these platforms. To get the most from this article, you should have a basic understanding of Java™ programming, Web services development, WSDL and SOAP.

Web Services interoperability between Apache Axis2 and the WebSphere Web Services Feature Pack, Part 1.............................................................................................................1Test basic SOAP and WS-Addressing interoperability.......................................................1Introduction .......................................................................................................................... 3

Web service messaging .................................................................................................... 4 Message exchange patterns (MEPs) ................................................................................ 4 Terminology used in this article ...................................................................................... 5 Synchronous and asynchronous client API ..................................................................... 5 Transport layer behavior .................................................................................................. 5 WS-Addressing ................................................................................................................ 6 Get started with the samples ........................................................................................... 6 Verify the WSFP sample endpoints ................................................................................. 7 Run the WebSphere Feature Pack samples ...................................................................... 7

Run the Axis2 samples ..................................................................................................... 7 Start the Axis2 services ................................................................................................ 8 Run the Axis2 client ..................................................................................................... 9 Axis2 client to Axis2 service Ping example ................................................................ 9 Axis2 client to Axis2 service Echo example ............................................................. 10 Axis2 client to Axis2 Service Async echo example .................................................. 10

Client to Axis2 service examples ................................................................................... 11 Client to Axis2 service One-Way Ping example ....................................................... 12 Client to Axis2 service Synchronous Echo example ................................................. 13

Axis2 client to WSFP service examples ........................................................................ 15 Axis2 client to WSFP service Ping example ............................................................. 16

Axis2 client to Feature Pack for Web Services service Echo example ................. 16 Axis2 client to Feature pack for Web Services service Async Echo sample ............. 17

Configure the SOAP version ............................................................................................. 17 Configure the SOAP version in JAX-WS ...................................................................... 17 The SOAP version and the SEI samples ........................................................................ 17 Configure the SOAP version in Axis2 ........................................................................... 17

Run the Axis2 samples using SOAP 1.2 ............................................................................ 18 Start SOAP 1.2 Axis2 services ...................................................................................... 18

Test SOAP 1.2 Axis2 services with SOAP 1.2 Axis2 client ............................................ 19 SOAP 1.2 Axis2 client to SOAP 1.2 Axis2 service Ping example ................................ 20 SOAP 1.2 Axis2 client to SOAP 1.2 Axis2 service Echo example ............................... 20 SOAP 1.2 Axis2 client to SOAP 1.2 Axis2 service Async example ............................. 20

Test the SOAP 1.2 WSFP SEI client to Axis2 SOAP 1.2 services ................................... 20 SOAP 1.2 WSFP client to SOAP 1.2 Axis2 service Ping example ............................... 20 SOAP 1.2 WSFP client to SOAP 1.2 Axis2 service Echo and Synchronous Async example .......................................................................................................................... 22

Test SOAP 1.2 Axis2 client to WSFP SOAP 1.2 services ................................................ 23 SOAP 1.2 Axis2 client to SOAP 1.2 WSFP service Ping example ............................... 23 SOAP 1.2 Axis2 client to SOAP 1.2 WSFP service Echo and Async example ............ 24

Configure WS-Addressing ................................................................................................. 24 Apply the WS-Addressing policy set to the Feature Pack samples ............................... 24 Configure WS-Addressing in Axis2 ............................................................................. 24

Client-side changes .................................................................................................... 24 Service-side changes .................................................................................................. 25

Test WS-Addressing configuration .................................................................................... 25 Configure transport-level asynchronous behavior ............................................................. 25

Configure asynchronous behavior at the transport layer in the Feature Pack for Web Services client ................................................................................................................ 26 Configure asynchronous behavior at the transport layer in Axis2 client ....................... 26

Test asynchronous over-the-wire interoperability ............................................................ 28 Test WSFP client to WSFP service communication using async over-the-wire to confirm semantic interoperability .................................................................................. 28 Test Axis2 client to Axis2 service communication using async over-the-wire to confirm semantic interoperability ................................................................................. 28

Test WSFP client to Axis2 service communication using async over-the-wire to confirm technical interoperability ................................................................................. 29 Test Axis2 client to WebSphere service communication using async over-the-wire to confirm technical interoperability ................................................................................. 31

Summary ............................................................................................................................ 32 Resources ........................................................................................................................... 33

Specifications ............................................................................................................. 33 Feature Pack for Web Services and developerWorks articles .................................. 33 Apache Axis2 ............................................................................................................ 33 Apache Tomcat .......................................................................................................... 33

About the author ................................................................................................................ 34

IntroductionThe WebSphere Application Server Version 6.1 Feature Pack for Web Services (hereafter called WSFP) includes a set of Java API for XML-based Web Services (JAX-WS) samples. These samples demonstrate the usage of simple message exchange patterns (MEPs), using both synchronous and asynchronous programming models, and support for SOAP 1.1 and SOAP 1.2.

The samples included with the WSFP can be attached to different Web services quality of service (QoS) protocols. A QoS is the non-functional value added to the underlying technology of Web services that provides improvements in security, reliability, availability or performance. Web services server vendors must comply with standard specifications of these QoS’s to interoperate successfully with other vendor Web services implementations. Some of the popular standards supported by most vendors are: WS-Addressing (WS-A), WS-Reliable Messaging (WS-RM), and WS-Secure Conversation (WS-SC). By applying QoS’s to the samples, you can establish a wide range of interoperability tests.

This five-part article series will help developers and architects apply and validate interoperability of Web services QoS’s between Apache Axis2 and the WSFP. For background information on MEPs and installation and configuration of WSFP samples, see Achieving Web services interoperability between the WebSphere Web Services Feature Pack and Windows Communication Foundation, Part 1: Set up the test environment and run the samples for basic SOAP and WS-Addressing interoperability (LeVay and Link, developerWorks 2007). Note: This article is cited frequently and will be referred to hereafter as LeVay 2007.

This article describes how to set up a test environment for the WSFP samples and the Apache Axis2 samples. It describes how to configure the samples with basic SOAP 1.1, SOAP 1.2 and WS-Addressing to demonstrate interoperability.

Web service messagingWeb services are defined based on XML messaging, and the following three properties describe a given Web service's messaging interaction.

1. Message exchange pattern (MEP)2. Synchronous and asynchronous client API 3. One-way/two-way transport behavior

At the simplest level, Web services messaging is based on sending and receiving messages. A given message is sent by one party and received by another. Furthermore, the messages in this exchange might be related to one another, so it is essential to identify the most common use cases for a group of related messages, which gives rise to the concept of message exchange patterns, or MEPs.

A service requester's actions in the transitory period between the exchanges of two related messages define the synchronous and asynchronous behavior in the client API. In a synchronous programming model, the client API invocation blocks and waits until the related message arrives at the destination. In contrast, in an asynchronous or non-blocking programming model, the client API invocation continues processing without blocking and, when the related message arrives, it is associated with the appropriate messages within that exchange.

The transport of a Web service message exchange is characterized as one-way or two-way based on a simplex, or duplex behavior. One-way transports are non-blocking in nature, such as JMS and SMTP. Conversely, two-way transports, such as TCP and HTTP, may allow the related message to travel back on the same channel. However, in Web services, two-way transports can be used as one-way transports, and are effectively treated as one-way.

Message exchange patterns (MEPs)The WebSphere and Axis2 samples were developed to drive simple MEPs used to test protocol-level interoperability. The following three MEPs were used to demonstrate interoperability. You can understand all of the names by replacing the in with request and out with response. The two most common MEPs are:

In-only (“fire and forget”) - Ping sampleThe service requester sends a message to the service provider and does not expect any related message. The Ping scenario demonstrates a one-way MEP to send an application message from a client to a service.

In-Out (“request response”) - Echo sampleThe service requester sends a message to the service provider and receives a related message from the service provider. This scenario demonstrates a two-way MEP that sends an application message from a client to a service and receives an echoed response from the service.

Terminology used in this articleThe following terminology is used in this article.

• Ping: Indicates an implementation of the In-Only MEP.• Echo: Iindicates an implementation of the In-Out MEP. • Async or Async echo: Indicates an implementation of the In-Out MEP using

the asynchronous client API, with two different transport behaviors:o Async Echo with synchronous communication uses the two-way

behavior (related messages on the same channel).o Async Echo with asynchronous communication uses the one-way

behavior (related messages on a separate channel).o

Synchronous and asynchronous client API The synchronous and asynchronous (blocking and non-blocking) behavior is based on the programming model of the client API. A synchronous invocation blocks and waits for the related messages to arrive, whereas an asynchronous invocation returns and continues processing while another thread waits and processes the returned set of related messages.

When a one-way transport behavior is associated with a two-way MEP, we use the asynchronous programming model in the service requestor, or client. The client creates a callback handler on a separate thread, which receives the related message from the service through a separate listener managed by the client run-time. This gives us a truly end-to-end asynchronous behavior.

Both these programming models are demonstrated in the accompanying sample code, using the Echo service.

Transport layer behaviorThe behavior of the transport layer is an important factor in determining Web services messaging communication. The transport layer is characterized by one-way or two-way behavior.

In a one-way transport, the complexity of the Web service messaging is reduced because the response message comes on a separate channel. A two-way transport, on the other hand, provides the flexibility to use either the one-way or two-way transport for messaging. For instance, when the transport is HTTP, a two-way transport sends and receives related messages on the same HTTP connection, or channel. On the other hand, if a two-way transport is used in a one-way style, the Web service responds with a 200 code, indicating that the related message will be sent on a different connection, or channel.

WS-AddressingWS-Addressing defines a framework for incorporating message addressing information into Web services messages. It provides a uniform addressing protocol for SOAP messages traveling over synchronous or asynchronous transports between related parties in an exchange. It also comes with addressing extensions to build applications around a variety of messaging patterns beyond the typical exchange of requests and responses.

The article Web Services Messaging with Apache Axis2: Concepts and Techniques (Perera and Ranabahu, ONJava 2005) provides a good overview of WS-Addressing. As defined in the article, the following five properties define a service requester and service provider conversation:

1. Message exchange pattern 2. Transport to access service provider 3. Transport used by the related messages 4. Behavior of the transport 5. Synchronous or asynchronous programming model of the service requestor

The service provider declares the first two, while the client is flexible to define the other properties. The service requestor’s synchronous or asynchronous nature is completely transparent to the service provider, and the service requestor uses WS-addressing to describe the Web service messaging.

Note: In order for a true asynchronous behavior (that is, asynchronous client API and message exchanges on separate channels at the transport layer), the service requester and service provider interaction should execute with WS-Addressing enabled.

The WSFP enables WS-Addressing using policy sets. For more information on this topic, see “WebSphere Application Server policy sets,” (p. 27, LeVay 2007).

The sample code accompanying this article demonstrates how to use WS-Addressing headers in the SOAP message exchanges.

Get started with the samples In this section, you’ll see how to present information in various formats. Pick the appropriate format for the type of information you need to present.

To run the WebSphere and Axis2 samples, complete the following steps on a Windows XP system:

1. Install WebSphere Application Server V6.1 (hereafter called Application Server).

2. Install the latest Update Installer for WebSphere Application Server.

3. Install the WebSphere Application Server V6.1 Feature Pack for Web Services, including the SEI samples. The samples are located in the <WAS_HOME>/samples/lib/WebServicesSamples directory. You can install the EAR files (WSSampleClientSei.ear and WSSampleServicesSei.ear) using either the Integrated Solutions Console or use the installapps.cmd script. Installation instructions for both methods are in the WSFP_README.txt file in the samples directory.

4. Download and uncompress the WSSampleClientSei_Interop.zip file that contains the modified WSSampleClientSei.ear, renamed to WSSampleClientSei_Interop.ear. Install the EAR file using the Integrated Solutions Console.

5. Install Apache Axis2 1.3.

6. Install Apache Tomca6 6.0.

7. Install the Apache Axis2 WAR (Web archive) into the Apache Tomcat server.

8. Download and uncompress the Axis2 client sample (Axis2ClientSampleInstaller.zip) to the <AXIS2_HOME> directory.

9. Download and uncompress the Axis2 services sample (Axis2ServicesSampleInstaller.zip) to a temporary location, then load all the service (.aar) files into the Axis2 Web application, running on Apache Tomcat.

10. Download LeVay 2007, which is a companion to this article.

Verify the WSFP sample endpointsVerify the WSFP sample endpoints using the process described using the process described in “Verify the SEI sample endpoints” (p. 9, LeVay 2007).

Run the WebSphere Feature Pack samplesRun the WebSphere Feature Pack SEI sample demo as described in “Run the SEI samples” (p.10, LeVay 2007).

Run the Axis2 samplesIn this section, you’ll learn how to run the Axis2 samples, including how to correctly start the Axis2 services and use the command line for the Axis2 client.

Start the Axis2 servicesTo start the Axis2 services, do the following:

1. Start the Tomcat server is running. Open your browser to http://localhost:8080/ to verify the server is running properly.

2. Point your browser to http://localhost:8080/axis2/ to access the Apache Axis2 administration console. Click Administration to log in.

3. Make sure that all the services are up and running. You should see at least four services listed, under the Services:

• PingService (w/ SOAP 1.1)• EchoService (w/ SOAP 1.1)• PingService12 (w/ SOAP 1.2)• EchoService12 (w/ SOAP 1.2)

Figure 1 shows the Axis2 administration console with the installed services.

Figure 1. Axis2 administration console with services listed

Run the Axis2 clientTo run the Axis2 client, do the following:

1. Open a command window by selecting Start => Run => cmd.2.3. Change to the <AXIS2_HOME>/samples/interop/ directory.4.5. Enter runSampleAxis2 -? to see command usage information as shown here:

runSampleAxis2 -h [hostname] -p [port] -f [urlSuffix] -m [testMessage] -s [echo|ping|async] -t [timeout] -c [count] -a [y|n] –w [y|n] -1 -2

Default values are: hostname= localhostport= 8080testMessage= HELLOurlSuffix= /axis2/services/EchoService

service= asynctimeout= 240 (seconds)count= 1

a=n (WS-Addressing property, default set to no)w=n (wire level asynchronous behavior, default set to no)

-1 = soap 1.1 (default) -2 = soap 1.2

The following examples show how to use the command line arguments correctly and verify that both the Axis2 services and client are configured correctly. It’s a good idea to always test the Axis2 to Axis2 communication before attempting any interoperability tests between Application Server and Axis2.

Axis2 client to Axis2 service Ping exampleFollowing is an example of the Ping MEP using the command line:

runSampleAxis2 -p 8080 -m “ping test” -s ping

Since Ping is a one-way MEP, there is no response; however, this command should end successfully as shown in the client output in Figure 2.

Figure 2. Axis2 Client command line example for the Ping MEP

Your input string should be printed by the PingService to the Apache Tomcat server logs in stdout_<date>.log.

Axis2 client to Axis2 service Echo exampleFollowing is an example for the echo sample using the command line:

runSampleAxis2 -p 8080 -m “echo test” -s echo

The service response to the client request is:

<echoResponse>AXIS2: echo test</echoResponse>>> AXIS2 CLIENT: Echo response is: <ns1:echoStringResponse

xmlns:ns1="http://com/ibm/was/wssample/sei/echo/"><echoResponse>

AXIS2: echo test</echoResponse>

</ns1:echoStringResponse>

The client prepends AXIS2: to the test message echo test. You should see the AXIS2: echo test message in the service log.

Axis2 client to Axis2 Service Async echo exampleNote that this example is for the asynchronous programming model with asynchronous over-the-wire communication.

Following is an example of the Async Echo sample using the command line:

runSampleAxis2 -p 8080 -m “async test” -s async

The service response to the client request is:>> AXIS2 CLIENT: Async URL set to http://localhost:8080/axis2/services/EchoService>> AXIS2 CLIENT: - Async Timeout waiting for reply.[MessageContext: logID=urn:uuid:ECB1573FD5A2622E321195230247803]AXIS2: async test<ns1:echoStringResponse

xmlns:ns1="http://com/ibm/was/wssample/sei/echo/"><echoResponse>

AXIS2: async test</echoResponse>

</ns1:echoStringResponse>>> AXIS2 CLIENT: Async invocation still not complete>> AXIS2 CLIENT: SEI Async invocation complete.

The client prepends AXIS2: to the test message echo test. You should see the AXIS2: async test message in the service log.

Test for basic SOAP 1.1 MEP interoperability

This section demonstrates Feature Pack for Web Services client to Axis2 service interoperability and Axis2 client to Feature Pack for Web Services interoperability using SOAP 1.1.

Client to Axis2 service examplesPoint your browser to the SEI sample application at:http://<hostname>:port/wssamplessei_interop/demo

For example: http://localhost:9081/wssamplesei_interop/demo

Note: The port may vary based on your Application Server configuration.

This command opens the SEI samples demo UI shown in Figure 3.

Figure 3. SEI WebSphere Samples Demo

Client to Axis2 service One-Way Ping exampleTo demonstrate the Client to Axis2 service One-Way Ping MEP, do the following, as shown in Figure 4:

1. Select One-Way Ping for Message Type. 2. Enter a Message String. In this example, we use Ping WAS to AXIS2.3. Specify http://localhost:8080/axis2/services/PingService, for the

Service URI, which points to the Axis2 service.4. Assuming the Axis2 service is running, click Send Message.

Figure 4. Client to Axis2 service One-Way Ping

You should see the Ping WAS to AXIS2 message in the Tomcat server stdout.log. The presence of the message in the log indicates that you have successfully performed your first interoperability test.

Client to Axis2 service Synchronous Echo exampleTo demonstrate the Client to Axis2 service Synchronous Echo MEP, do the following, as shown in Figure 5:

1. Select Synchronous Echo for Message Type..2. Enter a Message String. In this example, we use WAS Sync Echo to AXIS2.3. Specify http://localhost:8080 for the Service URI. 4. Click Send Message.

Figure 5. Client to Axis2 service Synchronous Echo

You should see the “WAS Sync Echo to AXIS2” message in the Tomcat server stdout.log.

Axis2 client to WSFP service examplesOpen a command window and change to the directory <AXIS2_HOME>/samples/interop. The process here is similar to those for running the Axis2 client to Axis2 service tests. However, in this case, the Axis2 client should point to the WSFP service on port 9087.

Axis2 client to WSFP service Ping exampleFollowing is an example of the command for the Ping sample for Axis2 to WSFP:

C:\axis2-1.3\samples\interop>runSampleAxis2.bat -p 9087 -f /WSSampleSei/PingService -m "ping interop test" -s ping

Figure 6 shows an example of the proper usage of the Axis2 client request to WSFP service.

Figure 6. Axis2 client request to WSFP service command line usage example

You can see the Feature Pack for Web Services service output for the string ping interop test in the Application Server SystemOut.log.

Axis2 client to Feature Pack for Web Services service Echo exampleFollowing is an example of the command for the Echo sample for an Axis2 client to a WSFP service:

C:\axis2-1.3\samples\interop>runSampleAxis2.bat -p 9087 -f /WSSampleSei/EchoService -m "echo interop test" -s echo

The response to the client request is JAXWS==>> echo interop test, because the JAX-WS echo service prepends JAXWS==>> to the input string for the output response. You can see the WSFP service output for the string echo interop test in the Application Server SystemOut.log.

Axis2 client to Feature pack for Web Services service Async Echo sampleFollowing is an example of the command using the Async Echo sample that sends a request from an Axis2 client to a WSFP Echo service:

C:\axis2-1.3\samples\interop>runSampleAxis2.bat -p 9087 -f /WSSampleSei/EchoService -m "async interop test" -s async

This example is similar to the Echo example. The differences are only visible in the programming model of the client API. The response to the client request is JAXWS==>> async interop test. You can see the WSFP service output for the string async interop test in the WebSphere Application Server SystemOut.log.

Configure the SOAP version

The SOAP version is a simple configurable option that determines interoperability at the lowest level, the SOAP message. Both Axis2 and the WSFP support SOAP 1.1 and SOAP 1.2 for interoperability. The client and service SOAP version must match to exchange messages properly.

Configure the SOAP version in JAX-WSFor information on how to configure the SOAP version in JAX-WS, see “Configure the SOAP version in JAX-WS” (p. 30, LeVay 2007).

The SOAP version and the SEI samplesWhen running the WebSphere SEI samples, the SOAP checkbox in the SEI sample demo UI dictates the SOAP version of the client request. At run-time, the SEI sample code invokes the appropriate APIs for the selected SOAP version.

Configure the SOAP version in Axis2Switching from SOAP 1.1 to SOAP 1.2 is fairly simple in Axis2. You do this by setting the appropriate property in the service client. In order to send SOAP 1.2 encoded messages, you need to explicitly add a SOAP 1.2 property in the service client code by doing the following:

1. Open either the PingClient.java, or EchoClient.java source file in an editor. The source files are in the accompanying Axis2SampleClients.jar file. We use the PingClient.java.

2.

3. First, import the SOAP 1.2 package to set the property, by entering the following command:

import org.apache.axiom.soap.SOAP12Constants;

4. Add the line of code highlighted in bold between the italicized block as shown here:

clientOptions.setAction("pingOperation");clientOptions.setSoapVersionURI(SOAP12Constants.SOAP_ENVELOPE_NAMESPACE_URI);serviceClient.setOptions(clientOptions);

5. Running the sample generates SOAP envelopes using SOAP 1.2 encoding. An example header is shown below. Notice the yellow highlighted text indicating the SOAP 1.2 namespace.

<?xml version="1.0" encoding="http://www.w3.org/2003/05/soap-envelope"?><soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://www.w3.org/2005/08/addressing"><soapenv:Header>

Run the Axis2 samples using SOAP 1.2These SOAP 1.2 Axis2 endpoints were developed primarily to handle SOAP 1.2 encoded messages. The business logic is identical to the SOAP 1.1 service implementations. For SOAP 1.2 exchanges, the WebSphere SEI sample demo UI and the Axis2 CLI client expect the WebSphere SEI SOAP 1.2 service endpoint URLs to be: http://<hostname>:<port >/WSSampleSei/PingService12 or http://<hostname>:<port> /WSSampleSei/EchoService12.

Start SOAP 1.2 Axis2 servicesMake sure that the PingService12 and EchoService12 services are available on the Axis2 server by checking the Axis2 Web application administrative console and viewing the available services, as shown in Figure 7. If the services are unavailable, load them from the accompanying Axis2SampleServices.zip file. The services are packaged as PingService12.aar and EchoService.aar files.

Figure 7. Axis2 SOAP 1.2 services started

Test SOAP 1.2 Axis2 services with SOAP 1.2 Axis2 client

In this section, you’ll learn how to use the command line arguments for the Axis2 client to interact with the Axis2 services configured for SOAP 1.2. In each of these examples, you need to use the correct endpoints, which are /WSSampleSei/PingService12 for the Ping sample, and /WSSampleSei/EchoService12 for the Echo and Async samples.

SOAP 1.2 Axis2 client to SOAP 1.2 Axis2 service Ping exampleFollowing is an example command for the Ping sample:

C:\axis2-1.3\samples\interop>runSampleAxis2.bat -p 8080 -f /axis2/services/PingService12 -m "ping soap12 test" -s ping -2

Note the -2 at the end of the command. This indicates that SOAP 1.2 encoding should be enabled. Because this operation is a one-way MEP, there is no service response. You should also see the echo test SOAP 12 message in the Tomcat Server stdout _<date>.log.

SOAP 1.2 Axis2 client to SOAP 1.2 Axis2 service Echo exampleFollowing is an example command for the Echo sample:

C:\axis2-1.3\samples\interop>runSampleAxis2.bat -p 8080 -f /axis2/services/EchoService12 -m "echo soap12 test" -s echo -2

The service response to the client request is SOAP12==>>AXIS2: echo soap12 test. The service prepends SOAP12==>> and the client prepends AXIS2: to the echo soap12 test. You should also see the echo test SOAP 12 message in the Tomcat Application Server stdout_<date>.log.

SOAP 1.2 Axis2 client to SOAP 1.2 Axis2 service Async exampleFollowing is an example command for the Async sample:

C:\axis2-1.3\samples\interop>runSampleAxis2.bat -p 8080 -f /axis2/services/EchoService12 -m "async soap12 test" -s async -2

The service response to the client request is SOAP12==>>AXIS2: async soap12 test. The service prepends SOAP12==>> and the client prepends AXIS2: to the async soap12 test. You should also see the echo test SOAP 12 message in the Tomcat Server stdout _<date>.log.

Test the SOAP 1.2 WSFP SEI client to Axis2 SOAP 1.2 servicesThe following examples are similar to those for the WSFP SEI client to Axis2 SOAP 1.1 services. However, in these examples, you select the SOAP 1.2 checkbox.

SOAP 1.2 WSFP client to SOAP 1.2 Axis2 service Ping exampleTo demonstrate the SOAP 1.2 WSFP client to SOAP 1.2 Axis2 service In-Only MEP, do the following, as shown in Figure 8:

1. To access the WSFP sample demo UI, point your browser to http://<localhost>:<port>/wssamplesei_interop/demo.

2. Select One-Way Ping for Message Type.3. Enter a Message String. In this example, we use Ping test WAS to Axis2

SOAP 12.4. Specify http://<localhost>:<port>/axis2/services/PingService12 for

the Axis2 Service URI.5. Check Use SOAP 1.2.6. Click Send Message.

Figure 8. SOAP 1.2 WSFP client to SOAP 1.2 Axis2 service Ping example

You can see the WSFP service output for the string test WAS to Axis2 SOAP 12 in the Tomcat Server stdout_<date>.log.

SOAP 1.2 WSFP client to SOAP 1.2 Axis2 service Echo and Synchronous Async exampleYou can use the same procedure as the Ping example described in the previous section, to exchange Echo and Async messages using SOAP 1.2 encoding. However, in this case set the Service URI to http://<localhost>:<port>/axis2/services/EchoService12.

You can see the Feature Pack for Web Services service output for the request string in the Tomcat Server stdout_<date>.log.

Note: The Asynchronous Echo with Asynchronous communication option is not possible in this scenario, as it requires WS-Addressing enabled. This option is covered in a later section.

Test SOAP 1.2 Axis2 client to WSFP SOAP 1.2 servicesThe screen captures for the following examples are similar to the Axis2 client to WSFP SOAP 1.1 services, so they are not repeated here. However, in these examples, the Axis2 client points to SOAP 1.2 services. In all of these examples, it’s important that you use the WSFP port and the correct endpoints, which are /WSSampleSei/PingService12 for the Ping sample and /WSSampleSei/EchoService12 for the Echo and Async samples.

SOAP 1.2 Axis2 client to SOAP 1.2 WSFP service Ping exampleFollowing is an example command for the Ping sample to demonstrate interoperability from a SOAP 1.2 Axis2 client to a SOAP 1.2 WSFP:

C:\axis2-1.3\samples\interop>runSampleAxis2.bat -p 9087 -f /axis2/services/PingService12 -m "ping Axis2 to WAS soap12 test" -s ping -2

Figure 9 shows an example of the proper usage of the Axis2 client request to a WSFP service along with the successful results for Ping using SOAP 1.2.

Figure 9. Axis2 Client usage example for Ping using SOAP 1.2 to WSFP service

SOAP 1.2 Axis2 client to SOAP 1.2 WSFP service Echo and Async exampleYou can use the same procedure as the Ping example in the previous section to exchange Echo and Async messages using SOAP 1.2 encoding. However, before running the Axis2 client, ensure that your service URI (-f option) is set to:-f /WSSampleSei/EchoService12.

You can see the WSFP service output for the request string in the Application Server SystemOut.log.

Note: The Asynchronous Echo with Asynchronous communication option is not valid in this scenario, as it requires WS-Addressing enabled. This option will be covered in a later section.

Configure WS-Addressing

In this section, you’ll learn how to apply the WS-Addressing policy set to the WSFP SEI samples and configure Axis2 to use WS-Addressing for the Axis2 samples.

Apply the WS-Addressing policy set to the Feature Pack samplesTo enable WS-Addressing in the WSFP samples, see “Apply the WS-Addressing policy set to the Feature Pack samples” (p. 49, LeVay 2007).

Configure WS-Addressing in Axis2 This section describes how to configure the client- and service-side for WS-Addressing.

Client-side changesWS-Addressing support is built into Apache Axis2. Also, WS-Addressing is enabled by default in the client_axis2.xml configuration file, as long as you have an unaltered copy of the axis2.xml file from the Apache Axis2 1.3 distribution. Make sure that the entry <module>addressing</module> has not been commented out in the client_axis2.xml. Please remove the comments, if the line is not commented out. If not, your Apache Axis2 client is able to generate SOAP requests with WS-Addressing headers.

Note: For convenience, the supplied Axis2 client runSampleAxis2.bat file has built-in logic to modify client_axis2.xml automatically, driven by the command-line option -a of the .bat file.

Since no programmatic changes are required to turn on WS-Addressing, you can run the Axis2 client. You’ll notice WS-Addressing headers in the SOAP envelope, if both the client and service have been successfully enabled with WS-Addressing.

Service-side changesTo enable WS-Addressing on the Axis2 provider, ensure the WS-Addressing module is engaged for the applicable service, using the Axis2 administrative console, as shown in Figure 10. Refer to the Apache Axis2 Web Administrator’s Guide for information on how to engage QoS modules.

No other code changes are necessary.

Figure 10. Axis2 administrative console showing how to engage the module

Test WS-Addressing configuration

Once you have both the service requester and the service provider enabled with WS-Addressing, you can run either the complete SOAP 1.1 or SOAP 1.2 interoperability test as described earlier.

Configure transport-level asynchronous behavior

In previous sections, we performed only the two-way MEP with either blocking or non-blocking programming model with a two-way behavior. This section describes how to configure asynchronous over-the-wire, or one-way, behavior in JAX-WS and how to configure Axis2 for the same.

Since the transport level asynchronous behavior is entirely controlled by the service requestor’s programming model the changes have to be made at the service provider end.

Configure asynchronous behavior at the transport layer in the Feature Pack for Web Services clientTo configure the JAX-WS client for one-way behavior, see “Configure asynchronous over-the-wire behavior in a Feature Pack for Web Services client” (p. 63, LeVay 2007).

Configure asynchronous behavior at the transport layer in Axis2 clientTo build an asynchronous client, open the org.apache.axis2.sample.client.SampleClient file and perform the following steps:

1. The service client invokes the service using the non-blocking method call sendReceiveNonBlocking(OMElement, String, AxisCallback). Add this method to the SampleClient class to implement asynchronous invocation, as shown below:

// Invoke Non-blocking request-reply MEPSystem.out.println(">> AXIS2 CLIENT: - Async Timeout waiting for reply.");serviceClient.sendReceiveNonBlocking(getEchoOMBlock("AXIS2: "

+ input), callback);

Note: You don’t have to use the non-blocking API to perform transport layer async behavior. You can use a blocking (synchronous) API to accomplish the same behavior.

2. You need to define the AxisCallback object to process the asynchronous response. To do this, add the following code to the SampleClient class:

// Implementing the Axis callback interface to process aysnchronous// response

callback = new AxisCallback() {public void onComplete() {}

public void onError(Exception arg0) {}

public void onFault(MessageContext msgContext) {}

public void onMessage(MessageContext msgContext) {OMElement responseElement =

msgContext.getEnvelope().getBody().getFirstChildWithName(

new

QName(applicationEchoNamespaceName,EchoStringResponse));

OMElement result = responseElement.getFirstChildWithName(new QName(null,

EchoResponse));

...}

};3. Finally, add the following property in the SampleClient class to enable a two-

way, or a one way transport-level behavior, or over-the-wire asynchronous behavior on a traditional two-way HTTP transport protocol.

clientOptions.setTransportInfo(Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, wireasync);

where wireasync is a Boolean variable. A value of true or false indicates whether the related messages will flow on the same channel or on a separate channel (one-way or two-way behavior). True indicates synchronous (two-way) behavior, in which the related messages are communicated on the same channel. False indicates asynchronous (one-way) behavior, in which the related messages are communicated on a separate channel.

Now that you’ve made these changes to the API, you can control how to send and respond to messages in an asynchronous manner. The Axis2 CLI client uses the –w option with a value of yes or no to indicate asynchronous or synchronous communication, respectively.

Test asynchronous over-the-wire interoperability

Now that you’ve successfully configured asynchronous behavior at the transport layer, you’re ready to run the tests for asynchronous over-the-wire behavior for the WSFP and Axis2. Applications using an asynchronous programming model combined with asynchronous behavior at the transport layer reduce Web services messaging complexity and improve performance.

Test WSFP client to WSFP service communication using async over-the-wire to confirm semantic interoperabilityIn this test you will configure the Sample Demo UI client to communicate with the service deployed on the WebSphere Feature Pack Server.

Select Asynchronous Echo with async communication on the WSFP Sample Demo UI to invoke an asynchronous request combined with an asynchronous transport behavior. For instructions on how to do this, see “Test async over-the-wire Application Server to Application Server interoperability” (p. 68, Levay 2007).

Test the Asynchronous Echo scenario with asynchronous over-the-wire behavior in the Axis2 environment as well.

Test Axis2 client to Axis2 service communication using async over-the-wire to confirm semantic interoperability To test the Axis2 client async behavior pointing to an Axis2 service endpoint, enter the following command, as shown in Figure 10.

runSampleAxis2.bat -p 8080 -f /axis2/services/EchoService -m "Axis2 to Axis2 async over-the-wire test" -s async -a y -w y

The –a option with a value y enables WS-Addressing, and the –w option with the value y enables asynchronous behavior at the transport layer.

Figure 10. Axis2 usage example for Async Echo with async behavior to Axis2 service

Test WSFP client to Axis2 service communication using async over-the-wire to confirm technical interoperability Do the following, as shown in Figure 11, to use the Async sample to verify over-the-wireinteroperability from the WSFP to Axis2.

1. Select Asynchronous Echo with Async Communication for Message Type.2. Enter a Message String. In this example, we use WAS to Axis2 Async Echo.3. Specify http://localhost:8080/axis2/services/EchoService for the

Service URI.4. Check Use SOAP 1.2.5. Click Send Message.

Figure 11. Test Application Server to Axis2 async over-the-wire interoperability

You can see the WSFP service output for the request string in the Tomcat Server stdout_<date>.log.

Test Axis2 client to WebSphere service communication using async over-the-wire to confirm technical interoperability Following is an example command to run the over-the-wire interoperability tests using the Async sample from Axis2 to the WSFP endpoint:

runSampleAxis2.bat -p 9087 -f /WSSampleSei/EchoService12 -m "Axis2 to WAS async over-the-wire test" -s async -a y -w y -2

Figure 12 shows the proper usage of the Axis2 client request configured for the async over-the-wire request to a WebSphere service, as shows that it completed successfully.Figure 12. Axis2 usage example for Async Echo with async behavior to WebSphere service

You can see the WebSphere service output for the request string Axis2 to WAS async over-the-wire test in the Application Server SystemOut.log.

You have now successfully completed the asynchronous over-the-wire interoperability tests.

SummaryIn this article, you learned how to use the simple message exchange patterns to exchange messages between two communicating parties. You learned how to exchange messages with different SOAP encodings using different programming models. You also learned how to configure WS-Addressing on two platforms. Finally you learned how to implement asynchronous Web services clients on WebSphere and Axis2. In all these scenarios, you tested interoperability between JAX-WS Web services deployed on WebSphere Application Server and Apache Axis2 Web services. Using the correct programming techniques, policy sets, and Axis2 configurations, you can easily achieve interoperability between these two different Web services platforms.

ResourcesSpecifications

• WSDL 1.1 • SOAP 1.1 • SOAP 1.2 Primer • SOAP 1.2 Specification • WS-Addressing • JAX-WS

Feature Pack for Web Services and developerWorks articles • Feature Pack for Web Services Information center • Achieving Web services interoperability between the WebSphere Web Services

Feature Pack and Windows Communication Foundation, Part 1 (developerWorks 2007)

Apache Axis2 Apache Axis2 User’s Guide: The User’s Guide provides a starting place for users who are new to Apache Axis2. It also covers some advanced topics, such as how to use Axis2 to create and deploy Web services as well as how to use WSDL to generate both clients and services.Apache Axis2 Web Administrator’s Guide: This document gives you detailed information on the administration console of the Apache Axis2 Web application. Apache Axis2 administration is all about configuring Apache Axis2 at run-time, where the configuration is transient.Web Services Messaging with Apache Axis2: Concepts and Techniques: This article explains messaging concepts and how Axis2 can be used to implement several well-known messaging scenarios.

Apache TomcatApache Tomcat 6.0 documentation: This page links to the User’s Guide and other documentation for Apache Tomcat 6.0.

About the authorAndrew A. Das is a Staff Software Engineer and an IBM Certified Web Services Developer. He is part of the WebSphere Application Server Web Services Interoperability development team. His current responsibilities include evaluating Web Services standards and how they interoperate with other IBM products and other vendor products.

Andrew is a graduate of North Carolina State University, in Computer Science. You can reach Andrew at aadas@us.ibm.com.