First, servlets are responsible for extracting the SOAP contents from another wire packet. The SOAP contents must then be parsed so the servlet can acquire access to the elements and attributes contained within the SOAP document. A servlet must contain the logic for:

Based upon how WSDL, JAXM, and JAX-RPC eventually define the behavior of web services, four fundamental types of messages can be transported over SOAP:

The format and behavior of these transmission primitives are described in more detail in Chapter 5. These primitives provide an intriguing technical challenge for application server architects, however, since servlets were primarily designed to handle client-invoked, request-response behavior. A servlet that supports web services obviously needs to support familiar request-response behavior; however, it must also support server-invoked, solicit-response behavior and other server-initiated invocations.

This topic is technically challenging because a servlet must be engineered to receive asynchronous notifications from other resources located in the same application server. Servlets are invoked synchronously by a wire protocol, but to support asynchronous web services, they need to be engineered to receive asynchronous messages while they execute for inclusion on any outgoing response. Additionally, a servlet is generally thought of as something that reacts to inbound requests passively. It must now also be able to actively generate an outbound SOAP-over-HTTP solicitation. Your SOAP provider is responsible for implementing this servlet behavior. Vendor offerings such as BEA WebLogic Server, SonicXQ, CapeClear Studio, and Systinet WASP all provide these implementations to developers transparently.

After a servlet parses the SOAP message, it needs to either do an RPC-style invocation or deliver the XML message to another resource, such as a JMS destination. Before the servlet can pass processing on to the next resource, though, it must determine what that resource is. How does it do this? A servlet has some options for determining the next step in the process:

One of the interesting problems posed by this scenario is how an application server should handle conversational web services. SOAP, in its basic form, does not have a standardized way to track session tokens. Session tokens are needed to associate a message with an established conversation. For servlets, conversations are associated with a sessionID variable that accompanies every HTTP request. SOAP messages can carry these session tokens, but since no standardized way exists for them to be incorporated into the message, any session enablement of a SOAP message is nonportable. Despite this factor, conversational web services are very important and many vendors are building the extensions needed to support them.

If web services are going to be conversational, then the servlet SOAP handler needs to handle conversations, too. This means that a servlet implementation must figure out whether a message is part of a conversation, where that conversation is managed, and whether any special routing needs to occur as a result of the conversational dynamics.

Mapping web service invocations to EJBs is important because EJBs provide the component framework necessary for implementations of reliable and highly available business logic. EJBs have access to a range of enterprise technologies and provide a portable way to encapsulate the business logic necessary to interact with them. Mapping SOAP to EJBs is important because it allows application developers to continue to develop portal logic solutions for their systems while leveraging the benefits offered by web services. Figure 8-2 depicts the steps involved in generating an EJB invocation from a SOAP message:

Figure 8-2. SOAP-EJB invocation model

This process is pretty straightforward. It’s so simple, in fact, that most vendors now have toolkits that, given an EJB, perform most of these steps automatically. If you have a stateless session EJB, a SOAP handler generator creates the servlet that serves as the SOAP handler, creates the necessary deployment descriptors, and generates any WSDL necessary to map SOAP messages to an EJB. The code generator also creates any Java-XML binding that needs to occur. This process allows EJB developers to develop EJBs to implement their business logic without having to worry about the semantics of SOAP development. It provides a seamless transition from one paradigm to the other. In the next section, we provide pseudocode that shows how a servlet might integrate SOAP and JMS. That pseudocode can be extended to do the same for integrating SOAP and EJBs.

A very important notion for B2B, workflow, and system connectivity is the idea of mapping a WSDL endpoint to a JMS Topic or Queue. The Topic or Queue may have either a Message-Driven Bean or a standalone JMS client registered as a listener.

The interface between a web service and JMS is important because the world out there is “usually connected.” An organization may have many occasionally connected business partners. Legacy systems, which may be designed to move data around via bulk nightly batch processes, need to connect to more modern infrastructures designed to communicate in near-real time. JMS provides reliable asynchronous communication, and thus allows for a loosely coupled distributed architecture in which all parts of a distributed system don’t have to run constantly for the whole system to remain healthy. If you recall, one of the defining characteristics of web services is that they are also loosely coupled. Therefore, mapping web services to JMS is natural and important. Figure 8-3 shows the steps required to receive a SOAP message and, as a result, send a JMS message to a JMS destination.

Figure 8-3. SOAP-JMS invocation model

In Figure 8-3, the SOAP-JMS invocation can begin in two ways. First, a SOAP message sent by a client starts a request/response scenario or a one-way invocation that causes a JMS message to be placed onto a destination. In the second model, a message is placed onto a JMS destination monitored by an outbound SOAP handler. Any messages initiated by a JMS client are converted into SOAP messages and delivered using a solicit-response model.

