Marc Hadley's Blog: May 2005 Archive

Steve Loughran and Edmund Smith of HP Labs have written an interesting piece on JAX-RPC and JAXM that discusses their suitability as programming models for Web services. Unfortunately much of their article ignores the advances we've made with JAX-WS (nee JAX-RPC 2.0). As co-spec lead for JAX-WS, I'd like to point out a couple of the salient features.

Much of the paper's thesis centres on the difficulty of XML<->Object mapping. I agree that this is a difficult problem - I'm not a member of the JAXB expert group but I've monitored the mailing list and have been regularly befuddled by the complexity of this undertaking. <grin>Fortunately that's now JAXB's problem not JAX-WS's</grin>. Using JAXB, JAX-WS still provides a WSDL<->Java capability as in JAX-RPC 1.1 (though now with support for all of XML Schema rather than a subset). However the JAX-WS EG recognized that in some (or many, depending on your perspective) cases working at the XML layer is useful/desirable and so we added a couple of XML-centric APIs that completely bypass the XML<->Object layer of the stack: Dispatch and Provider.

Dispatch is the client side API and uses the generic functionality introduced in J2SE 5.0 to offer an API that allows the developer to choose their abstraction. Developers can work with entire messages or message payloads either using XML APIs or using pre-cooked JAXB classes. Here are few examples:

Message payload using XML APIs:

javax.xml.transform.Source reqMsg = ...;
Service service = ...;
Dispatch<Source> disp = service.createDispatch(portName,
    javax.xml.transform.Source.class, PAYLOAD);
Source resMsg = disp.invoke(reqMsg);

Working directly with SOAP messages using XML APIs:

javax.xml.transform.Source reqMsg = ...;
Service service = ...;
Dispatch<Source> disp = service.createDispatch(portName,
    javax.xml.transform.Source.class, MESSAGE);
Source resMsg = disp.invoke(reqMsg);

Working with SAAJ SOAP messages:

javax.xml.soap.SOAPMessage soapReqMsg = ...;
Service service = ...;
Dispatch<SOAPMessage> disp = service.createDispatch(portName,
    javax.xml.soap.SOAPMessage.class, MESSAGE);
SOAPMessage soapResMsg = disp.invoke(soapReqMsg);

Finally, if you want to use JAXB separate from JAX-WS, message payload using JAXB objects:

JAXBContext jc = JAXBContext.newInstance("primer.po");
Unmarshaller u = jc.createUnmarshaller();
PurchaseOrder po = (PurchaseOrder)u.unmarshal(
    new FileInputStream( "po.xml" ) );
Service service = ...;
Dispatch<Object> disp = service.createDispatch(portName, jc, PAYLOAD);
OrderConfirmation conf = (OrderConfirmation)disp.invoke(po);

The Provider interface is the server side couterpart to Dispatch, here are a few illustrative examples:

Working with XML APIs to send a canned reply to every message:

@ServiceMode(value=Service.Mode.PAYLOAD)
public class MyService implements Provider<Source> {
    public MyService {
    }
    
    public Source invoke(Source request, Map<String,Object> context)
        throws RemoteException {
        Source requestPayload = request.getPayload();
        ...
        String replyElement = new String("<n:ack xmlns:n='...'/>");
        StreamSource reply = new StreamSource(new StringReader(replyElement));
        return reply;
    }
}

Simple echo service working with SAAJ SOAP messages:

@ServiceMode(value=Service.Mode.MESSAGE)
public class MyService implements Provider<SOAPMessage> {
    public MyService {
    }
    
    public SOAPMessage invoke(SOAPMessage request, Map<String,Object> context)
        throws RemoteException {
        return request;
    }
}

Using JAXB to read the input message and set the reply:

@ServiceMode(value=Service.Mode.PAYLOAD)
public class MyService implements Provider<Source> {
    public MyService {
    }
    
    public Source invoke(Source request, Map<String,Object> context)
        throws RemoteException {
        JAXBContent jc = JAXBContext.newInstance(...);
        Unmarshaller u = jc.createUnmarshaller();
        Object requestObj = u.unmarshall(request);
        ...
        Acknowledgement reply = new Acknowledgement(...);
        return new JAXBSource(jc, reply);
    }
}

Hopefully this taste of the new APIs will encourage everyone to check out the document centric features of JAX-WS.

WADL Revision

Posted by mhadley on May 24, 2005 at 01:33 PM | Permalink | Comments (2)

I got some useful feedback following the publication of the original version of the Web Application Description Language (WADL) and have revised the specification accordingly. Thanks particularly to Mark Nottingham and Philippe Le Hegaret for their useful comments, many of which are addressed in the latest version of the WADL specification (PDF) and WADL schema

Changes since the previous version:

Resources may now be nested. This allows the resources to be specified in a tree that closely parallels typical URI structures
I've added global operation groups as a lexical shortcut to specifying the same set of operations for multiple resources. This isn't quite a resource typing capability as requested by Mark but provides much the same functionality (IMO)
URIs are now used to refer to WADL components instead of XML QNames
Clarified escaping requirements for URIs with embedded parameters
Assorted other clarifications and additional explanatory text

Still to do:

Specify the extensibility model including scope and inheritance
Investigate registering a media type for WADL documents

The W3C has just created a mailing list for discussion of Web description, if you have comments or thoughts about WADL or similarly targetted description languages then why not join the list and share your ideas.

Introducing WADL

Posted by mhadley on May 13, 2005 at 02:16 PM | Permalink | Comments (2)

Seems like lots of folks are either doing it or talking about it (publishing proposals for alternatives to WSDL that is) so here's mine: Web Application Description Language (PDF) or WADL for short.

A number of Web based enterprises (Google, Yahoo, Amazon, Flickr to name but a few) are developing XML/HTTP based applications/services that provide access to their internal data. Anecdotal evidence suggests there's a lot of simple XML/HTTP integration going on within other companies too. Add to this the recent interest in AJaX and you're left with a need for a simple way to describe such applications and services.

WADL is designed to provide a simple alternative to WSDL for use with XML/HTTP Web applications. To date such applications have been mainly described using a combination of textual description and XML schema, WADL aims to provide a machine process-able description of such applications in a simpler format than is possible using WSDL.

Here's an example WADL description of the Yahoo news search application to illustrate the language:

01 <?xml version="1.0" standalone="yes"?>
02 <application targetNamespace="urn:yahoo:yn"
03  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
04  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
05  xmlns:yn="urn:yahoo:yn"
06  xmlns:tns="urn:yahoo:yn"
07  xmlns:ya="urn:yahoo:api"
08  xmlns="http://research.sun.com/wadl">
09    
10  <types>
11    <include 
12      href="http://.../NewsSearchService/V1/NewsSearchResponse.xsd"/>
13    <include
14      href="http://.../Api/V1/error.xsd"/>
15  </types>
16    
17  <resources>
18    <resource uri="http://.../NewsSearchService/V1/newsSearch">
19      <operationRef ref="tns:NewsSearch"/>
20    </resource>
21  </resources>
22    
23  <operation name="NewsSearch" method="get">
24    <request>
25      <parameter name="appid" type="xsd:string" required="true"/>
26      <parameter name="query" type="xsd:string" required="true"/>
27      <parameter name="type" type="xsd:string"/>
28      <parameter name="results" type="xsd:int"/>
29      <parameter name="start" type="xsd:int"/>
30      <parameter name="sort" type="xsd:string"/>
31      <parameter name="language" type="xsd:string"/>
32    </request>
33    <response>
34      <representation mediaType="text/xml" element="yn:ResultSet">
35        <parameter name="totalResults"
36          type="xsd:nonNegativeInteger"
37          path="/ResultSet/@totalResultsAvailable"/>
38        <parameter name="resultsReturned"
39          type="xsd:nonNegativeInteger"
40          path="/ResultSet/@totalResultsReturned"/>
41        <parameter name="resultPosition"
42          type="xsd:nonNegativeInteger"
43          path="/ResultSet/@firstResultPosition"/>
44        <parameter name="results" path="/ResultSet/Result"/>
45      </representation>
46      <fault name="SearchError" status="400"
47        mediaType="text/xml" element="ya:Error">
48        <parameter name="msg" path="/Error/Message"
49          type="xsd:string"/>
50      </fault>
51    </response>
52  </operation>
53</application>

Lines 2-8 begin an application description and define the XML namespaces used elsewhere in the service description. Lines 10-15 define the XML schemas used by the service, in this case two schemas are included by reference. Lines 17-21 describe the Yahoo News Search Web resource and the operations it supports. Lines 23-52 describe the NewsSearch operation: lines 24-32 describe the inputs to the operation; lines 33-51 describe the possible outputs of the operation.

The WADL specification (PDF) and WADL schema describe the features of the language in detail but a few points are worth highlighting:

Generative URIs are handled by including support for parameterization of URI components.
The base set of HTTP methods (GET, POST, PUT, DELETE, HEAD) are specifically supported by the WADL schema but the method enumeration is open to use with other methods such as those specified by WebDAV.
Representation parameters are hints to processors that point out interesting parts of a resource representation. As such they may be used or ignored as desired. I think they'll be useful for RPC-like interactions but less so for more document oriented work.
Sibling representation elements represent alternative representations of the same resource. This means you can describe a resource that is offered in alternate formats, e.g. XML or HTML.
The design center is XML/HTTP but this doesn't preclude use with alternate representation formats: the representation/@mediaType attribute provides the necessary hook.

I'm currently working on a WADL to Java compiler and will report back as things progress.

Powered by
Movable Type 3.01D

java.net RSS Feeds