Building an async JAX-WS from the bottom up.

Now and then in JDeveloper land we have an organization wide bug hunt to improve the overall quality of our product. For the most recent one I decided to try to write a async web service from the bottom up.

For the purposes of this experiment I am going to create a simple HelloWorld example so first off lets created the primary interface:

package model;

import ...;

@WebService
public class Hello
{

  public void sayHello(String name)
  {
  ...
  }
}

And of course we need to define the interface for the callback service:

package model;

@WebService
public interface HelloCallback
{
  public void response(String message);
}

Simple enough, right? Now I we are going to create a static wsdl under public_html/wsdl. Use the normal wizard to create a blank document then cut and paste the results of "Show WSDL for annotations" from the Hello class. You also need to do something similar for the HelloCallback service. Unfortunately you can't show the WSDL for a SEI, although I have raised that bug, so the quickest way to generate the WSDL content is to temporarily convert HelloCallback to a class.

To complete the WSDL add a partnerLinkType, this is used by tools such as BPEL to link the two halves of the equation:

    <partnerLinkType name="HelloService"
                     xmlns="http://schemas.xmlsoap.org/ws/2003/05/partner-link/">
        <role name="In">
            <portType name="tns:Hello"/>
        </role>
        <role name="Out">
            <portType name="tns:HelloCallBack"/>
        </role>
    </partnerLinkType>

Then it is worth updating the Hello class to reference this WSDL in the annotations:

package model;

@WebService(wsdlLocation = "/wsdl/Hello.wsdl")
public class Hello 
{
  ...
}

Okay so the specifications are in place lets look at a trivial implementation of the sayHello method. Note that in this case the response can arrive before the original call has completed; but this will do for this example.

SOAPMessageContext smc = (SOAPMessageContext)_context.getMessageContext();
        
// Get hold of the AddressingProperties and look up the reply to address
// and later the return message id
//
        
AddressingProperties ap = AddressingUtils.getAddressingProperties(smc.getMessage());
EndpointReference endpointReference = ap.getReplyTo();
AttributedURI address = endpointReference.getAddress();
URI replyTo = address.getURI();
        
// 

try
{

  // Use the servlet context to get a reference to the local wsdl
  //  

  ServletContext sc = (ServletContext)_context.getMessageContext().get(
    "javax.xml.ws.servlet.context");
  URL found = sc.getResource("/wsdl/Hello.wsdl");
 
  // Create a new service instance on the callback

  Service s = Service.create(found, new QName(
                             "http://model/",
                             "HelloCallBackService"));
            
  // Create a port

  HelloCallBack acb = s.getPort(
           new QName(
               "http://model/",
               "HelloCallBackPort"),
               HelloCallBack.class); 
            
  BindingProvider bp = (BindingProvider)acb;
  Map requestProperties = bp.getRequestContext();

  // Change the endpoint address to the match the replyTo address
            
  requestProperties.put(
    BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
    replyTo.toString());

  // Make sure that this request has the correct addressing headers
            
  AddressingUtils.setupClientSideWSAddressing(requestProperties);
  String t = requestProperties.keySet().toString();
  AddressingProperties rap = 
    AddressingUtils.getOutboundAddressingProperties(requestProperties);
  rap.setRelatesTo(
    ap.getMessageID());
       
  // Invoke the response address
  //
     
  acb.response("Hello " + name);
}
catch (Exception ex) {
  ex.printStackTrace();            
}
        

Part of the pleasure of using JAX-WS over JAX-RPC is the simplicity of invoking services dynamically in this way. As you can see above this is actually really quite straight forward.

So how would you go about testing this, well the HTTP Analyzer in JDeveloper doesn't support WS-Addressing headers properly although we are working on this. You can of course create your own headers in the HTTP Content view, it might look like this:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Header xmlns:ns1="http://www.w3.org/2005/08/addressing">
      <ns1:MessageID>ws:uniqueAddress</ns1:MessageID>
      <ns1:ReplyTo>
         <ns1:Address>http://returnAddress.com/example</ns1:Address>
      </ns1:ReplyTo>
   </soap:Header>
   <soap:Body xmlns:ns2="http://model/">
      <ns2:sayHello>
         <arg0>John</arg0>
      </ns2:sayHello>
   </soap:Body>
</soap:Envelope>

