Book Excerpt

The last chapter introduced simple SOAP messaging. In this chapter, we move to the next level of sophistication and introduce a true messaging framework that forms the backbone of the EAI infrastructure developed in this book. This messaging framework enables Java applications to send and receive Java objects to and from web services using SOAP as the transport. It also enables asynchronous messaging whereby the sender of a message does not have to block waiting for the receiver to process it. We call our framework the Web Services Messaging Framework (WSMF). It is implemented using J2EE and Web Services standards and serves as the core messaging service used by all the non-JMS EAI applications developed in the remainder of this book.

The WSMF is not a commercial-quality messaging framework, but rather an illustrative example of how to implement Web Services oriented messaging within the J2EE environment. In this chapter, you will encounter the major issues associated with implementing SOAP messaging in Java and some solutions that can be applied to your own EAI projects.

Our WSMF is implemented using the Java API for XML-based RPC (JAX-RPC). As the reader is probably aware, JAX-RPC was created to provide Java developers with a standard for incorporating into Java applications the XML-based Remote Procedure Call (RPC) functionality described in Section 7 of the SOAP 1.1 specification. JAX-RPC was not intended for messaging. The reasons that we have chosen JAX-RPC as the standard for our messaging framework are discussed in Section 1.1.

In addition to JAX-RPC, this chapter introduces two additional standards: JAXB and WSDL. The Java Architecture for XML Binding (JAXB) provides a standard approach, based on XML Schema, for serializing and deserializing between XML documents and Java objects. The Web Services Description Language (WSDL) is a W3C standard interface definition language for specifying web services APIs using XML. Typically, a web services client reads the WSDL to determine how to structure SOAP messages that can be accepted as valid requests by the service.

This chapter assumes that the reader has a basic familiarity with JAX-RPC and WSDL. If you have never encountered JAXB, that should not be a problem. You can probably pick it up as you read through the material presented here. If you need to brush up on any of these standards, the author suggests Sun's Java Web Services Tutorial (java.sun.com/webservices/docs/1.4/tutorial/doc/index.html) for JAX-RPC and JAXB. For WSDL, we suggest that you read through the specification (www.w3.org/TR/wsdl). It is not very long and provides a lot of illustrative examples.

5.1 JAX-RPC for Messaging
With some misgivings, we have implemented the WSMF using JAX-RPC. As you will see in this chapter, JAX-RPC, at least the current version 1.0, has many shortcomings as a standard for messaging. The primary design goal for the initial release of JAX-RPC seems to have been enabling RMI-like remote procedure calls (RPCs) using SOAP over HTTP.

Another standard, JAXM, has been developed specifically for XML messaging. However, because JAX-RPC is a required part of the J2EE platform (starting with version 1.4) and the JAXM standard is optional, we believe that a messaging framework based on JAX-RPC is easier to introduce into a corporate Java environment. Any IT department supporting J2EE must support JAX-RPC. Therefore, any code you develop using the techniques illustrated in this chapter should be usable in a corporate Java environment.

As an interesting aside, you may be wondering why there is no true messaging standard for Web Services included in the J2EE standard (at least at the time of this writing). I.e., why is JAXM not included in the J2EE standard? The reason is that many of the vendors driving Java standards (e.g., IBM, BEA, Fujitsu) feel that J2EE already supports enough messaging standards. As IBM wrote in casting their vote against final approval of JSR #67 (JAXM): We are significantly concerned that the introduction of JAX-M as yet another API for calling a service (along with RMI-IIOP, JMS, and the proposed JAX-RPC) is unnecessarily complicating the Java programming model for our developers.

As a result of this decision, we need to work a little harder to implement Web Services messaging within the J2EE framework. This is not all bad, however, because it gives us an opportunity to gain a detailed understanding of the important JAX-RPC standard.

The JAX-RPC 1.0 specification is long and fairly complex. You don't need to understand the entire standard to learn how to use it for messaging. The approach that we suggest is to start working through the examples in this chapter and refer back to the JAX-RPC Javadoc API and specification as necessary.

When reviewing JAX-RPC, you should focus on these features, which are used by the WSMF:

• SOAP message support and the SOAP 1.1 binding including SOAP faults (JAX-RPC 1.0 Specification Section 6)
• WSDL interface definitions of services and their Java representations (JAX-RPC 1.0 Specification Sections 4 and 5)
• Dynamic invocation of operations on service endpoints (JAX-RPC 1.0 Specification Section 8)
• SOAP Message Handlers (JAX-RPC 1.0 Specification Section 12)

