JAX-WS : SOAP handler in client side

This is part 2 of JAX-WS SOAP handler. In previous article – JAX-WS : SOAP handler in server side, you created a web service and attach a handler to retrieve the client MAC address in header block, for every incoming SOAP message.

SOAP handler in client side

In this article, you will develop a web service client to access the published service in previous article, and attach a handler to inject client’s MAC address into header block, for every outgoing SOAP message that’s send by client side.

Directory structure of this example

1. Web Service Client

Uses wsimport command to parse the published service WSDL file (http://localhost:8888/ws/server?wsdl) and generate all required files to access the service.

C:\>wsimport -keep -verbose http://localhost:8888/ws/server?wsdl
parsing WSDL...
generating code...

Six files are generated automatically, you may only need to concern on the ServerInfoService.java.

File : ServerInfoService.java

@WebServiceClient(name = "ServerInfoService", 
	targetNamespace = "http://ws.mkyong.com/", 
	wsdlLocation = "http://localhost:8888/ws/server?wsdl")
public class ServerInfoService extends Service

A client to access the published service.
File : WsClient.java

package com.mkyong.client;
import com.mkyong.ws.ServerInfo;
import com.mkyong.ws.ServerInfoService;
public class WsClient{
	public static void main(String[] args) throws Exception {
		ServerInfoService sis = new ServerInfoService();
		ServerInfo si = sis.getServerInfoPort();

2. SOAP Handler

Create a SOAP handler to inject client’s MAC address into the SOAP header block, for every outgoing SOAP message. See comments for the code explanation.

File : MacAddressInjectHandler.java

package com.mkyong.handler;
import java.io.IOException;
import java.net.InetAddress;
import java.net.NetworkInterface;
import java.net.SocketException;
import java.net.UnknownHostException;
import java.util.Set;
import javax.xml.namespace.QName;
import javax.xml.soap.SOAPConstants;
import javax.xml.soap.SOAPEnvelope;
import javax.xml.soap.SOAPException;
import javax.xml.soap.SOAPHeader;
import javax.xml.soap.SOAPHeaderElement;
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;
public class MacAddressInjectHandler implements SOAPHandler<SOAPMessageContext>{
   public boolean handleMessage(SOAPMessageContext context) {
	System.out.println("Client : handleMessage()......");
	Boolean isRequest = (Boolean) context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
	//if this is a request, true for outbound messages, false for inbound
	    SOAPMessage soapMsg = context.getMessage();
            SOAPEnvelope soapEnv = soapMsg.getSOAPPart().getEnvelope();
            SOAPHeader soapHeader = soapEnv.getHeader();
            //if no header, add one
            if (soapHeader == null){
            	soapHeader = soapEnv.addHeader();
            //get mac address
            String mac = getMACAddress();
            //add a soap header, name as "mac address"
            QName qname = new QName("http://ws.mkyong.com/", "macAddress");
            SOAPHeaderElement soapHeaderElement = soapHeader.addHeaderElement(qname);
	   }catch(SOAPException e){
	   }catch(IOException e){
	   //continue other handler chain
	   return true;
	public boolean handleFault(SOAPMessageContext context) {
		System.out.println("Client : handleFault()......");
		return true;
	public void close(MessageContext context) {
		System.out.println("Client : close()......");
	public Set<QName> getHeaders() {
		System.out.println("Client : getHeaders()......");
		return null;
   //return current client mac address
   private String getMACAddress(){
	InetAddress ip;
	StringBuilder sb = new StringBuilder();
	try {
		ip = InetAddress.getLocalHost();
		System.out.println("Current IP address : " + ip.getHostAddress());
		NetworkInterface network = NetworkInterface.getByInetAddress(ip);
		byte[] mac = network.getHardwareAddress();
		System.out.print("Current MAC address : ");
		for (int i = 0; i < mac.length; i++) {
			sb.append(String.format("%02X%s", mac[i], (i < mac.length - 1) ? "-" : ""));
	} catch (UnknownHostException e) {
	} catch (SocketException e){
	return sb.toString();

3. SOAP Handler XML file

Create a SOAP handler XML file, and puts your SOAP handler declaration.

File : handler-chain.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

4. Attach SOAP Handler –> Web Service Client

To attach above SOAP handler to web service client, edit the ServerInfoService.java file (generated via wsimport), and annotate with @HandlerChain and specify the SOAP handler file name inside.

File : ServerInfoService.java

@WebServiceClient(name = "ServerInfoService", 
	targetNamespace = "http://ws.mkyong.com/", 
	wsdlLocation = "http://localhost:8888/ws/server?wsdl")
public class ServerInfoService extends Service

Done, please proceed on next article – Part 3 : JAX-WS – SOAP handler testing for client and server side.

Download Source Code

Download It – JAX-WS-Handler-Example.zip (21KB)
Tags :

About the Author

Founder of Mkyong.com and HostingCompass.com, love Java and open source stuff. Follow him on Twitter, or befriend him on Facebook or Google Plus. If you like my tutorials, consider make a donation to these charities.


  • Pingback: Blue Coaster33()

  • Marcos Filho

    hi, i am using your example but when i go to client side the handler doesn’t work, i create my web service client in eclipse with new > web service > web service client > put the wsdl and the eclipse generate my web service client, then i put @handlerchain in the service, i start my app but the handler client never is being called

  • http://www.javaplex.com Faisal

    Hi, i get the following exception on Jboss7, but it works fine on tomcat7 when i call context.getMessage();

    Any help please??

    17:46:27,347 INFO [stdout] (http- java.lang.LinkageError: com/sun/xml/messaging/saaj/soap/SOAPDocumentImpl

    17:46:27,348 INFO [stdout] (http- at com.sun.xml.messaging.saaj.soap.SOAPPartImpl.(SOAPPartImpl.java:119)

    17:46:27,348 INFO [stdout] (http- at com.sun.xml.messaging.saaj.soap.ver1_1.SOAPPart1_1Impl.(SOAPPart1_1Impl.java:89)

    17:46:27,349 INFO [stdout] (http- at com.sun.xml.messaging.saaj.soap.ver1_1.Message1_1Impl.getSOAPPart(Message1_1Impl.java:109)

    17:46:27,349 INFO [stdout] (http- at com.sun.xml.ws.message.AbstractMessageImpl.readAsSOAPMessage(AbstractMessageImpl.java:191)

    17:46:27,349 INFO [stdout] (http- at com.sun.xml.ws.handler.SOAPMessageContextImpl.getMessage(SOAPMessageContextImpl.java:79)

    17:46:27,350 INFO [stdout] (http- at com.inov8.integration.soap.SOAPLoggingHandler.logToSystemOut(SOAPLoggingHandler.java:62)

    17:46:27,350 INFO [stdout] (http- at com.inov8.integration.soap.SOAPLoggingHandler.handleMessage(SOAPLoggingHandler.java:32)

    17:46:27,350 INFO [stdout] (http- at com.inov8.integration.soap.SOAPLoggingHandler.handleMessage(SOAPLoggingHandler.java:1)

    17:46:27,350 INFO [stdout] (http- at com.sun.xml.ws.handler.HandlerProcessor.callHandleMessage(HandlerProcessor.java:292)

    17:46:27,351 INFO [stdout] (http- at com.sun.xml.ws.handler.HandlerProcessor.callHandlersRequest(HandlerProcessor.java:133)

    17:46:27,351 INFO [stdout] (http- at com.sun.xml.ws.handler.ClientSOAPHandlerTube.callHandlersOnRequest(ClientSOAPHandlerTube.java:138)

    17:46:27,351 INFO [stdout] (http- at com.sun.xml.ws.handler.HandlerTube.processRequest(HandlerTube.java:116)

    17:46:27,351 INFO [stdout] (http- at com.sun.xml.ws.api.pipe.Fiber.__doRun(Fiber.java:595)

    17:46:27,352 INFO [stdout] (http- at com.sun.xml.ws.api.pipe.Fiber._doRun(Fiber.java:554)

    17:46:27,352 INFO [stdout] (http- at com.sun.xml.ws.api.pipe.Fiber.doRun(Fiber.java:539)

    17:46:27,352 INFO [stdout] (http- at com.sun.xml.ws.api.pipe.Fiber.runSync(Fiber.java:436)

    17:46:27,352 INFO [stdout] (http- at com.sun.xml.ws.client.Stub.process(Stub.java:248)

    17:46:27,353 INFO [stdout] (http- at com.sun.xml.ws.client.sei.SEIStub.doProcess(SEIStub.java:135)

    17:46:27,353 INFO [stdout] (http- at com.sun.xml.ws.client.sei.SyncMethodHandler.invoke(SyncMethodHandler.java:109)

    17:46:27,353 INFO [stdout] (http- at com.sun.xml.ws.client.sei.SyncMethodHandler.invoke(SyncMethodHandler.java:89)

    17:46:27,353 INFO [stdout] (http- at com.sun.xml.ws.client.sei.SEIStub.invoke(SEIStub.java:118)

    17:46:27,353 INFO [stdout] (http- at $Proxy124.balanceUpdate(Unknown Source)

    17:46:27,354 INFO [stdout] (http- at com.inov8.integration.service.WaridTopupService.topup(WaridTopupService.java:58)

    17:46:27,354 INFO [stdout] (http- at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)

    17:46:27,354 INFO [stdout] (http- at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)

    17:46:27,354 INFO [stdout] (http- at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)

    17:46:27,354 INFO [stdout] (http- at java.lang.reflect.Method.invoke(Method.java:597)

    17:46:27,355 INFO [stdout] (http- at org.springframework.aop.support.AopUtils.invokeJoinpointUsingReflection(AopUtils.java:309)

    17:46:27,355 INFO [stdout] (http- at org.springframework.aop.framework.ReflectiveMethodInvocation.invokeJoinpoint(ReflectiveMethodInvocation.java:183)

    17:46:27,355 INFO [stdout] (http- at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:150)

    17:46:27,355 INFO [stdout] (http- at org.springframework.remoting.support.RemoteInvocationTraceInterceptor.invoke(RemoteInvocationTraceInterceptor.java:77)

    17:46:27,355 INFO [stdout] (http- at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(ReflectiveMethodInvocation.java:172)

    17:46:27,356 INFO [stdout] (http- at org.springframework.aop.framework.JdkDynamicAopProxy.invoke(JdkDynamicAopProxy.java:202)

    17:46:27,356 INFO [stdout] (http- at $Proxy122.topup(Unknown Source)

    17:46:27,356 INFO [stdout] (http- at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)

    17:46:27,356 INFO [stdout] (http- at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)

    17:46:27,356 INFO [stdout] (http- at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)

    17:46:27,357 INFO [stdout] (http- at java.lang.reflect.Method.invoke(Method.java:597)

    17:46:27,357 INFO [stdout] (http- at org.springframework.remoting.support.RemoteInvocation.invoke(RemoteInvocation.java:205)

    17:46:27,357 INFO [stdout] (http- at org.springframework.remoting.support.DefaultRemoteInvocationExecutor.invoke(DefaultRemoteInvocationExecutor.java:38)

    17:46:27,357 INFO [stdout] (http- at org.springframework.remoting.support.RemoteInvocationBasedExporter.invoke(RemoteInvocationBasedExporter.java:78)

    17:46:27,358 INFO [stdout] (http- at org.springframework.remoting.support.RemoteInvocationBasedExporter.invokeAndCreateResult(RemoteInvocationBasedExporter.java:114)

    17:46:27,358 INFO [stdout] (http- at org.springframework.remoting.httpinvoker.HttpInvokerServiceExporter.handleRequest(HttpInvokerServiceExporter.java:73)

    17:46:27,358 INFO [stdout] (http- at org.springframework.web.servlet.mvc.HttpRequestHandlerAdapter.handle(HttpRequestHandlerAdapter.java:49)

    17:46:27,358 INFO [stdout] (http- at org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:790)

    17:46:27,359 INFO [stdout] (http- at org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:719)

    17:46:27,359 INFO [stdout] (http- at org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:644)

    17:46:27,359 INFO [stdout] (http- at org.springframework.web.servlet.FrameworkServlet.doPost(FrameworkServlet.java:560)

    17:46:27,359 INFO [stdout] (http- at javax.servlet.http.HttpServlet.service(HttpServlet.java:754)

    17:46:27,359 INFO [stdout] (http- at javax.servlet.http.HttpServlet.service(HttpServlet.java:847)

    17:46:27,360 INFO [stdout] (http- at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:329)

    17:46:27,360 INFO [stdout] (http- at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:248)

    17:46:27,360 INFO [stdout] (http- at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:275)

    17:46:27,360 INFO [stdout] (http- at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:161)

    17:46:27,360 INFO [stdout] (http- at org.jboss.as.web.security.SecurityContextAssociationValve.invoke(SecurityContextAssociationValve.java:139)

    17:46:27,361 INFO [stdout] (http- at org.jboss.as.web.NamingValve.invoke(NamingValve.java:57)

    17:46:27,361 INFO [stdout] (http- at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:154)

    17:46:27,361 INFO [stdout] (http- at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:102)

    17:46:27,362 INFO [stdout] (http- at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:109)

    17:46:27,362 INFO [stdout] (http- at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:362)

    17:46:27,363 INFO [stdout] (http- at org.apache.coyote.http11.Http11Processor.process(Http11Processor.java:877)

    17:46:27,363 INFO [stdout] (http- at org.apache.coyote.http11.Http11Protocol$Http11ConnectionHandler.process(Http11Protocol.java:667)

    17:46:27,363 INFO [stdout] (http- at org.apache.tomcat.util.net.JIoEndpoint$Worker.run(JIoEndpoint.java:952)

  • Manasi


    I am using WAS 7 and generated my client code using wsimport. I have created a SOAP Handler to inject Security token in my request exactly as described here. I am getting the following error:

    getHeaders() called.
    getHeaders() called.
    Before call to PartyService
    handleMessage() called.
    close() called
    Exception in thread “main” javax.xml.ws.WebServiceException: org.w3c.dom.DOMException: HIERARCHY_REQUEST_ERR: An attempt was made to insert a node where it is not permitted.
    at com.sun.xml.internal.ws.handler.ClientSOAPHandlerTube.callHandlersOnRequest(ClientSOAPHandlerTube.java:147)
    at com.sun.xml.internal.ws.handler.HandlerTube.processRequest(HandlerTube.java:117)
    at com.sun.xml.internal.ws.api.pipe.Fiber.__doRun(Fiber.java:599)
    at com.sun.xml.internal.ws.api.pipe.Fiber._doRun(Fiber.java:558)
    at com.sun.xml.internal.ws.api.pipe.Fiber.doRun(Fiber.java:543)
    at com.sun.xml.internal.ws.api.pipe.Fiber.runSync(Fiber.java:440)
    at com.sun.xml.internal.ws.client.Stub.process(Stub.java:223)
    at com.sun.xml.internal.ws.client.sei.SEIStub.doProcess(SEIStub.java:136)
    at com.sun.xml.internal.ws.client.sei.SyncMethodHandler.invoke(SyncMethodHandler.java:110)
    at com.sun.xml.internal.ws.client.sei.SyncMethodHandler.invoke(SyncMethodHandler.java:90)
    at com.sun.xml.internal.ws.client.sei.SEIStub.invoke(SEIStub.java:119)
    at $Proxy36.updateParty(Unknown Source)
    at com.bac.cmx.component.MessageFormatter.prepareUpdatePartyRequest(MessageFormatter.java:130)
    at com.bac.cmx.component.MessageFormatter.main(MessageFormatter.java:57)
    Caused by: org.w3c.dom.DOMException: HIERARCHY_REQUEST_ERR: An attempt was made to insert a node where it is not permitted.
    at org.apache.xerces.dom.CoreDocumentImpl.insertBefore(Unknown Source)
    at org.apache.xerces.dom.NodeImpl.appendChild(Unknown Source)
    at com.ibm.ws.webservices.engine.xmlsoap.SOAPPart.appendChild(SOAPPart.java:282)
    at com.sun.xml.internal.bind.marshaller.SAX2DOMEx.startElement(SAX2DOMEx.java:177)
    at com.sun.xml.internal.ws.message.AbstractMessageImpl.writeTo(AbstractMessageImpl.java:159)
    at com.sun.xml.internal.ws.message.AbstractMessageImpl.readAsSOAPMessage(AbstractMessageImpl.java:194)
    at com.sun.xml.internal.ws.handler.SOAPMessageContextImpl.getMessage(SOAPMessageContextImpl.java:80)
    at com.bankofamerica.wsdl.wcc.party.service.v012.ClientHandler.handleMessage(ClientHandler.java:39)
    at com.bankofamerica.wsdl.wcc.party.service.v012.ClientHandler.handleMessage(ClientHandler.java:1)
    at com.sun.xml.internal.ws.handler.HandlerProcessor.callHandleMessage(HandlerProcessor.java:293)
    at com.sun.xml.internal.ws.handler.HandlerProcessor.callHandlersRequest(HandlerProcessor.java:134)
    at com.sun.xml.internal.ws.handler.ClientSOAPHandlerTube.callHandlersOnRequest(ClientSOAPHandlerTube.java:139)
    … 13 more

    The error is on line SOAPMessage soapMsg = context.getMessage();

    Any help please?

  • http://storify.com/haroldrossii/art-com-coupon-huge-discount jason

    Awesome! Its in fact remarkable article, I have got much clear idea regarding from this post.

  • http://webservices srini

    how to generate the wsdl for the project

  • Umberto

    Thank you so much, you helped me a lot!

  • http://www.eksikalori.com Ahmet

    Thanks for this nice tutorial, especially pointing out the “wsimport” tool which is very useful.

  • Daniel Zimmermann


    I’m currently trying to attach a HandlerChain to my Client side only to modify the HTTP headers.
    I’ve tried the approch you’ve mentioned, but also the “old” one via attaching the chain programatically to the service:

    service.setHandlerResolver(new HandlerResolver() {
    	public List&lt;Handler&gt; getHandlerChain(PortInfo portInfo) {
    		AuthenticationHandler authenticationHandler = new AuthenticationHandler();
    		List&lt;Handler&gt; handlerChain = new ArrayList&lt;Handler&gt;();
    		return handlerChain;

    and even tried to tie it to the Port –> BindingProvider

    BindingProvider bp = (BindingProvider) servicePort;
    AuthenticationHandler authenticationHandler = new AuthenticationHandler();
    List&lt;Handler&gt; handlerChain = handlerChain = new ArrayList&lt;Handler&gt;();

    Nothing of this worked. I tried to debug it, but it seams, that my Handler is never invoked.
    Now I’m quite uncertain, how to continue, since I have no more ideas… Maybe it’s the OpenJDK (java-6-openjdk-amd64) I’m currently using under linux?

    • Karthick

      I think its the OpenJDK. Both your methods work just fine for me. Im using JavaEE6 (Websphere App Server 8.0)

  • Pedro Pereira


    Great job!

    Can you provide a example (server and client) with SOAPFault handling?


  • Pasqualino

    Thank you for posting this :)!

  • Zeus

    im getting this error message running this through eclipse project

    Client : getHeaders()……
    Client : getHeaders()……
    Exception in thread “main” java.lang.IllegalArgumentException: com.mkyong.serverside.handler.ws.ServerInfo is not an interface

    it seems that when i do a wsimport the ServerInfo.java is public interface ServerInfo { and not an implementation of the interface.

    I also realize that we never created an interface for the ServerInfo.java so how do we get around this ?


    • Zeus

      fixed it by adding wsimport … -p .. to distinguish ServerInfo client from server

  • Chandra


    Can you please give me information on setting the NTLM credentials in JAX-WS Client

    Thanks in Advance,

  • Saroj


    Many many thanx for your post. Actually we need to add a header in the msg. In our case the Header key is a static one, but the Header value is dynamic. So we need the header value as variable in the handler’s handleMessage method.

    Please advise how can that be done. Thanx a lot for you help so far.


  • Bharat


    When I use your example and try to add a client soap header, I am getting following exception…

    Client : getHeaders()......
    javax.xml.soap.SOAPException: Invalid SOAPHeaderElement name: {http://webservice.domain.gcdm.wmg.com/}ArtistWebServiceBeanService
    Client : handleMessage()......
    Client : handleFault()......
    Client : close()...... 

    The code which i am executing is:

    QName qname = new QName("http://webservice.domain.gcdm.wmg.com/", "ArtistWebServiceBeanService");
    SOAPHeaderElement soapHeaderElement = soapHeader.addHeaderElement(qname);
    • Dinesh

      hey i need a help… help me to run these examples

      • http://www.mkyong.com mkyong

        help? get this example, then run it?

        • Hippi

          Hi mkykong,

          I just get the example and i run it in eclipse successful. But i saw a file war in the project. Can you tell me how to use the file war in tomcat? Thanks!

  • Pramod Kumar

    In the above code (JAX-WS : SOAP handler in client side) , instead of the Mac Address I need to pass some authentication information ( user name and password ) availabe as object.

    public class Authenticate_Info
    public string UserName;
    public string Password;

    How to add this object to the SoapHeader.

    WSDL Entry for the oject.

    please let me know how to add this object to soap header and then how on server to validate the same.

    • Saroj

      Hi Pramod,

      My requirement is also same as yours. Would you please help me with the way you implemented it ??

      Many thanx for your help in advance.


    • Saroj

      Hi Pramod,

      Did you find a way to do set the userName and pwd header in handleMessage() method.
      If yes, would you please put some light on that. many thanx for your help n time.

  • Pingback: JAX-WS : SOAP handler in server side()

  • Pingback: JAX-WS : SOAP handler testing for client and server side()