Thursday, December 18, 2008

Invoke a single port async service using JAX-WS and WS-Addressing

I was looking over the WSTF pages and found the use cases that include a single port reply to another address. I did wonder if you could safely invoke this using JAX-WS. So I decided to find out.

To make things simple I used the following hello world with addressing turned on. Note this is not a true asynchronous service as the rely is sent before the server returns with a 202 code; but it is close enough for the purposes of this presentation.

public class Hello {

    public String sayHello(String name) {
        return name;

So I published this service and then generated a client to another project. We need to create a suitable callback service so first of all you have to find the port SEI:

@WebService(wsdlLocation="HelloService.wsdl", targetNamespace="http://project1/",
  { project1.ObjectFactory.class })
public interface Hello
  @Action(input="http://project1/Hello/sayHelloRequest", output="http://project1/Hello/sayHelloResponse")
  @ResponseWrapper(localName="sayHelloResponse", targetNamespace="http://project1/",
  @RequestWrapper(localName="sayHello", targetNamespace="http://project1/",
  public String sayHello(@WebParam(targetNamespace="", name="arg0")
    String arg0);

Then I used Refactor->Duplicate to create a copy and converted the interface into a class. As you can see you need to turn the interface in-side out. The changes I made are:

  • Remove WSDL declaration in @WebService, a new one will be create for response part
  • Remove output action and replace with input with the output value
  • Make method one way
  • Add @Addressing modifier
  • Make the return value the only parameter, moving over any WebResult values to WebParam.

If would be really nice to have this done automatically when the usingAddressing tag is found in the WSDL, perhaps it would be possible to extend the web services generation tool to do this.

@WebService(targetNamespace = "http://project1/", name = "Hello")
@XmlSeeAlso( { ObjectFactory.class })
public class HelloCallback {
    @Action(input = "http://project1/Hello/sayHelloResponse")
    @RequestWrapper(localName = "sayHelloResponse",
                     targetNamespace = "http://project1/",
                     className = "project1.SayHelloResponse")
    public void sayHello(@WebParam(targetNamespace = "", name = "return")
        String ret) {

And then the code is really quite simple, in this case we publish the endpoint and then invoke the service. Note we use the @OneWayFeature to populate the required WS-Addressing features, this is a bit naughty as it is part of the -RI and doesn't support faults. For the purposes of this blog though it makes the code a mite easier to read.

The other thing to note is that the call to sayHello returns a "null" object, you can use the MessageContext to check the response code if you want to confirm a 202; but otherwise the rest of the action is deferred to the callback class at this point.

public static void main(String[] args) {
    helloService = new HelloService();
    Endpoint e = Endpoint.publish(
        new HelloCallback());

    WSEndpointReference replyTo = new WSEndpointReference(e.getEndpointReference());

    Hello hello = helloService.getHelloPort(new WebServiceFeature[] {
      new OneWayFeature(true, replyTo)});

    // This method will return null
    Object ret = hello.sayHello("Bob");

    // Check the message response code

    Integer responseCode = (Integer)     

One final note is that you need to force the client to exit as Endpoint.publish create a non-daemon thread.


Justin_R said...

Thanks so much Gerard. Your posts are the only ones I can find online teaching how to use JAX-WS and WS-Addressing to implement asynchronous invocations.

I am just wondering if there is a alternative annotation in JAX-WS spec of "@OneWayFeature". The "@AddressingFeature" could not take a replyTo Endpoint Reference.

Thanks again,


Gerard Davison said...


No problem, glad to be of service.

No alternative to OneWayFeature I am afraid. Probably worth raising a bug over at You can write you own though as JAX-WS RI is really quite extensible.

Might just not be an area they care about directly yet as glassfish as it only just starting to get deep into SOA where async services become more prevalent.


Mark H said...

Thanks for trying to explain this - I've been struggling for a few days to find an example of how to create a simple async service with jax-ws.
Unfortunately, I've not been able to get the example to work. When I send the message to the server, the following stack trace is output to the console and the method implementation is never called. Stream is closed
at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(
at java.util.concurrent.ThreadPoolExecutor$
Caused by: Stream is closed
... 21 more

Also, the stubs generated from the wsdl (jax-ws 2.1.7) do not contain @Action annotations (although the wsdl does contain wsaw:UsingAddressing and an action for the input)

Any ideas what I'm doing wrong? Or any chance that you could post full sources?

Gerard Davison said...

Mark H,

I am not sure, unfortunately I don't have the original code having been a bit to vigorous in tidying up my home directory.

If you have a simple example project you can send me in a .zip, you will need to alter the file extension to get past filters, to and I will take a look.


a.c.white said...

Thank you very much for the tutorial. I have a problem running it
though. I deployed the service and it can be easily used the standard
way. However when I want to utilize the callback, the main method runs
forever and doesn't return anything. When I stop it manually, Netbeans
comes up with the message: BUILD STOPPED.

Any advice?

Thanks is advance,

Gerard Davison said...


the java vm won't stop until you do a System.exit() and you have started a server. The trick is to do this after you have finished in the callback; but not during.


Aswin said...

Thanks for this article Gerad. It was so much useful while using CXF for this purpose. I have a post that shows the difference here.

Aswin said...

Thanks a lot of the article. It was really useful and I wrote a post that deals with the same situation , but using Apache CXF as the provider and is here

jasonray said...

Thanks a bunch. I have been struggling with this for a few days now, and am happy to see a good example. It seems like this is a need that could be handled by the stack, and the fact that it isn't almost makes me think that few are utilizing this feature in WS-Addressing.

Thanks again!

Hema said...

Thanks Gerard for writing such helpful post.

I was just wondering how shall i be able to verify that response comes to HelloCallBack and the required code is executed.

Your response will be really helpful.