We also develop some workarounds to avoid the JAX-RPC Type Mapping Framework. Version 2.0 of JAX-RPC is going to replace 1.0 type mapping with JAXB, so we don't want to invest much effort incorporating it into our messaging platform. Indeed, as you will see, part of what makes JAX-RPC a bit clumsy as a messaging framework is its built-in [de]serialization between Java types and XML. Throughout this chapter, we call this the JAX-RPC embedded type mapping. (Be aware that this is our phrase and not standard industry terminology.) Within our WSMF, we "turn off" the embedded type mapping and substitute the Java API for XML Binding (JAXB). JAX-RPC 2.0 promises improved type mapping and support for JAXB, but as of this writing, work on version 2.0 is just starting.

In the following sections, we look at each of these features and discuss how they are used to implement the WSMF. Sections 1.2 and 1.3 illustrate how JAX-RPC support for the SOAP 1.1 binding is leveraged to facilitate communication with Web Services using SOAP over HTTP. We first look at simple one-way messaging and then at request-response. Section Error! Reference source not found. introduces the server side framework for implementing messaging services. Section Error! Reference source not found. shows how WSDL is used to describe messaging services. We also look at how JAX-RPC uses WSDL descriptions to create client side representations of services. Section Error! Reference source not found. discusses how and why we use custom XML/Java bindings (e.g., JAXB) with JAX-RPC. Lastly, Section Error! Reference source not found. ties this all together and demonstrates a sample application that uses the WSMF.

5.2 One-Way Messaging Using JAX-RPC (Client Side)
To start off, we consider the straightforward case of one-way messaging. In this scenario, the sender transmits a message to the receiver, but does not receive a response back. Often times, but not always, this scenario assumes that the receiver processes the message asynchronously - i.e., the client does not block until the receiver finishes processing. To be clear, we distinguish between one-way blocking and one-way non-blocking messaging.

Figure 5-1 illustrates how One-Way Messaging is implemented using JAX-RPC. This figure traces the journey of a message object from sender to receiver and is accurate for both the blocking and non-blocking scenarios. In either case, something may come back to the sender at a lower protocol level, e.g., a simple HTTP ACK, an empty SOAP message, or a SOAP fault. That depends on the implementation details, which we get in to later. What defines one-way messaging is that no response is returned at the message level. Here the term message refers to the contents of the SOAP body and not the SOAP document itself. In Section Error! Reference source not found. we will see that an equivalent definition says that a message service is one-way if and only if it's WSDL port type specifies a one-way operation. As illustrated, one-way messaging involves these steps.

1. The message to send exists as an instance of a java class that can be serialized, i.e., marshaled, to XML that the receiver can process. Section Error! Reference source not found. describes how marshalling / unmarshalling is handled within WSMF. Throughout this chapter, we refer to such a class as MsgClass.
2. The instance of MsgClass is passed as a parameter to the OneWayClient interface method sendMessage(). One-way messaging clients in the WSMF must implement the com.javector.ws.OneWayClient interface (shown in Example 5-1 below) by extending the class com.javector.ws.jaxrpc.JAXRPCClient.
3. Within the JAXRPCClient instance, the message is marshaled to an implementation of org.w3c.dom.Element. The JAX-RPC interfaces, in particular, the Call.invoke() or Call.invokeOneWay methods, are used to send the message to the receiver.
4. The runtime implementation of JAX-RPC (e.g., Apache Axis) on the client now takes our message as an org.w3c.dom.Ele ment and serializes it into a SOAP document that is sent across the wire (e.g. HTTP over TCP/IP) to the receiver. Although it is not spelled out in the JAX-RPC specification, we assume that all JAX-RPC implementations can serialize an org.w3c.dom.Element into the body of a SOAP document.
5. The message is received and processed by the web service.

Example 5-1 below shows the OneWayClient interface. Note that the return type of sendMessage() is void, i.e., no response message is returned. Implementations of this interface may be blocking or non-blocking as discussed above. In addition to the message object, the method's parameters include the WSDL port and operation names. Beyond just the port and operation names, however, JAX-RPC requires the URI and name of the target service in order to instantiate a client side representation of a web service. For this reason, OneWayClient should be implemented by extending JAXRPCClient (discussed in Section Error! Reference source not found.). The JAXRPCClient class maps to a WSDL service and supplies the JAX-RPC run time implementation with this additional information. If you have read a little bit about JAX-RPC at this point, you can see that the OneWayClient interface gets mapped to a JAX-RPC javax.xml. rpc.Call interface.

