Implementing Custom SOAP Message Handlers

The SOAP message handler implementation class is required to implement the javax.xml.rpc.handler.Handler interface as defined in the JAX-RPC specification. It should contain only the default constructor with no arguments in order to be instantiated at runtime. For example:

package javax.xml.rpc.handler;
   public interface Handler {
      public boolean handleRequest(javax.xml.rpc.handler.MessageContext context);
      public boolean handleResponse(javax.xml.rpc.handler.MessageContext context);
      public boolean handleFault(javax.xml.rpc.handler.MessageContext context);
      public void destroy();
      public void init(javax.xml.rpc.handler.HandlerInfo config);
      public javax.xml.namespace.QName[] getHeaders();
   }

To make it easier to implement these handlers, the JAX-RPC specification also defines an abstract helper class, javax.xml.rpc.handler.GenericHandler, which has default implementations for all the methods of this interface. You can use this as a starting point and incorporate custom logic for SOAP message processing by overriding the necessary methods.

Creating a SOAP Message Handler Archive File

In order to use the implemented message handlers, they need to be made available in NetBeans and the Java CAPS Repository. This is done by importing a SOAP message handler archive file into the Java CAPS Environment, as described in Importing a JAX-RPC Handler Archive. If you create a custom message handler, you need to package an archive file to import.

To Create the SOAP Message Handler Archive File

1. Create and compile the message handler implementation classes and support classes, and package them into a JAR file.
2. Create a directory in which to store the archive files.
3. Copy the JAR file to this directory, and if the handler implementations depend on any other JAR files, copy them to this directory as well.
4. Create a descriptor XML file in the same directory and name it messagehandlers.xml.

   This file describes the packaged handlers and should contain the following elements. You can view a sample XML file under Sample Descriptor File for the Console Logger Handler.

   • message-handlers: The parent element, which contains a list of message handlers.

   • handler: Contains the following elements, which define the configuration of a handler.

     • name: The name of the message handler.

     • description: A brief description of the message handler.

     • type: The type of handler. Currently, only the javax.xml.rpc.handler.Handler is supported.

     • class: The handler implementation class name.

     • init-properties: Contains a list of properties for initializing the handler at runtime. For each property, you can specify the following attributes: name, default-value, required, and description. If the required attribute is set to true, a value must be specified for that property in order for the handler to function properly at runtime.

5. Use a file archiving tool, such as WinZip, to archive the contents of the directory into a ZIP file.

Sample SOAP Message Handler: Console Logger Handler

The following sample handler implementation logs the entire SOAP message and the MIME headers when the logging level is set to INFO on the handler class.

package com.stc.ws.samples.rpc.handler;

import java.io.ByteArrayOutputStream;
import java.util.Iterator;
import java.util.logging.Level;
import java.util.logging.Logger;

import javax.xml.namespace.QName;
import javax.xml.rpc.handler.GenericHandler;
import javax.xml.rpc.handler.HandlerInfo;
import javax.xml.rpc.handler.MessageContext;
import javax.xml.rpc.handler.soap.SOAPMessageContext;
import javax.xml.soap.Mimeheader;
import javax.xml.soap.MimeHeaders;
import javax.xml.soap.SOAPMessage;


public class ConsoleLoggerHandler extends GenericHandler {
   private Logger logger=Logger.getLogger(getClass().getCanonicalName());
   private QName [] qnames;
   private boolean initialized;

   public void init(HandlerInfo info) {
      qnames=info.getHeaders();
      initialized=true;
   }

   public javax.xml.namespace.QName[] getHeaders() {
      return qnames;
   }

/** Logs the SOAP request to the log file
*/
public boolean handleResponse(MessageContext mc) {
   return logMessage(mc, "SOAP Request Message is: ");
}

/** Logs the SOAP response to the log file
*/
public boolean handleResponse(MessageContext mc) {
   return log Message(mc, "SOAP Response Message is: ");
}

/** Logs the SOAP fault to the log file
*/
public boolean handleFault(MessageContext mc) {
   return logMessage(mc, "SOAP Fault Message is: ");
}

private boolean logMessage(MessageContext mc, String type) {
   if (!initialized) {
      return false;
   }

   try {
      if (logger.isLoggable(Level.INFO)) {
         logger.log(Level.INFO, type);
         SOAPMessage msg = ((SOAPMessageContext)mc).getMessage();

         //Print out the Mime Headers
         MimeHeaders mimeHeaders = msg.getMimeHeaders();
         Iterator mhIterator = mimeHeaders.getAllHeaders();
         MimeHeader mh;
         String header;
         logger.log(Level.INFO, "  Mime Headers:");
         while (mhIterator.hasNext()) {
            mh = (MimeHeader) mhIterator.next();
            header = new StringBuffer(" Name: ")
               .append(mh.getName())
               .append(" Value: ")
               .append(mh.getValue()).toString();
            logger.log(Level.INFO, header);
         }

         logger.log(Level.INFO, " SOAP Message: ");
         ByteArrayOutputStream baos = new ByteArrayOutputStream();
         msg.writeTo(baos);
         logger.log(Level.INFO,"   " + baos.toString());
         baos.close();
      }
      
      return true;
   } catch (Exception e) {
      if(logger.isLoggable(Level.SEVERE)) {
         logger.log(Level.SEVERE,  "Error logging SOAP message", e);
      }
      
      return false;
   }
}

Sample Descriptor File for the Console Logger Handler

The following example could be used with the sample Console Logger Handler, defined above.

<?xml version="1.0" encoding="UTF-8"?>
<message-handlers>
   <handler>
      <name>ConsoleLoggerHandler</name>
      <description>"Prints out the SOAP request/response/fault messages to 
           the logger."
      </description>
      <type>javax.xml.rpc.handler.Handler</type>
      <class name="com.stc.ws.samples.rpc.handler.ConsoleLoggerHandler"/>
      <init-properties>
         <property name="http-return-status" default-value="503"  
                   required="false" description="The HTTP status to 
                   return in the response message."/>
      </init-properties>
   </handler>
</message-handlers>