The same process occurs for the solicit-response model, except that it is initiated by a backend resource that places a JMS message onto a queue monitored by a SOAP protocol handler. The protocol handler must then wait for responses from the clients to which the SOAP message is delivered. In the case of a one-way or notification model, no response is necessary—the rest of the steps are identical. In fact, a truly asynchronous environment may consist entirely of one-way and notification operations.

To demonstrate how integration between web services and J2EE works in practice, we have provided pseudocode that shows how an application server or JMS vendor might create a servlet that receives SOAP messages, parses their content, creates a JMS message, and places that message onto a JMS destination. Since most vendors provide this type of implementation, you will never have to write this code yourself. We provide it to show how things work internally and to give you a better understanding of how web services and J2EE interact:

// JAVA PSEUDO-CODE FOR INTEGRATING A SERVLET WITH SOAP & JMS
// This code is designed to receive a SOAP message and then
// to parse the message and to place that message onto a JMS Queue
//
// NOTE: This class is not compilable and does not have proper
//       Exception handling.  It is just pseudo-code to demonstrate
//       how Servlet / JMS / SOAP can work together.
//
// This servlet is NOT responsible for receiving JMS messages.
// Web Services are loosely coupled, so a separate servlet is
// responsible for checking to see if a response message has been
// delivered onto the response queue.  That receive servlet has to
// be invoked separately to check for the correct contents.
// If the vendor supports asynchronous outbound notifications,
// then polling the servlet for response is not necessary.
// 
import javax.jms.*;
import com.vendor.specific.SOAPMessage;
import com.vendor.specific.SOAPMessageFactory;
  
public class SoapJMSSendServlet extends HttpServlet {
  
    static String SEND_QUEUE_NAME = "SomeQueueName";
    static String QUEUE_CONNECTION_FACTORY = "SomeConnectionFactoryName";
    static String SOAP_MESSAGE_FACTORY = "SomeSoapMessageFactoryName";
    private Destination destination;
    private ConnectionFactory factory;
    private QueueConnection qConnect;
    private QueueSession qSession;
    private QueueSender qSender;
    
    private SOAPMessageFactory smf;
    private SOAPMessage soapMessage, responseMessage;
    private long requestTimeout = 180000; // 30 seconds
  
    public void doPost(HttpServletRequest httpRequest, 
        HttpServletResponse httpResponse) throws ServletException {
  
        // Parse SOAP input from HTTP Stream.
        org.w3c.dom.Document doc 
            = SOAPParser.getDocument(
                new InputSource(httpRequest.getInputStream(  )));
  
        // This representative "SOAPMessage"
        // could be a JAXM-based message, and ApacheSoap kind of message, or an 
        // Axis message.  The important thing to note is that it contains a SOAP 
        // envelope along with any other runtime-specific information that allows 
        // it to be routed appropriately.  The runtime-specific information could
        // be derived from HTTP headers, from SOAP headers, WSDL, or deployment 
        // descriptors
        soapMessage = smf.createSOAPMessage(doc, request);
  
        if (soapMessage.isRPC(  ))
            responseMessage = callEJB(soapMessage);
        else if (soapMessage.isJMSSender(  ))
            responseMessage = sendToQueue(soapMessage);
  
        // We have to send a SOAP response to the client informing them
        // of the success.
        if (responseMessage != null)
            responseMessage.write(httpResponse.getOutputStream(  ));
    }
  
    // this method converts the SOAPMessage into a JMS message and places it onto
    // a JMS queue.  If the message is supposed to be participating in a
    // synchronous request/reply, then it blocks and waits for the reply
    // to be received, or a timer expires - whatever comes first.
    private SOAPMessage sendToQueue(SOAPMessage soapMessage)
                        throws ServletException  {
        SOAPMessage responseMessage = null;
  
        // This hypothetical SOAPMessage knows how to marshall itself 
        // into a JMS Message
        qSender.send(soapMessage.createJMSMessage(  ));
  
        // This could be a request/response
        if (soapMessage.needsReply(  )){
            // receive blocks until either a message is received,
            // or timeout occurs.  If timeout occurs, msg is null
            javax.jms.Message msg = qReceiver.receive(requestTimeout);
  
            if (msg == null)
                // generate fault.  This hypothetical SOAPMessage has a 
                // static method for doing that
                responseMessage 
                    = SOAPMessage.createSOAPFault("Request Timed out");
            else
                // The SOAPMessage can also create a SOAP envelope 
                // from a JMS message
                responseMessage = SOAPMessage.createSOAPMessage(msg);
        }
        else
            responseMessage 
                = SOAPMessage.createSOAPMessage("Message Delivered");
        return responseMessage;
    }
  
