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.


In order to use Handler chains in your Web service you have to add the @javax.jws.HandlerChain annotation at class level:


package com.sample.ws;

import javax.jws.HandlerChain;
import javax.jws.WebService;

@WebService(endpointInterface = "com.sample.ws.SampleWS", serviceName = "SampleWS")
public class SampleWSImpl implements SampleWS {
 public SampleWSImpl() {}
 public String hello(String s) {
 return "Hello "+s;

Ok, now your Web service will be proxied by one or more Handler defined in the handler-chain.xml configuration file.

In earlier releases of JBoss you had to place this file beneath the META-INF folder of your Web application. When using JBoss 7 just place it in the package folder which is included in the file property (In our example com/sample/ws).

Here is the handler-chain.xml which defines a Logging Handler:

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

And this is the Handler Class:

package com.sample.handler;

import java.util.Set;

import javax.xml.namespace.QName;
import javax.xml.soap.SOAPMessage;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.soap.SOAPHandler;
import javax.xml.ws.handler.soap.SOAPMessageContext;

import org.apache.commons.io.output.ByteArrayOutputStream;

public class LoggingHandler implements SOAPHandler<SOAPMessageContext> {

 public Set<QName> getHeaders() {
 return null;

 public void close(MessageContext context) {

 public boolean handleFault(SOAPMessageContext context) {
  return true;

 public boolean handleMessage(SOAPMessageContext context) {
  return true;

 private void logToSystemOut(SOAPMessageContext smc) {
  Boolean outboundProperty = (Boolean) smc.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);

  try {
   if (!outboundProperty.booleanValue()) {
   SOAPMessage message = smc.getMessage();
  System.out.println("Incoming message:");
  ByteArrayOutputStream stream = new ByteArrayOutputStream();
  catch (Exception e) {
  System.out.println("Exception in handler: " + e);

The above Handler will just print out all the SOAP incoming messages which are gathered as InputStream and finally converted to String using the ByteArrayOutputStream utility class from Apache Commons IO.

You can use SOAP message Handlers as well to improve the performance of your Web Service. After your Web Service has been deployed, 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.


Related articles available on mastertheboss.com

JBoss web services

JAX-WS simplifies the development model for a web service endpoin

What is a Web Service One Way invocation?

JBoss recipe of the day

Asynchronous web services with JBoss WS

Developing rigorous and responsive web service client application

How to change the default Web Service deployment Port ?

JBoss recipe of the day

Using Axis Web Services with JBoss

Still not ready for JBoss WS ? if you don't have a JDK 1.5 compli

Invoking JBoss Web Services with Flex

Flex® is a free, open source framework for building highly in