If you start up the HTTP Analyzer before the embedded server you can send his message to the endpoint and you should see the failed attempt to send the message to the returnAddress url in the analyzer log. It should look something like:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://www.w3.org/2005/08/addressing">
   <env:Header>
      <wsa:To>http://returnAddress.com/example</wsa:To>
      <ns1:MessageID>ws:anotherUniqueAddress</ns1:MessageID>
      <wsa:RelatesTo xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:mustUnderstand="0">ws:uniqueAddress</wsa:RelatesTo>
   </env:Header>
   <env:Body>
      <ns0:response xmlns:ns0="http://model/">
         <arg0 xmlns="">Hello John</arg0>
      </ns0:response>
   </env:Body>
</env:Envelope>

This is worth remembering this trick if you are trying to test a async web service and don't want to go to the bother of setting up a valid return address to connect to.

Next time I get a few minutes I will take a look at the client side of this equation. Back to fixing the bugs I have just found.

A viewlet showing Abbot being used to test relatively complex UI

As I have mentioned previously we have been playing with Abbot and Costello internally in order to automate testing of some of our UI. When you start working Abbot/Costello there is a steep learning curve with people not sure that they will ever get there tests run more than once. (Some of the reasons I have talked about before.) Once you get the hang of things though setting up tests becomes much easier with recording tests becoming a normal part of the working day.

I figured it would be usefully to publish a viewlet showing abbot testing some relatively meaty UI. So here is a recording of current smoke tests for JDeveloper web services tooling which were created in Costello and run using Abbot.

There are a few glitches in that some context menu are not recorded and the playback speed is slower than the tests actually run on my machine. In general though this gives a fair representation of a test run on my machine. Also if you look carefully you will notice some bugs that the tests are not picking up; but I will leave that as an exercise for the reader to figure out what is wrong.

More than meets the eye, or JAX-WS and the not so obvious interfaces.

I really enjoy using JAX-WS I have only come to web services relatively recently but I have found the programming model to be relatively easy to use. Certainly removing the need to create n xml mapping files has made the developer's life much easier.

One problem I have with the design of JAX-WS it the way that you end up having to cast common objects to other helper interfaces. Now most of the implementation is done using proxies so in most debuggers you are going to have a hard time understanding the objects you are passed. Lets just knock up a quick method to list all the interfaces for a bit of debugging:

public class Util
{
    public static void dumpInterfaces(Class t)
    {
       System.out.println("=== Interfaces for " + t.getSimpleName());
       List interfaces = new ArrayList();
       interfaces.add(t);
       for (int i=0; i < interfaces.size(); i++) {
           Class it = interfaces.get(i);
           for (Class sp : it.getInterfaces()) {
               if (!interfaces.contains(sp))
               {
                 interfaces.add(sp);
               }
           }
       }
       
       // List them out
       //
       
       for (Class sp : interfaces)
       {
         System.out.println(sp.getName());
       }
    }

    public static  void dumpMap(String name, Map map) 
    {
        System.out.println("=== " + name);
        for(Map.Entry e : map.entrySet()) {
            System.out.println(e.getKey() + " : " + e.getValue());
        }
    }
}

On the server side lets take a look at what interfaces that might not otherwise be obvious, take this simple web service example:

@WebService
public class Hello {
    
    @Resource
    private WebServiceContext context;
    
    
    public String sayHello(String name) {
        
        Util.dumpInterfaces(context.getClass());
        Util.dumpInterfaces(context.getMessageContext().getClass());
        
        Util.dumpMap("Dumping message context properties",context.getMessageContext());        
        
        return "Hello " + name;
    }
}

This gives the following output for the interfaces. The web service context is less interesting that the message context. This can be cast to SOAPMessageContext which can give you access to the original SOAP message along with the headers. This is an alternative to using Handlers in order to process headers.

=== Interfaces for WebServiceContextImpl
oracle.j2ee.ws.server.jaxws.WebServiceContextImpl
javax.xml.ws.WebServiceContext
=== Interfaces for SOAPMessageContextImpl
oracle.j2ee.ws.common.jaxws.SOAPMessageContextImpl
javax.xml.ws.handler.soap.SOAPMessageContext
javax.xml.ws.handler.MessageContext
java.util.Map

The since the message context is also a map it is relatively easy to list all of the properties defined in there. Here is what I see when I run the service defined above. Part of the problem with JAX-WS is that these properties are extensible so it is hard to get a definitive list of all of them. Something for a future blog I think.