    public void init(  ) throws ServletException {
        // Set up Queue—only needs to occur once.
        InitialContext ctx = new InitialContext(  );
        factory 
            = (ConnectionFactory)ctx.lookup(QUEUE_CONNECTION_FACTORY);
        destination = (Destination)ctx.lookup(SEND_QUEUE_NAME);
        smf = (SoapMessageFactory)ctx.lookup(SOAP_MESSAGE_FACTORY);
        qConnect = factory.createQueueConnection(username, passwd);
        qSession
            = qConnect.createQueueSession(false, 
                    javax.jms.Session.AUTO_ACKNOWLEDGE);
        qSender = qs.createSender(destination);
    }
}

The code provided here is a standard servlet that acts as a JMS message producer. We’ll look at a few of the more interesting pieces in detail. Since SOAP over HTTP has just the SOAP payload as part of the HTTP request, the servlet accesses the SOAP envelope by using the HttpServletRequest object and the InputStream by using the getInputStream( ) method. The contents of this method are then passed into a SOAP parser. In this example, a SOAPParser object represents the SOAP parser:

        // Parse SOAP input from HTTP Stream.
        org.w3c.dom.Document doc 
            = SOAPParser.getDocument(
                new InputSource(httpRequest.getInputStream(  )));
        soapMessage = smf.createSOAPMessage(doc, request);

This representative SOAP message could be based on JAXM, JAX-RPC, Apache SOAP, or Axis. The important thing to note is that it contains a SOAP envelope along with any other runtime-specific information that allows it to be routed appropriately. Since the XML in the SOAP message could represent a message that will be placed on the JMS queue or topic, an RPC invocation, or something else, our hypothetical SOAP message has an isRPC( ) and an isJMSSender( ) method for determining how to dispatch the message. The dispatching information could be derived from HTTP headers, SOAP headers, WSDL, or deployment descriptors.

        if (soapMessage.isRPC(  ))
            responseMessage = callEJB(soapMessage);
        else if (soapMessage.isJMSSender(  ))
            responseMessage = sendToQueue(soapMessage);

The callEJB( ) method simply deserializes the method name and its parameters, invokes the appropriate EJB, and then sends the response back. In J2EE 1.4, this method will be based on the rules defined by JAX-RPC.

The sendToQueue( ) method needs more explanation since it is a bit more complicated. It can send the message and optionally wait for a synchronous reply. We will see the JMS replier side in a moment. For the purpose of our pseudocode example, let’s assume that the createJMSMessage( ) creates a JMS message and marshals the SOAP content into it. It doesn’t matter what the type is, as long as sufficient APIs are on either side (for accessing the message by using JMS APIs and accessing the XML content by using JAXP or SOAP Envelope APIs). The JMS message is created and sent to its destination:

    private SOAPMessage sendToQueue(SOAPMessage soapMessage)
                         throws ServletException  {
        SOAPMessage responseMessage = null;

        // This fictitous SOAPMessage knows how to marshall itself 
        // into a JMS Message
        qSender.send(soapMessage.createJMSMessage(  ));

Next, the SOAP message also knows enough about itself to determine whether it should be an asynchronous send( ) or a synchronous request/reply operation. If a reply is expected, the QueueReceiver.receive( ) blocks until a message is returned or a timeout occurs. The timeout is important because we must satisfy the HTTP request with either a response message or a Fault message before the HTTP request itself times out:

            // This could be a request/response
            if (soapMessage.needsReply(  )){
                // receive blocks until either a message is received,
                // or timeout occurs.  If timeout occurs, msg is null
                javax.jms.Message msg = qReceiver.receive(requestTimeout);
  
                if (msg == null)
                    // generate fault.  This hypothetical SOAPMessage has a 
                    // static method for doing that
                    responseMessage 
                        = SOAPMessage.createSOAPFault("Request Timed out");
                else
                    // The SOAPMessage can also create a SOAP envelope 
                    // from a JMS message
                    responseMessage = SOAPMessage.createSOAPMessage(msg);
            }
    else
        responseMessage 
            = SOAPMessage.createSOAPMessage("Message Delivered");
    return responseMessage;
}

In JMS, an asynchronous response might result from this message. However, the “response” may not happen immediately. It may occur hours or days after the request, or the “response” may be just another message delivered to a new destination that is not related to the SOAP client that initiated the request. This servlet is responsible only for retrieving any JMS response messages that might be created for an immediate synchronous response. To handle the other situations, there are other possibilities:

