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

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 18-1 Order of Execution of Handler Methods

Description of "Figure 18-1 Order of Execution of Handler Methods"

In the case of a client-side handler, the handler executes twice:

• Directly before the client application sends the SOAP request to the web service

• Directly after the client application receives the SOAP response from the web service

The following example illustrates a simple SOAP handler that returns whether the message is inbound or outbound along with the message content.

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)
  {
  }
}

The following example illustrates a simple logical handler that returns whether the message is inbound or outbound along with the message content.

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)
  {
  }
}

The Handler.handleMessage() method is called to intercept a SOAP message request before and after it is processed by the back-end component. Its signature is:

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

Implement this method to perform such tasks as encrypting/decrypting data in the SOAP message before or after it is processed by the back-end component, and so on.

C extends javax.xml.ws.handler.MessageContext (see http://docs.oracle.com/javaee/7/api/javax/xml/ws/handler/MessageContext.html). The MessageContext properties allow the handlers in a handler chain to determine if a message is inbound or outbound and to share processing state. Use the SOAPMessageContext or LogicalMessageContext sub-interface of MessageContext to get or set the contents of the SOAP or logical message, respectively. For more information, see Using the Message Context Property Values and Methods.

After you code all the processing of the SOAP message, code one of the following scenarios:

• Invoke the next handler on the handler request chain by returning true.

  The next handler on the request chain is specified as the next <handler> subelement of the <handler-chain> element in the configuration file specified by the @HandlerChain annotation.

• Block processing of the handler request chain by returning false.

  Blocking the handler request chain processing implies that the back-end component does not get executed for this invoke of the web service. You might want to do this if you have cached the results of certain invokes of the web service, and the current invoke is on the list.

  Although the handler request chain does not continue processing, WebLogic Server does invoke the handler response chain, starting at the current handler.

• Throw the java.lang.RuntimeException or java.xml.ws.ProtocolException for any handler-specific runtime errors.

  WebLogic Server catches the exception, terminates further processing of the handler request chain, logs the exception to the WebLogic Server log file, and invokes the handleFault() method of this handler.

The Handler.handleFault() method processes the SOAP faults based on the SOAP message processing model. Its signature is:

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

Implement this method to handle processing of any SOAP faults generated by the handleMessage() method, as well as faults generated by the back-end component.

C extends javax.xml.ws.handler.MessageContext (see http://docs.oracle.com/javaee/7/api/javax/xml/ws/handler/MessageContext.html). The MessageContext properties allow the handlers in a handler chain to determine if a message is inbound or outbound and to share processing state.Use the LogicalMessageContext or SOAPMessageContext sub-interface of MessageContext to get or set the contents of the logical or SOAP message, respectively. For more information, see Using the Message Context Property Values and Methods.

After you code all the processing of the SOAP fault, do one of the following:

• Invoke the handleFault() method on the next handler in the handler chain by returning true.

• Block processing of the handler fault chain by returning false.

The Handler.close() method concludes the message exchange and cleans up resources that were accessed during processing. Its signature is:

public boolean close(MessageContext context) {}

The following context objects are passed to the SOAP message handlers.

Each context object extends javax.xml.ws.handler.MessageContext, which enables you to access a set of runtime properties of a SOAP message handler from the client application or web service, or directly from the javax.xml.ws.WebServiceContext from a web service (see https://jax-ws.java.net/nonav/jax-ws-20-pfd/api/javax/xml/ws/WebServiceContext.html).

For example, the MessageContext.MESSAGE_OUTBOUND_PROPERTY holds a Boolean value that is used to determine the direction of a message. During a request, you can check the value of this property to determine if the message is an inbound or outbound request. The property would be true when accessed by a client-side handler or false when accessed by a server-side handler.

For more information about the MessageContext property values that are available, see Accessing the Web Service Context.

The LogicalMessageContext class defines the following method for processing the Logical message. For more information, see the java.xml.ws.handler.LogicalMessageContext Javadoc at http://docs.oracle.com/javaee/7/api/javax/xml/ws/handler/LogicalMessageContext.html.

The SOAPMessageContext class defines the following methods for processing the SOAP message. For more information, see the java.xml.ws.handler.soap.SOAPMessageContext Javadoc at http://docs.oracle.com/javaee/7/api/javax/xml/ws/handler/soap/SOAPMessageContext.html.

The javax.xml.soap.SOAPMessage abstract class is part of the SOAP With Attachments API for Java (SAAJ) specification at https://jcp.org/aboutJava/communityprocess/mrel/jsr067/index4.html. You use the class to manipulate request and response SOAP messages when creating SOAP message handlers. This section describes the basic structure of a SOAPMessage object and some of the methods you can use to view and update a SOAP message.

A SOAPMessage object consists of a SOAPPart object (which contains the actual SOAP XML document) and zero or more attachments.

Refer to the SAAJ Javadocs for the full description of the SOAPMessage class.