Example 5-1 Interface for One-Way Messaging

  3   package com.javector.ws;
  4  
  5   public interface OneWayClient {
  6   
  7   // ----------------------------------Public Methods
  8 
  9   /**
 10   * Sends a message object to a service that does not return
 11   * anything. This method can be used to call asynchronous
 12   * message services.
 13   *
 14   * @param msgObject The message to be sent
 15   * @param portName the qualified name of the WSDL port that
 16   * contains the operation for receiving the message
 17   * @param operationName qualified name of the WSDL operation
 18   * on the specified port that accepts the message
 19   */
 20   public void sendMessage
 21   (Object msgObject, String
 		    portName, String operationName)
 22   throws Exception;
 23   
 24   }
      com/javector/ws/OneWayClient.java

In this section, we have introduced the simple OneWayClient interface which will be used throughout the rest of this book for web services messaging. Although JAX-RPC is complex, because we are focused on messaging, we can simplify our client-side API down to a couple of interfaces. The next section discusses the interface for Request-Response messaging.

5.3 Request-response Messaging Using JAX-RPC (Client Side)
Request-Response messaging works the same as One-Way except that the client receives a response message from the web service. As with One-Way, Request-Response messaging can be blocking or non-blocking. Most of us think of Request-Response over SOAP as being implemented as a "SOAP for RPC" application where the request message is carried on the HTTP request and the response message comes back on the corresponding HTTP response. This is the most common scenario, and it implies a blocking client that returns only after the response has been received. However, there are many situations where it is not practical or efficient to block for the response message. These non-blocking scenarios are covered in detail in Chapter 6 - Reliable Messaging. In this chapter, we restrict our consideration of Request-Response to the blocking scenario.

As shown in Figure 5-2 steps 1-5 of the Request-Response messaging are the same as in the One-Way scenario. Steps 6-9 trace the response message which follows a slightly different path depending on whether it is a fault or a response. Where a fault message is deserialized according to the JAX-RPC implementation's embedded type mapping, a response message gets deserialized by a special handler. This handler is discussed in detail in Section Error! Reference source not found. The response steps are as follows:

6. The web service sends either a fault or a response as XML within the body of a SOAP document. If it is a fault, then the structure of the SOAP document is as defined in Section 4.4 of the SOAP 1.1 specification. Otherwise, the response is the single child element of the SOAP body. When the SOAP document is received by the JAX-RPC implementation, the processing depends on whether it represents a fault or a response.
7. If the SOAP document is a response, it is processed by an instance of the class JAXRPCClientHandler, that implements the JAX-RPC javax.xml.rpc.handler.Handler interface. This handler extracts the response message as an instance of org.w3c.dom.Element and hands it to the JAXRPCClient instance to be unmarshalled to a Java object as per the XML binding that has been implemented.
8. On the other hand, if the SOAP document is a fault, it is not processed by the handler. Instead, the JAX-RPC implementation extracts the fault and throws it as an instance of SOAPFaultException. This exception, in turn, is thrown by the method sendRequest().
9. In this manner, the method sendRequest() either returns an Object containing the response or throws a SOAPFaultException containing the fault.

Example 5-2 below shows the RequestResponseClient interface. It is identical to OneWayClient except that it returns an Object instead of void. Within the WSMF, the RequestResponseClient interface is implemented by JAXRPCClient.

  3  package com.javector.ws;
  4 
  5  public interface RequestResponseClient {
  6   
  7    // ----------------------------------Public Methods
  8 
  9    /**
 10    * Sends a message object synchronously and returns the
 11    * response object that it receives from the remote
 12    * service.
 13    *
 14    * @param requestObject The request to be sent
 15    * @param portName the qualified name of the WSDL port that
 16    * contains the operation for receiving the message
 17    * @param operationName qualified name of the WSDL operation
 18    * on the specified port that accepts the message
 19    * @return the response received from the remote service
 20    */
 21    public Object sendRequest
 22    (Object requestObj, String portName, String operationName)
 23    throws Exception;
 24  
 25    }
       com/javector/ws/RequestResponseClient.java

Example 5-2 Interface for Request-Response Messaging
Sections 1.2 and 1.3 have provided an overview of how client side messaging with JAX-RPC is structured in the WSMF. Before getting into the client side details, we use the next section to get a quick overview of how we can write web services in Java.

About the Article
This article is excerpted from a chapter within the forthcoming, November 2004 book, EAI with Web Services and Java, by Mark D. Hansen, ISBN 0-13-044968-7. This chapter is printed with permission from publisher Prentice Hall PTR, copyright 2005. This book can be pre-ordered at Amazon or BN.com.