public class PsuedoJMSSoapReplier
    implements javax.jms.MessageListener
{
// ...
    public void onMessage( javax.jms.Message aMessage)
    {
        if (aMessage instanceof SOAPMessage)
        {
            SOAPMessage sMsg = (SOAPMessage)aMessage;
                
            int partCount = sMsg.getPartCount(  );
            //Display number of parts in multipart message
            System.out.println("MultipartMessage received with : " 
                + partCount + " parts");
            
            Part part = null;
            for(int i = 0; i < partCount; i++)
            {   
                part = sMsg.getPart(i);
                System.out.println("Multipart message part(" + i 
                    + ") has content type: "
                    +  part.getHeader().getContentType(  ));
                System.out.println("Multipart message part(" + i 
                    + ") has size: " 
                    + part.getContentBytes(  ).length + " bytes");
            }
            org.w3c.dom.Document doc 
                = SOAPParser.getDocument(
                    new InputSource(sMsg.getPart(0).getInputStream(  )));
  
            if (doc == null) 
            {
                throw new org.apache.soap.SOAPException (
                    org.apache.soap.Constants.FAULT_CODE_CLIENT, "parsing error");
            }
  
            //Validate the XMLMessage content using Apache SOAP
            org.apache.soap.Envelope msgEnv = 
                org.apache.soap.Envelope.unmarshall (doc.getDocumentElement(  ));
  
            //... Do SOAP Envelope things....
  
            System.out.println("Successfully processed MultipartMessage");
        }

        // Check for a ReplyTo Queue and send one if necessary
        javax.jms.Queue replyQueue = (javax.jms.Queue) aMessage.getJMSReplyTo(  );
        if (replyQueue != null){
            // create reply message and send it.
        }else{
            // create a new SOAP message to go to another destination
            String urlEndpoint = sMsg.getNextURLEndpoint(  );
            ...
        }
    }
}

In an enterprise environment, the processing of SOAP requests often doesn’t fit a simple request/response model involving a simple servlet interaction; the servlet model doesn’t necessarily work well for a multistep workflow web service. In this section, we will describe how J2EE technologies such as servlets, JMS, and EJB can be used together with XML-related technologies to orchestrate a multistep complex business process that supports the implementation of a web service.

Consider a company that exposes its business interface to its customers as a web service. It regularly receives purchase orders for its goods from any number of prospective buyers. Figure 8-4 shows the complex chain of events that occurs when a purchase order is received. The purchase order may come into the system as a SOAP message over the HTTP protocol. Upon arriving at the servlet or the SOAP processor, the message may be sent immediately to a routing service that uses an XPATH expression such as /PurchaseOrder/Items to identify that it is indeed a purchase order. If the routing service uses a parser that supports JavaScript extensions, then additional logic may be plugged into the routing service to do some real-time expression evaluation.

Figure 8-4. Content-based routing, XSLT transformation, and J2EE connectors

The routing service may then determine that this purchase order is valid and needs to proceed to the next step in the process—performing a credit authorization. It sends the purchase order on to the next step by placing a message onto a JMS queue. The credit authorization service listening on that queue may run some business logic and choose to delegate its credit checking responsibility to another external web service. To accomplish this delegation, it may make a direct SOAP call over an HTTP connection or choose to create a new JMS message and place it on a queue destination that is mapped to an outbound SOAP-over-HTTP handler. If that request for credit approval is denied, then a “credit denied” message is sent back to the sender, either synchronously or asynchronously, depending on how the whole service is described in WSDL.

If the credit check is successful, the next step may be to execute some business logic by invoking an EJB—directly as a synchronous call or asynchronously by sending a message to a message-driven bean listening on a queue. The business logic might break the purchase order into its respective line items and send each item to the legacy fulfillment application (EIS) that resides at the remote warehouse. In the process, several things need to happen: the purchase order’s line items must be broken into separate requests, the data must be converted from XML into the proprietary format that is used by the EIS, and the logic must communicate with the EIS in a standardized way.

The breaking of <Items> into multiple entries and the transformation from XML into the legacy format required by the EIS are both accomplished by routing the purchase order to a special XSLT-based translation service. Given the appropriate style sheet, we can rely on the parser to do most of the work.

The next step, communicating with the EIS, is accomplished by using a connector, as defined by the J2EE Connector Architecture. In Figure 8-4, the implementation of the connector may reside in the local container, at the remote location, or it may be spread across both places. After the processing is complete, a final SOAP response message may be generated to travel back to the sender, using similar processes.

Unfortunately, although integration between J2EE and web services has matured among many of the providers, the Java Community Process (JCP) has not yet standardized it. JSR109, “Implementing Enterprise Web Services,” is intended to provide a standardized approach for J2EE/web services integration. Unfortunately, as of early 2002, JSR109 has stalled, and may not be delivered to the public until the middle of 2002. This means that any vendor implementations following the standard probably won’t be fully realized until 2003 or 2004. That is a very long time, given the pace at which technology tends to mature.

One positive, note, however, is the expectation that the contents of JSR109 will be incorporated into J2EE 1.4, forcing application server vendors to provide a standardized level of web services support by 2003.

JSR109 is expected to cover several things. Everything is in flux at this point, but some of the highlights appear to be: