10 Creating and Using SOAP Message Handlers

Overview of SOAP Message Handlers

Web services and their clients may need to access the SOAP message for additional processing of the message request or response. You can create SOAP message handlers to enable Web services and clients to perform this additional processing on the SOAP message. A SOAP message handler provides a mechanism for intercepting the SOAP message in both the request and response of the Web service.

A simple example of using handlers is to access information in the header part of the SOAP message. You can use the SOAP header to store Web service specific information and then use handlers to manipulate it.

You can also use SOAP message handlers to improve the performance of your Web service. After your Web service has been deployed for a while, you might discover that many consumers invoke it with the same parameters. You could improve the performance of your Web service by caching the results of popular invokes of the Web service (assuming the results are static) and immediately returning these results when appropriate, without ever invoking the back-end components that implement the Web service. You implement this performance improvement by using handlers to check the request SOAP message to see if it contains the popular parameters.

JAX-WS supports two types of SOAP message handlers: SOAP handlers and logical handlers. SOAP handlers can access the entire SOAP message, including the message headers and body. Logical handlers can access the payload of the message only, and cannot change any protocol-specific information (like headers) in a message.

Adding Server-side SOAP Message Handlers: Main Steps

The following procedure describes the high-level steps to add SOAP message handlers to your Web service.

It is assumed that you have created a basic JWS file that implements a Web service and that you want to update the Web service by adding SOAP message handlers and handler chains. It is also assumed that you have set up an Ant-based development environment and that you have a working build.xml file that includes a target for running the jwsc Ant task. For more information, see in Getting Started With JAX-WS Web Services for Oracle WebLogic Server:

• Use Cases and Examples

• Developing WebLogic Web Services

• Programming the JWS File

• Invoking Web Services

Adding Client-side SOAP Message Handlers: Main Steps

You can configure client-side SOAP message handlers for both stand-alone clients and clients that run inside of WebLogic Server. You create the actual Java client-side handler in the same way you create a server-side handler (by creating a Java class that implements the SOAP message handler interface). In many cases you can use the exact same handler class on both the Web service running on WebLogic Server and the client applications that invoke the Web service. For example, you can write a generic logging handler class that logs all sent and received SOAP messages, both for the server and for the client.

The following procedure describes the high-level steps to add client-side SOAP message handlers to the client application that invokes a Web service operation.

It is assumed that you have created the client application that invokes a deployed Web service, and that you want to update the client application by adding client-side SOAP message handlers and handler chains. It is also assumed that you have set up an Ant-based development environment and that you have a working build.xml file that includes a target for running the clientgen Ant task. For more information, see "Invoking a Web service from a Stand-alone Client: Main Steps" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server.

prompt> ant build-client

When you next run the client application, the SOAP messaging handlers listed in the configuration file automatically execute before the SOAP request message is sent and after the response is received.

Designing the SOAP Message Handlers and Handler Chains

When designing your SOAP message handlers, you must decide:

• The number of handlers needed to perform the work.

• The sequence of execution.

You group SOAP message handlers together in a handler chain. Each handler in a handler chain may define methods for both inbound and outbound messages.

Typically, each SOAP message handler defines a separate set of steps to process the request and response SOAP message because the same type of processing typically must happen for the inbound and outbound message. You can, however, design a handler that processes only the SOAP request and does no equivalent processing of the response. You can also choose not to invoke the next handler in the handler chain and send an immediate response to the client application at any point.

Server-side Handler Execution

When invoking a Web service, WebLogic Server executes handlers as follows:

1. The inbound methods for handlers in the handler chain are all executed in the order specified by the JWS annotation. Any of these inbound methods might change the SOAP message request.

2. When the last handler in the handler chain executes, WebLogic Server invokes the back-end component that implements the Web service, passing it the final SOAP message request.

3. When the back-end component has finished executing, the outbound methods of the handlers in the handler chain are executed in the reverse order specified by the JWS annotation. Any of these outbound methods might change the SOAP message response.

4. When the first handler in the handler chain executes, WebLogic Server returns the final SOAP message response to the client application that invoked the Web service.

For example, assume that you are going to use the @HandlerChain JWS annotation in your JWS file to specify an external configuration file, and the configuration file defines a handler chain called SimpleChain that contains three handlers, as shown in the following sample:

<?xml version="1.0" encoding="UTF-8" ?> 
<handler-chains xmlns="http://java.sun.com/xml/ns/javaee"> 
   <handler-chain> 
      <handler> 
         <handler-class>
            Handler1
         </handler-class> 
      </handler> 
   </handler-chain> 
   <handler-chain> 
      <handler> 
         <handler-class>
            Handler2
         </handler-class> 
      </handler> 
   </handler-chain> 
   <handler-chain> 
      <handler> 
         <handler-class>
            Handler3
         </handler-class> 
      </handler> 
   </handler-chain> 
</handler-chains>

The following graphic shows the order in which WebLogic Server executes the inbound and outbound methods of each handler.

Figure 10-1 Order of Execution of Handler Methods

Creating the SOAP Message Handler

There are two types of SOAP message handlers that you can create, as defined in the following table.

Each type of message handler extends the javax.xml.ws.Handler interface (see http://java.sun.com/javase/6/docs/api/javax/xml/ws/handler/Handler.html), which defines the methods defined in the following table.

handleMessage()

handleFault()

close()

In addition, you can use the @javax.annotation.PostConstruct and @javax.annotation.PreDestroy annotations to identify methods that must be executed after the handler is created and before the handler is destroyed, respectively.

Sometimes you might need to directly view or update the SOAP message from within your handler, in particular when handling attachments, such as image. In this case, use the javax.xml.soap.SOAPMessage abstract class, which is part of the SOAP With Attachments API for Java 1.1 (SAAJ) specification at http://java.sun.com/webservices/saaj/docs.html For details, see Directly Manipulating the SOAP Request and Response Message Using SAAJ.

package examples.webservices.handler;

import java.util.Set;
import java.util.Collections;
import javax.xml.namespace.QName;
import javax.xml.ws.handler.soap.SOAPHandler;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.soap.SOAPMessageContext;
import javax.xml.soap.SOAPMessage;

public class Handler1 implements SOAPHandler<SOAPMessageContext>
{
  public Set<QName> getHeaders()
  {
    return Collections.emptySet();
  }

  public boolean handleMessage(SOAPMessageContext messageContext)
  {
     Boolean outboundProperty = (Boolean)
         messageContext.get (MessageContext.MESSAGE_OUTBOUND_PROPERTY);

     if (outboundProperty.booleanValue()) {
         System.out.println("\nOutbound message:");
     } else {
         System.out.println("\nInbound message:");
     }

     System.out.println("** Response: "+messageContext.getMessage().toString());
    return true;
  }

  public boolean handleFault(SOAPMessageContext messageContext)
  {
    return true;
  }

  public void close(MessageContext messageContext)
  {
  }
}

package examples.webservices.handler;

import java.util.Set;
import java.util.Collections;
import javax.xml.namespace.QName;
import javax.xml.ws.handler.LogicalHandler;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.LogicalMessageContext;
import javax.xml.ws.LogicalMessage;
import javax.xml.transform.Source;

public class Handler2 implements LogicalHandler<LogicalMessageContext>
{
  public Set<QName> getHeaders()
  {
    return Collections.emptySet();
  }

  public boolean handleMessage(LogicalMessageContext messageContext)
  {
     Boolean outboundProperty = (Boolean)
         messageContext.get (MessageContext.MESSAGE_OUTBOUND_PROPERTY);
     if (outboundProperty.booleanValue()) {
            System.out.println("\nOutbound message:");
     } else {
            System.out.println("\nInbound message:");
     }

    System.out.println("** Response: "+messageContext.getMessage().toString());
    return true;
  }

  public boolean handleFault(LogicalMessageContext messageContext)
  {
    return true;
  }

  public void close(MessageContext messageContext)
  {
  }
}

public boolean handleMessage(C context) 
  throws java.lang.RuntimeException, java.xml.ws.ProtocolException {}

public boolean handleFault(C context) 
  throws java.lang.RuntimeException, java.xml.ws.ProtocolException{}

public boolean close(MessageContext context) {}

javax.xml.ws.handler.LogicalMessageContext

javax.xml.ws.handler.soap.SOAPMessageContext

getMessage()

getHeaders()

getMessage()

getRoles()

setMessage()

SOAPMessage soapMessage =  messageContext.getMessage();
SOAPPart soapPart = soapMessage.getSOAPPart();
SOAPEnvelope soapEnvelope = soapPart.getEnvelope();
SOAPBody soapBody = soapEnvelope.getBody();
SOAPHeader soapHeader = soapEnvelope.getHeader(); 

addAttachmentPart()

countAttachments()

createAttachmentPart()

getAttachments()

Configuring Handler Chains in the JWS File

The @javax.jws.HandlerChain annotation (also called @HandlerChain in this chapter for simplicity) enables you to configure a handler chain for a Web service. Use the file attribute to specify an external file that contains the configuration of the handler chain you want to associate with the Web service. The configuration includes the list of handlers in the chain, the order in which they execute, the initialization parameters, and so on.

The following JWS file shows an example of using the @HandlerChain annotation; the relevant Java code is shown in bold:

package examples.webservices.handler;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.HandlerChain; 
import javax.annotation.Resource;
import javax.xml.ws.WebServiceContext;
@WebService(name = "Handler", targetNamespace = "http://example.org")
@HandlerChain(file="handler-chain.xml") 
public class HandlerWS
{
  @Resource
  WebServiceContext ctx;
  @WebMethod()
  public String getProperty(String propertyName)
  {
    return (String) ctx.getMessageContext().get(propertyName);
  }
}

Before you use the @HandlerChain annotation, you must import it into your JWS file, as shown above.

Use the file attribute of the @HandlerChain annotation to specify the name of the external file that contains configuration information for the handler chain. The value of this attribute is a URL, which may be relative or absolute. Relative URLs are relative to the location of the JWS file at the time you run the jwsc Ant task to compile the file.

For details about creating the external configuration file, see Creating the Handler Chain Configuration File.

For additional detailed information about the standard JWS annotations discussed in this section, see the Web services Metadata for the Java Platform specification at http://www.jcp.org/en/jsr/detail?id=181.

Creating the Handler Chain Configuration File

As described in the previous section, you use the @HandlerChain annotation in your JWS file to associate a handler chain with a Web service. You must create the handler chain file that consists of an external configuration file that specifies the list of handlers in the handler chain, the order in which they execute, the initialization parameters, and so on.

Because this file is external to the JWS file, you can configure multiple Web services to use this single configuration file to standardize the handler configuration file for all Web services in your enterprise. Additionally, you can change the configuration of the handler chains without needing to recompile all your Web services.

The configuration file uses XML to list one or more handler chains, as shown in the following simple example:

<?xml version="1.0" encoding="UTF-8"?>
<handler-chains xmlns="http://java.sun.com/xml/ns/javaee">
  <handler-chain>
    <handler>
      <handler-class>examples.webservices.handler.Handler1</handler-class>
    </handler>
  </handler-chain>
  <handler-chain>
    <handler>
      <handler-class>examples.webservices.handler.Handler2</handler-class>
    </handler>
  </handler-chain>
</handler-chains>

In the example, the handler chain contains two handlers implemented with the class names specified with the <handler-class> element. The two handlers execute in forward order before the relevant Web service operation executes, and in reverse order after the operation executes.

Use the <init-param> and <soap-role>child elements of the <handler> element to specify the handler initialization parameters and SOAP roles implemented by the handler, respectively.

You can include logical and SOAP handlers in the same handler chain. At runtime, the handler chain is re-ordered so that all logical handlers are executed before SOAP handlers for an outbound message, and vice versa for an inbound message.

For the XML Schema that defines the external configuration file, additional information about creating it, and additional examples, see the Web services Metadata for the Java Platform specification at http://www.jcp.org/en/jsr/detail?id=181.

Compiling and Rebuilding the Web Service

It is assumed in this section that you have a working build.xml Ant file that compiles and builds your Web service, and you want to update the build file to include handler chain. See "Developing WebLogic Web Services" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server for information on creating this build.xml file.

Follow these guidelines to update your development environment to include message handler compilation and building:

• After you have updated the JWS file with the @HandlerChain annotation, you must rerun the jwsc Ant task to recompile the JWS file and generate a new Web service. This is true anytime you make a change to an annotation in the JWS file.

  If you used the @HandlerChain annotation in your JWS file, reran the jwsc Ant task to regenerate the Web service, and subsequently changed only the external configuration file, you do not need to rerun jwsc for the second change to take affect.

• The jwsc Ant task compiles SOAP message handler Java files into handler classes (and then packages them into the generated application) if all the following conditions are true:

  • The handler classes are referenced in the @HandlerChain annotation of the JWS file.

  • The Java files are located in the directory specified by the sourcepath attribute.

  • The classes are not currently in your CLASSPATH.

  If you want to compile the handler classes yourself, rather than let jwsc compile them automatically, ensure that the compiled classes are in your CLASSPATH before you run the jwsc Ant task.

• You deploy and invoke a Web service that has a handler chain associated with it in the same way you deploy and invoke one that has no handler chain. The only difference is that when you invoke any operation of the Web service, the WebLogic Web services runtime executes the handlers in the handler chain both before and after the operation invoke.

Configuring the Client-side SOAP Message Handlers

You configure client-side SOAP message handlers in one of the following ways:

• Set a handler chain directly on the javax.xml.ws.BindingProvider, such as a port proxy or javax.xml.ws.Dispatch object. For example:

  package examples.webservices.handler.client;
  
  import javax.xml.namespace.QName;
  import java.net.MalformedURLException;
  import java.net.URL;
  
  import javax.xml.ws.handler.Handler; 
  import javax.xml.ws.Binding; 
  import javax.xml.ws.BindingProvider; 
  import java.util.List;
  
  import examples.webservices.handler.Handler1; 
  import examples.webservices.handler.Handler2; 
  
  public class Main {
    public static void main(String[] args) {
       HandlerWS test;
       try {
            test = new HandlerWS(new URL(args[0] + "?WSDL"), new 
                    QName("http://example.org", "HandlerWS") );
          } catch (MalformedURLException murl) { throw new RuntimeException(murl); }
        HandlerWSPortType port = test.getHandlerWSPortTypePort();
  
        Binding binding = ((BindingProvider)port).getBinding(); 
        List<Handler> handlerList = binding.getHandlerChain(); 
        handlerList.add(new Handler1()); 
        handlerList.add(new Handler2()); 
        binding.setHandlerChain(handlerList); 
        String result = null;
        result = port.sayHello("foo bar");
        System.out.println( "Got result: " + result );
    }
  }
  

• Implement a javax.xml.ws.handler.HandlerResolver on a Service instance. For example:

     public static class MyHandlerResolver implements HandlerResolver {
        public List<Handler> getHandlerChain(PortInfo portInfo) {
          List<Handler> handlers = new ArrayList<Handler>();
          // add handlers to list based on PortInfo information
          return handlers;
        }
     }
  

  Add a handler resolver to the Service instance using the setHandlerResolver() method. In this case, the port proxy or Dispatch object created from the Service instance uses the HandlerResolver to determine the handler chain. For example:

  test.setHandlerResolver(new MyHandlerResolver());
  

• Create a customization file that includes a <binding> element that contains a handler chain description. The schema for the <handler-chains> element is the same for both handler chain files (on the server) and customization files. For example:

  <bindings xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
      wsdlLocation="http://localhost:7001/handler/HandlerWS?WSDL"
      xmlns="http://java.sun.com/xml/ns/jaxws">
      <bindings node="wsdl:definitions"  
          xmlns:jws="http://java.sun.com/xml/ns/javaee">
      <handler-chains>
         <handler-chain>
            <handler>
               <handler-class>examples.webservices.handler.Handler1
               </handler-class>
            </handler>
         </handler-chain>
         <handler-chain>
            <handler>
               <handler-class>examples.webservices.handler.Handler2
               </handler-class>
            </handler>
         </handler-chain>
      </handler-chains>
  </bindings>
  

  Use the <binding> child element of the clientgen command to pass the customization file.