JAX-WS Handler Processing

JAX-WS Handler mechanism gives us the plugable solution to handle message headers or other part of a message. JAX-WS handler allows us to trap inbound and outbound messages. It also allows us to modify inbound message's header or body, similarly it also allows use to modify outbound message header or body.

JAX-WS handler is not limited to modification in the message. It allow us to add new element in the inbound and outbound message.

The JAX-WS handler can be configured in Client and Server.
  Most of the time JAX-WS handler is used to add a tracking id in the inbound message header and returns same tracking id in the outbound response message header.

In JAX-WS, there are two kinds of Handler. It would be great if I can explain with an example. So for instance I am talking about SOAP message.

In real world, SOAP message is considered as an Envelop. A Envelop has three parts- Header, Body and Attachment.

So, the handler mechanism provides two kinds of Handlers.

1. Protocol Handler
2. Logical Handler

In our example, SOAP is a protocol. So, we will be taking about SOAPhandler. Also, we will seeing an example of LogicalHandler.

SOAPHandler - SOAPHandler is a type of Protocol handler. SOAPHandler deals with whose SOAP message, i.e complete Envelop.

LogicalHandler - Logical handler is a protocol independent handler. Logical handler deals with the part of message i.e. payload of the message.

One important thing with handler is we can use the same handler for incoming and outgoing messages.

You can found the Logical and SOAP handler in the following package respectively:

javax.xml.ws.handler.soap.SOAPHandler, javax.xml.ws.handler.LogicalHandler.

Both the Handler interfaces are extends from Handler interface.

In JAX-WS, there is a concept of Handler chain. Handler chain is a list of Handlers. The handler chain can contain mix of Protocol and Logical Handlers.

There is a specific Order of processing of those Handers mentioned in the Handler chain. All the Logical Handlers are preceded with Protocol Handlers. Suppose you have listed Handlers in the following order in the handler chain.

Original Handler List -  L1->P1->P2->L2->P3->L3

In the runtime environment, this order will not be preserved. The List of Handlers will be reorganized like this.

Runtime Handler List -  L1->L2->L3->P1->P2->P3

Now, As I have said in the beginning of this topic is Handler can be used in Inbound and Outbound web service call. So, there are following scenarios we have:

1.  Outbount Handler processing - The processing of handler will starts from beginning of the Runtime Handler List. e.i. L1->L2->L3->P1->P2->P
2. Inbound Handler processing - The processing of handler will starts from end of the Runtime Handler List. e.i. P3->P2->P1->L3->L2->L1

A sample Logical handler for Inbound and Outbound request.

Previous Post

Use of CountDownLatch API in java

This is a brand new API introduced in Java 5. This API is dealing with synchronization. It means that at any given point of time only one thread can access the block of code.

This API is under the java.util.concurrent package.

This is best suitable where you want to initialized all the sub programs before completing or other work.

Suppose, we have a program, which has LogManager and ErrorManager objects. At the same time we want to initialize all these objects then only the main program can do other work.

The CountDownLatch API has the following methods:

1. await() - Causes the current thread to wait until the latch has counted down to zero.
2. await(long timeout, TimeUnit unit) - Causes the current thread to wait until the latch has counted down to zero, unless the thread is interrupted, or the specified waiting time elapses.
3. countDown() - Decrements the count of the latch, releasing all waiting threads if the count reaches zero.
4. getCount() - Returns the current count.

Next Post

New features of Spring 3.0

These are the features available in Spring 3.0

• Spring Expression Language
• IoC enhancements/Java based bean metadata
• General-purpose type conversion system and field formatting system
• Object to XML mapping functionality (OXM) moved from Spring Web Services project
• Comprehensive REST support
• @MVC additions
• Declarative model validation
• Early support for Java EE 6
• Embedded database support

When web service methods in implicit SEI are exposed

If you carefully watch/read @WebMethod annotation of JAX-WS API.

You can find that there is an attribute called "exclude" in @WebMethod annotation. Yes! as name suggests it controls whether the method of implicit SEI(Service Endpoint Interface) are exposed or not. 

One important thing is that - you can not use "exclude" attribute of @WebMethod annotation in explicit SEI(Service Endpoint Interface).

Also, there is some restriction of using "exclude" attribute of @WebMethod depending upon the JAX-WS version.

Prior to JAX-WS 2.1.6:

• The method has an @WebMethod or @WebMethod(exclude=false) annotation and the containing class has an @WebService annotation.
• The method has no @WebMethod annotation, but the containing class has a @WebWervice annotation and no other methods have @WebMethod or @WebMethod(exclude=false) annotation on it.

On JAX-WS 2.1.6 or Later:

