WebSphere Studio Application Developer (WSAD) includes support for developing SOAP-based Web services. For example, the WSAD Web Services wizard allows you to turn a JavaBean into a SOAP RPC-based Web service with almost no work. In addition, WSAD can create a proxy for the RPC-based Web service, greatly simplifying its use.

Some applications and ser-vices, such as UDDI, require the lower level of control offered by the SOAP message-based model, upon which the RPC-based model is built. Although WSAD doesn't yet provide automated support for SOAP message-based Web services, it's relatively easy to provide manual support in WSAD. This article shows you how to create and use message-based Web services in WSAD.

There are three steps to creating a message-based Web service in WSAD:

1.   Create an RPC-based Web service to automatically create artifacts necessary for describing and deploying the Web service.
2.   Implement the actual message-based service, and modify the Web service artifacts accordingly.
3.   Create a client proxy for the message-based service (optional).

Creating a SOAP RPC Web Service
Using the WSAD Web Services wizard to create an RPC-based Web service minimizes the work involved in creating and deploying the message-based Web service. Since the resulting RPC-based Web service won't be used, it's best to start with a very simple Java class. For this exercise, create a Web project, create a package named "message" in the source folder of the Web project, and then create the bean described in the following code.

package message;
public class MessageService {
public String process(String in) {
return in;
}
}

Expand the Web project that contains the MessageService class, select the class, right click, and select New->Other. On the left side of the resulting dialog, select Web Service on the right side and then select Next to start the Web Services wizard. In the initial panel of the wizard (see Figure 1), uncheck Generate Proxy, uncheck Start Web Service, and then select Finish. The wizard creates the WSDL describing the RPC-based Web service as well as a deployment descriptor. The wizard will also start the application server in which the Web service is deployed.

SOAP Message-Based Web Services
While SOAP RPC Web services can have virtually any signature with multiple operations, SOAP message-based Web services in the Apache SOAP 2.2 implementation included with WSAD all have exactly the same signature, with a single operation, shown in the following code. See the References section for more information.

public class <SOAPMessageService> {
public void process(
Envelope env,
SOAPContext requestContext,
SOAPContext responseContext) {
...
}
}

Modify the signature of the MessageService class and add the functional part of the Web service that implements the message-based Web service. Listing 1 shows the new Web service implementation.

The process() method first gets the body from the SOAP envelope received. The method extracts the request element from the body. At this point in a real service, the class would process the request element, execute the business logic required by the request, and formulate a response (in the form of a DOM Element). This simple example just returns the request.

Next, modify the Web service deployment descriptor (dds.xml) produced by the Web Services wizard. The dds.xml file can be found in the webApplication folder of the Web project containing the Web service. Simply add the attribute type="message" to the <isd:service> element in the deployment descriptor as shown in Listing 2.

After saving the modified deployment descriptor, restart the application server to deploy the Web service and make it available to clients.

Creating a SOAP Message Client Proxy
Creating a proxy for the Web service isn't absolutely necessary, but it simplifies client access to the Web service. Create another package in the source folder of the Web project; this example uses "proxy.soap.message" for the package name. The proxy itself is shown in Listing 3.

The send() method sends the request, in this case in the form of a DOM Element, to the Web service. The send() method uses the createBody() method to wrap the request in a body element with the correct name ("process") and namespace attribute. The "xmlns" attribute identifies the Web service on the server; it should be set equal to the "id" attribute in the element in the deployment descriptor generated by WSAD. The receive() method allows a client to retrieve the response produced by the Web service.

This generic proxy is useful for sending and receiving "free-form" documents because it accepts and returns a DOM Element. It's possible to construct a proxy with a send() method that takes one or more parameters of a specific Java type, e.g., a String, int, etc. Likewise, it's possible to have the receive() method return a specific Java type. A proxy constructed in this fashion must construct the DOM Element sent to the service and parse the DOM Element received from the service.

Creating a SOAP Message Client
Listing 4 shows a client that uses the generalized proxy described above. The best place to create the client is in the default package of the Web project containing the Web service and the proxy.

Since the proxy requires an element as input, the client first creates a simple element named "test" with one attribute named "myAtt". The client then sets the URL for the service implementation; the value should be set to the value of the location attribute of the <service/ port/soap:address> element in the "service" WSDL file generated by WSAD, except that you must substitute "messagerouter" for the "rpcrouter" in the attribute value. The client then sends the request to the service. Since the proxy for the message Web service models an asynchronous operation, the client can now do other things before retrieving the reply. Eventually, the client receives the response from the Web service. This example simply prints the attribute, which should match the attribute in the request. When you run the test client shown in Listing 4, you'll get the following result in the WSAD Console view:

The web service echoed the attribute; the value is "good"

This is exactly what's expected.

Digging Deeper
It's instructive to dig deeper into the operation of the message Web service to discover what's really happening. One way to do this is by examining the SOAP messages flowing between the client and the Web service. WSAD provides the TCP/IP Monitor that can be used for this; see the WSAD Help for more information about the monitor and how to get it running. The application server providing the Web service by default listens on port 8080. Configure the monitor to listen on port 8081 and pass requests to port 8080, then start the monitor. The only change necessary in the test client is to change "8080" in the setURL() call to "8081". Do this and run the client again. You'll see the same result in the Console view, but the monitor captures the request and response so you can examine them in the TCP/IP Monitor view.

Listing 5 shows the request sent by the client proxy. You can see that the body of the request contains the <process> element, which in turn contains the <test> element with its attribute.

Listing 6 shows the response sent as a result of the send() method. The response contains the <test> element with its attribute. You may be surprised to find that the response comes back as a result of the send() method. You can confirm this by putting a breakpoint in the test client before calling the receive() method and running the test client in debug mode.

Summary
This article walked you through the steps necessary to develop message-based Web services with WebSphere Studio Application Developer. While not as well supported as the more widely used RPC-based Web services, this type of Web service can be inplemented and tested with WSAD.

One final note: the intentional split of the send() and receive() methods in the proxy allows a client using the proxy to model asynchronous operations where the send() method starts the Web service, but does not wait for it to finish; instead, the receive() method actually waits for the Web service to finish. In reality, the Web service is synchronous because the Apache SOAP Message.send() method invoked in the proxy is synchronous, so the repsonse actually comes back as a result of the proxy send() method. This means that this client can't operate in an asynchronous manner; it can't do anything until the proxy send() method returns. To really be asynchronous, the proxy must implement some multithreading, which I'll cover in Part 2.

References

• Apache SOAP version v2.3.1: http://xml.apache.org/soap/docs/index.html
• UDDI: http://uddi.org
• Web services zone on IBM developerWorks: www.ibm.com/developerworks/webservices
• IBM developerWorks tutorial, Creating a complete Web service: www.ibm.com/developerworks/training

• Figure 1
• Source Code