=== Dumping message context properties
javax.xml.ws.binding.attachments.inbound : {}
javax.xml.ws.http.request.pathinfo : null
incomming.addressing.properties : amespace=http://www.w3.org/2005/08/addressing
javax.xml.ws.servlet.context : Application1-Project1-webapp web-app
javax.xml.ws.http.request.querystring : null
javax.xml.ws.http.response.code : null
javax.xml.ws.http.response.headers : null
javax.xml.ws.servlet.request : com.evermind.server.http.EvermindHttpServletRequest@109b23b
oracle.j2ee.ws.context.Message : oracle.j2ee.ws.saaj.soap.soap11.Message11@1945696
javax.xml.ws.binding.attachments.outbound : {}
javax.xml.ws.servlet.response : com.evermind.server.http.EvermindHttpServletResponse@1c0bec5
javax.xml.ws.http.request.headers : {SOAPACTION=[""], CONNECTION=[Keep-Alive, TE], CONTENT-LENGTH=[202], USER-AGENT=[Oracle HTTPClient Version 10h], TE=[trailers, deflate, gzip, compress], ACCEPT-ENCODING=[gzip, x-gzip, compress, x-compress], CONTENT-TYPE=[text/xml; charset=ASCII], HOST=[localhost:8988], ECID-CONTEXT=[HIINUXQV`[YegG@DKKGSLNWWZZ[Zbef@BKCAGSLNS[TQ]}
javax.xml.ws.http.request.method : POST
javax.xml.ws.handler.message.outbound : false

We can do something similar with the on the client side, so if we were to create a simple client:

public class Client {
    public Client() {
    }
    
    public static void main(String argv[]) {
        HelloService hs = new HelloService();
        Hello h = hs.getHelloPort();
        Util.dumpInterfaces(h.getClass());
        
        BindingProvider bp = (BindingProvider)h;
        Util.dumpInterfaces(bp.getBinding().getClass());
        Util.dumpMap("Request context",bp.getRequestContext());
        Util.dumpMap("Response context",bp.getResponseContext());
    }
}

We can see that the port is implemented using a proxy object that implement both the SEI and the BindingProvider interface. The BindingProvider interface is perhaps not that much of a secret, although I would have thought that a more usable design for the client generation would have seen the SEI extend this interface to make the programming model cleaner.

=== Interfaces for $Proxy12
$Proxy12
project1.proxy.Hello
javax.xml.ws.BindingProvider
=== Interfaces for SOAPBindingImpl
oracle.j2ee.ws.client.jaxws.SOAPBindingImpl
javax.xml.ws.soap.SOAPBinding
javax.xml.ws.Binding
=== Request context
javax.xml.ws.binding.attachments.outbound : {}
=== Response context

It is worth noting that again there is a SOAP variant that you need to cast to in order to get all of the functionality available to you. Of course you have to be careful that you understand the context of your service. For example if you were to using the HTTP binding than the Binding object would of course be HTTP not SOAPBinding.

Finally where I have dumped out a the contents of a map, these represent the current state when running on an interim build of OC4J 11. As noted before there are many more properties that are available that can be added depending on what platform and extensions you are using.

Update: A nice summary document for the standard MessageContext and BindingContext parameters can be found here.

Q: How do I monitor outgoing HTTP Traffic in OC4J, or any other java app for that matter

Make sure that -Dhttp.proxyHost or -Dhttp.proxyPort is set

When you use the HTTP Analyzer within JDeveloper you will find that all java processes started from then on will send there traffic via the HTTP Analyzer. This includes the embedded oc4j instance. This can be useful if your service is using external services such as a credit card validation system.

Is the relatively straight forward to do this trick for any java process that might have been started outside of JDeveloper. You simply need to supply something like -Dhttp.proxyHost=localhost -Dhttp.proxyPort=8099 to the java executable. You can of course alter the host name if the process is running on a different machine.

If you are running an instance of oc4j you tend to do this with with oc4j or oc4j.bat. These both read the environment variable OC4J_JVM_ARGS which can contain the parameters mentioned above.

This may not capture all traffic between SOA services, such as BPEL, as in some cases inter-process communicate will skip the "HTTP Protocol" stack and exchange infosets more directly. This is something we will of course look at in future releases.