-k.

I’m happy to annouce that version 0.3 of Jacket is ready and available from the usual location.

The release is mainly focused on increased documentation. There are a couple of minor changes in the base xml handling but nothing that will break current code.

Release Features:

• Added lots of Javadoc
• Added a short introduction (access via the package description)
• Use Ivy for dependency management

Upcomming Features

• REST service support

A copy of the introduction has been posted if you just want to get a feel for how it’s used without downloading the full release.

Jacket is a very simple package for handling Document/Literal SOAP messages. The intent is to keep the
framework out of the way and allow the programmer to process the XML components of the message.

The Client

To invoke a SOAP service the first thing you need is a SoapClient.
The client is used to invoke RequestHandler or
SoapRequestHandler objects. It handles the transport of the payloads,
negotiating things like proxies, the handlers do the payload processing.

Creation is pretty simple.

SoapClient client = new SoapClient();

If you need to go through a proxy then you just need to supply the configuration

ProxyConfiguration proxy = new ProxyConfiguration(new ProxyHost("proxy", 3128));
SoapClient client = new SoapClient(proxy);

Now that you have a client all you need is a request handler.

Request Handlers

RequestHandler instances do the payload processing. The prepare the body of
the request and respond to the result. A SoapRequestHandler also allows
you to specify processing for header elements.

public class DilbertRequest extends SoapRequestHandler

{
        static final String NAMESPACE = "http://tempuri.org/";
        static final String TARGET = "http://www.esynaps.com/WebServices/DailyDiblert.asmx";
        static final String ACTION = "http://tempuri.org/DailyDilbertImagePath";

        String _imagePath;

        public DilbertRequest() throws URISyntaxException
        {
                super(new URI(TARGET));
        }

        public String getImagePath()
        {
                return _imagePath;
        }

        public String getAction()
        {
                return ACTION;
        }

        public boolean hasRequestBody()
        {

                return true;
        }

        public void writeRequestBody(XMLStreamWriter request) throws XMLStreamException
        {
                request.writeStartElement("DailyDilbertImagePath");
                request.writeDefaultNamespace(NAMESPACE);
                request.writeEndElement();
        }

        public void readResponseBody(XMLEventReader response) throws XMLStreamException
        {
                DilbertResponseReader reader = new DilbertResponseReader(new StringValueCallback()
                {
                        public void value(String value)
                        {
                                _imagePath = value;
                        }
                });
                reader.read(response);
        }
}

In the above sample (that gets a link to todays Dilbert cartoon) we simply:

• Provided the target url via the constructor and action by overridding SoapRequestHandler.getAction()
• Tell the SoapClient that we have some information to send with the request by overridding RequestHandler.hasRequestBody() and write it in the overridden RequestHandler.writeRequestBody(XMLStreamWriter).
• Read the result by overridding RequestHandler.readResponseBody(XMLEventReader)

Running

Now all we need to do now is invoke our request

DilbertRequest request = new DilbertRequest();
client.invoke(request);
System.out.println("Todays Dilbert can be found at: " + request.getImagePath());

Now wasn’t that simple?

Over the last couple of nights I’ve been working to shore up the jacket javadoc and started writing a short introduction / tutorial. I plan to release a new version early next week.

I’m interested in getting peoples opinions on what to do with the fault detail node. At the moment it’s ignored but obviously this can’t go on forever. My initial thought has been to store the StAX events for the node and allow you to access the information via an event reader. What do you think? What features are you looking for?

As a side note I’ve just created a mailing list for those interested in jacket development.

XStream is one of those libraries that you keep asking yourself "what did I do before I used this?" (picocontainer is another one). It's smallish, clean and simple to use. More importatnly it has well defined extension points tht allow you to build additional, more specific code upon. Look for a jacket sample that take advantage of it "real soon now".

A new version (0.2) of Jacket which fixes a bug in fault handling, allows you to set proxy information and includes a simple sample that retrieves the location of the current Dilbert strip (much more interesting than the weather ) is available from the project page.

Version 0.2 (31-05-2005)

• Added proxy configuration
• Fixed a bug in SOAP Fault handling
• Added the Dilbert sample

I’ve just completed work on the first public version of my SOAP client Jacket. An intentionally simple client that gives you control of the result document processing.

You’ll find an all to short set of notes and access to the downloads at http://kevin.oneill.id.au/jacket/. Take a look and let me know what you think.