SOAP handlers overview

Handlers are the message interceptors which does additional processing of the inbound and outbound messages.

Inbound messages are the request messages (client to web service)

Outbound messages are the response messages (web service to client)

Additional processing of a SOAP message would be to add some additional information to SOAP headers or manipulate the values based on some condition etc.

Example 1:

Attach most commonly used parameters in the SOAP header using a handler at the client side.
In the server side, write a handler which can check these commonly used parameters from the header and then produce the response from the cache if these parameters are found otherwise get the data from the backend.
This way it will improve the web service performance.

Example 2:

In the client side handler, add some client identity information in the SOAP header like IP address of a client
In the server side handler,extract the IP address from the SOAP header and check whether it belongs to trusted IP addresses or not and then process it further if it’s a trusted IP else throw an exception which can be sent as SOAP fault.

JAX-WS provides 2 types of Message handlers

1.SOAP handlers

2.Logical handlers

SOAP handlers

SOAP handlers are the protocol specific handlers and they can access or change the protocol specific aspect (like headers) of a message and also they can alter the body of a SOAP message
Basically SOAP handlers can access the entire SOAP message (header+body)

Logical handlers

Logical handlers are protocol-agnostic and cannot access or change any protocol-specific parts (like headers) of a message.
They act only on the payload of the message.
Basically Logical handlers can access only body of the message.

The most preferred handler is the SOAP handler as it provides an access to the entire SOAP message(header + body

Message Context

Message context provides methods to access and modify the inbound and outbound messages.
It also provides some properties which can be used to determine whether message is inbound or outbound.


Each SOAP Handler should implement interface

Each Logical handlers should implement interface

Message context for logical handlers is represented by

Message context for SOAP handlers is represented by

Message for logical handler is represented by

Message for SOAP handler is represented by javax.xml.soap.SOAPMessage

We can write both SOAP handler and Logic handler within a handler chain but in this case, logical handlers will be executed before the SOAP handlers on outbound message and SOAP handlers are executed before the logic handlers on inbound message

We can see that in below diagram


How we define handlers ?

Defining handlers is very easy in JAX-WS
We just need to implement the handler interface and override the below 3 methods





This method will be called for both inbound and outbound messages
Perform the additional processing of the message in this method.


This method handles the processing of any SOAP faults generated by the handleMessage() method,
and also the faults generated by the back-end component


This is called after the completion of message processing by all handlers for each web service invocation.
This method can be used to clean up all resources which are used during processing of the message.

About the Author

Karibasappa G C (KB)
Founder of
I love Java and open source technologies and very much passionate about software development.
I like to share my knowledge with others especially on technology πŸ™‚
I have given all the examples as simple as possible to understand for the beginners.
All the code posted on my blog is developed,compiled and tested in my development environment.
If you find any mistakes or bugs, Please drop an email to

Connect with me on Facebook for more updates

Share this article on