• The method has an @WebMethod or @WebMethod(exclude=false) annotation.
• The method has no @WebMethod or @WebMethod(exclude=false) annotation but the containing class has an @WebService annotation.

Example:

public class Message {

    @WebMethod(exclude=false)
    public void send(String s) {...}

    public String accept() {...}
}

@WebService(targetNamespace="foo")
public class MessageImpl extends Message {

    @WebMethod(exclude=false)
    public void sendWrapper(String s) {...}

    public String acceptWrapper() {...}
}

Prior you JAX-WS 2.1.6

public void sendWrapper(String s) {...}

On or After JAX-WS 2.1.6

public void send(String s) {...}
public void sendWrapper(String s) {...}
public String acceptWrapper() {...}

Create a service endpoint implementation for JAX-WS applications with annotations

Before going to steps/procedure creating a service endpoint using JAX-WS annotation, you should read the basic of Endpoint implementation using JAX_WS.

Please read JAX-WS endpoint implementation 

1. First determine if the service implementation is a JavaBeans endpoint or a Provider endpoint. If you choose to use a JavaBeans endpoint, then determine if you want to use an explicit SEI or if the bean itself will have an implicit SEI.
2. Annotate the service endpoints. A Java class that implements a Web service must specify either the javax.jws.WebService orjavax.xml.ws.WebServiceProvider annotation. Both annotations must not be present on a Java class. Thejavax.xml.ws.WebServiceProvider annotation is only supported on classes that implement the javax.xml.ws.Provider interface.
   • If you have an explicit service endpoint interface with the Java class, then use the endpointInterface parameter to specify the service endpoint interface class name to the javax.jws.WebService annotation. You can add the @WebMethod annotation to methods of a service endpoint interface to customize the Java-to-WSDL mappings. All public methods are considered as exposed methods regardless of whether the @WebMethod annotation is specified or not. It is incorrect to have an @WebMethod annotation on an service endpoint interface that contains the exclude attribute.
   • If you have an implicit service endpoint interface with the Java class, then the javax.jws.WebService annotation will use the default values for the serviceName, portName, and targetNamespace parameters. To override these default values, specify values for these parameters in the @WebService annotation. If the @WebMethod annotation is not specified, all public methods are exposed including the inherited methods with the exception of methods inherited from java.lang.Object. The exclude parameter of the @WebMethod annotation can be used to control which methods are exposed.
   • If you are using the Provider interface, use the javax.xml.ws.WebServiceProvider annotation on the Provider endpoint.

JAX-WS Web Service Endpoint implementation

In web service development cycle, Endpoint implementation plays a vital role. Actual purpose of the web service is written in Web service endpoint class or technically we can say that web service endpoint contains the business logic.

In this blog post i'll be going to discuss about types of JAX-WS web service endpoint implementation.

In JAX-WS, we have two choice and discuss individually:

1. JavaBeans service endpoint interface.
2. A Provider interface.

JavaBeans service endpoint implementation is same a JAX-RPC. In JAX-WS SEI (Service Endpoint Interface) is optional. The JAX-WS service that do not have an associated SEI are regarded as having implicit SEI. whereas the service have an associated SEI are regarded as having explicit SEI. Unlike JAX-RPC, JAX-WS service not required to implement java.rmi.Remote. It is mandatory in JAX-RPC.

JAX-WS specification leverages support for annotating Java class with other metadata to expose the class as a web service.

If you are decided to use JavaBeans service endpoint interface, then annotate the class with javax.jws.WebService annotation.


If JAX-WS service implementation bean also uses an explicit SEI then endpoint interface name should be used in attribute "endpointInterface" of javax.jws.WebService annotation.

If JAX-WS service implementation bean does not use explicit SEI then service is described by implicit SEI declared in the bean itself.

If you have explicit SEI then you have to annotate the interface with the javax.jws.WebService with the following attributes.

@WebService(name="", targetNamespace="", wsdlLocation="")

and SIB (Service Implementation Bean) should be annotate with the followings:

@WebService(serviceName="", targetNamespace="", endpointInterface="", portName="")


If you are decided to use a new Provider interface, then annotate the class woth javax.jws.WebServiceProvider annotation.

a new Provider API, is more message oriented and this interface has one method named "invoke" and uses generic "Source" to control input and output.

Steps creating JAX-WS endpoint implementation

Transitivity rules of WSDL1.1

Transitivity rules of WSDL 1.1

• A claim on a wsdl:port element is inherited by the referenced wsdl:binding element
• A claim on a wsdl:binding element is inherited by the referenced wsdl:portType element
• A claim on a wsdl:portType element is inherited by the referenced wsdl:operation elements
• A claim on a wsdl:operation element is inherited by the referenced wsdl:message elements of its child wsdl:output and/or wsdl:input elements