JAX-WS and REST, anyone?

[Ulf Dittmer]

Trying to simplify the WS infrastructure, I'm playing with JAX-WS for implementing REStful WS. The client side is easy enough, but it seems that the server-side isn't widely explored (or at the least not publicly written about). In particular, I'm looking for a way to have a URL like

http://ws.server.com/api/doTheRestThing/ulf/42

automatically routed to a method that's declared to handle the operation "doTheRestThing", and pass the parameters "ulf" and "42" to it. Mapping the operation is the easy part, but how are parameters handled? Does anyone have an example? Is this really as simple as it gets?

[William Brogden]

I did some playing around with the service end of REST. Rather than mapping the request to a method, I mapped the request to a class - using an XML configuration file. Each class had its own doGet( request, response ) so taking apart the parameters was delegated to the class.

After much wheel-spin with class loaders I got it to where I could add a new class to the configuration without restarting the server thus making the debug cycle much faster.

Bill

[Peer Reynders]

Well, for comparison sake this is the beginning of a Restlet version.

package com.javaranch.api.rest;
 
import org.restlet.Component;
import org.restlet.Restlet;
import org.restlet.data.MediaType;
import org.restlet.data.Protocol;
import org.restlet.data.Request;
import org.restlet.data.Response;
 
/* based on Jerome Louvel's tutorial Part05 */
 
public class DoTheRestThing {
 
    public static void main(String[] args) throws Exception {
 
        // Create a new Restlet component and add a HTTP server connector to it
        Component component = new Component();
        component.getServers().add(Protocol.HTTP, 8080);
 
        // Create a new tracing Restlet
        Restlet restlet = new Restlet() {
            @Override
            public void handle(Request request, Response response) {
                // Print the remaining URI
                String message = request.getResourceRef().getRemainingPart();
 
                response.setEntity(message, MediaType.TEXT_PLAIN);
            }
        };
 
        // Then attach it to the local host
        component.getDefaultHost().attach("/api/doTheRestThing", restlet);
 
        // Now, let's start the component!
        // Note that the HTTP server connector is also automatically started.
        component.start();
    }
}

I wouldn't be surprised if the JAX-WS REST support will vanish in future versions if JSR 311: JAX-RS: The Java� API for RESTful Web Services goes anywhere.

[Peer Reynders]

FYI: Currently wadl2java only supports client side stubs. So for interest sake I whipped together a WADL:

<?xml version="1.0"?>
<application
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:tns="http://javaranch.com/dotherestthing"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:html="http://www.w3.org/1999/xhtml"
    xmlns="http://research.sun.com/wadl/2006/10">
 
  <grammars>
    <xsd:schema elementFormDefault="qualified"
        targetNamespace="http://javaranch.com/dotherestthing"
        xmlns:tns="http://javaranch.com/dotherestthing"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
 
      <xsd:complexType name="UserDetailsType">
        <xsd:sequence>
          <xsd:element name="username" type="xsd:string"/>
          <xsd:element name="userid"   type="xsd:int"/>
        </xsd:sequence>
      </xsd:complexType>
 
      <xsd:element name="userdetails" type="tns:UserDetailsType"/>          
    </xsd:schema>
  </grammars>
 
  <resources base="http://localhost:8080/api/v1/">
 
    <resource path="doTheRestThing/{userName}/{userId}/">
      <method name="GET" id="echo">
        <request>
          <param name="userName" style="template" type="xsd:string"/>
          <param name="userId" style="template" type="xsd:int"/>
        </request>
        <response>
            <representation mediaType="application/xml" element="tns:userdetails" />
        </response>
      </method>
    </resource>
 
  </resources>
</application>

and generated the code

java -jar wadl2java.jar -o . -p com.javaranch.api.rest  doTheRestThing.wadl

This resulted in four files: package-info.java, UserDetailsType.java, ObjectFactory.java and Endpoint.java
package-info.java

@javax.xml.bind.annotation.XmlSchema(namespace = "http://javaranch.com/dotherestthing",
elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED)
package com.javaranch.api.rest;

UserDetailsType.java

package com.javaranch.api.rest;
 
import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlType;
 
 
/**
 * <p>Java class for UserDetailsType complex type.
 * 
 * <p>The following schema fragment specifies the expected content contained within this class.
 * 
 * <pre>
 * <complexType name="UserDetailsType">
 *   <complexContent>
 *     <restriction base="{http://www.w3.org/2001/XMLSchema}anyType">
 *       <sequence>
 *         <element name="username" type="{http://www.w3.org/2001/XMLSchema}string"/>
 *         <element name="userid" type="{http://www.w3.org/2001/XMLSchema}int"/>
 *       </sequence>
 *     </restriction>
 *   </complexContent>
 * </complexType>
 * </pre>
 * 
 * 
 */
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "UserDetailsType", propOrder = {
    "username",
    "userid"
})
public class UserDetailsType {
 
    @XmlElement(required = true)
    protected String username;
    protected int userid;
 
    /**
     * Gets the value of the username property.
     * 
     * @return
     *     possible object is
     *     {@link String }
     *     
     */
    public String getUsername() {
        return username;
    }
 
    /**
     * Sets the value of the username property.
     * 
     * @param value
     *     allowed object is
     *     {@link String }
     *     
     */
    public void setUsername(String value) {
        this.username = value;
    }
 
    /**
     * Gets the value of the userid property.
     * 
     */
    public int getUserid() {
        return userid;
    }
 
    /**
     * Sets the value of the userid property.
     * 
     */
    public void setUserid(int value) {
        this.userid = value;
    }
 
}

ObjectFactory.java

package com.javaranch.api.rest;
 
import javax.xml.bind.JAXBElement;
import javax.xml.bind.annotation.XmlElementDecl;
import javax.xml.bind.annotation.XmlRegistry;
import javax.xml.namespace.QName;
 
 
/**
 * This object contains factory methods for each 
 * Java content interface and Java element interface 
 * generated in the com.javaranch.api.rest package. 
 * <p>An ObjectFactory allows you to programatically 
 * construct new instances of the Java representation 
 * for XML content. The Java representation of XML 
 * content can consist of schema derived interfaces 
 * and classes representing the binding of schema 
 * type definitions, element declarations and model 
 * groups.  Factory methods for each of these are 
 * provided in this class.
 * 
 */
@XmlRegistry
public class ObjectFactory {
 
    private final static QName _Userdetails_QNAME =
        new QName("http://javaranch.com/dotherestthing", "userdetails");
 
    /**
     * Create a new ObjectFactory that can be used to create new instances
     * of schema derived classes for package: com.javaranch.api.rest
     * 
     */
    public ObjectFactory() {
    }
 
    /**
     * Create an instance of {@link UserDetailsType }
     * 
     */
    public UserDetailsType createUserDetailsType() {
        return new UserDetailsType();
    }
 
    /**
     * Create an instance of {@link JAXBElement }{@code <}{@link UserDetailsType }{@code >}}
     * 
     */
    @XmlElementDecl(namespace = "http://javaranch.com/dotherestthing", name = "userdetails")
    public JAXBElement<UserDetailsType> createUserdetails(UserDetailsType value) {
        return new JAXBElement<UserDetailsType>(_Userdetails_QNAME, UserDetailsType.class, null, value);
    }
 
}

Endpoint.java

package com.javaranch.api.rest;
 
import java.io.IOException;
import java.net.MalformedURLException;
import java.util.HashMap;
import java.util.List;
import javax.activation.DataSource;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
import com.sun.research.ws.wadl.util.DSDispatcher;
import com.sun.research.ws.wadl.util.JAXBDispatcher;
import com.sun.research.ws.wadl.util.UriBuilder;
 
public class Endpoint {
 
 
    public static class DoTheRestThingUserNameUserId {
 
        private JAXBDispatcher _jaxbDispatcher;
        private DSDispatcher _dsDispatcher;
        private UriBuilder _uriBuilder;
        private JAXBContext _jc;
        private HashMap<String, Object> _templateAndMatrixParameterValues;
 
        /**
         * Create new instance
         * 
         */
        public DoTheRestThingUserNameUserId(String username, String userid)
            throws JAXBException
        {
            _jc = JAXBContext.newInstance("com.javaranch.api.rest");
            _jaxbDispatcher = new JAXBDispatcher(_jc);
            _dsDispatcher = new DSDispatcher();
            _uriBuilder = new UriBuilder();
            List<String> _matrixParamSet;
            _matrixParamSet = _uriBuilder.addPathSegment("http://localhost:8080/api/v1/");
            _matrixParamSet = _uriBuilder.addPathSegment("doTheRestThing/{userName}/{userId}/");
            _templateAndMatrixParameterValues = new HashMap<String, Object>();
            _templateAndMatrixParameterValues.put("userName", username);
            _templateAndMatrixParameterValues.put("userId", userid);
        }
 
        /**
         * Get userName
         * 
         */
        public String getUserName() {
            return ((String) _templateAndMatrixParameterValues.get("userName"));
        }
 
        /**
         * Set userName
         * 
         */
        public void setUserName(String username) {
            _templateAndMatrixParameterValues.put("userName", username);
        }
 
        /**
         * Get userId
         * 
         */
        public String getUserId() {
            return ((String) _templateAndMatrixParameterValues.get("userId"));
        }
 
        /**
         * Set userId
         * 
         */
        public void setUserId(String userid) {
            _templateAndMatrixParameterValues.put("userId", userid);
        }
 
        public DataSource getAsApplicationXml()
            throws IOException, MalformedURLException
        {
            HashMap<String, Object> _queryParameterValues = new HashMap<String, Object>();
            HashMap<String, Object> _headerParameterValues = new HashMap<String, Object>();
            String _url = _uriBuilder.buildUri(_templateAndMatrixParameterValues, _queryParameterValues);
            DataSource _retVal = _dsDispatcher.doGET(_url, _headerParameterValues, "application/xml");
            return _retVal;
        }
 
        public UserDetailsType getAsUserDetailsType()
            throws IOException, MalformedURLException, JAXBException
        {
            HashMap<String, Object> _queryParameterValues = new HashMap<String, Object>();
            HashMap<String, Object> _headerParameterValues = new HashMap<String, Object>();
            String _url = _uriBuilder.buildUri(_templateAndMatrixParameterValues, _queryParameterValues);
            Object _retVal = _jaxbDispatcher.doGET(_url, _headerParameterValues, "application/xml");
            if (_retVal == null) {
                return null;
            }
            return ((UserDetailsType) _retVal);
        }
 
        public DataSource getAsApplicationXml(String username, Integer userid)
            throws IOException, MalformedURLException
        {
            HashMap<String, Object> _queryParameterValues = new HashMap<String, Object>();
            HashMap<String, Object> _headerParameterValues = new HashMap<String, Object>();
            _headerParameterValues.put("userName", username);
            _headerParameterValues.put("userId", userid);
            String _url = _uriBuilder.buildUri(_templateAndMatrixParameterValues, _queryParameterValues);
            DataSource _retVal = _dsDispatcher.doGET(_url, _headerParameterValues, "application/xml");
            return _retVal;
        }
 
        public UserDetailsType getAsUserDetailsType(String username, Integer userid)
            throws IOException, MalformedURLException, JAXBException
        {
            HashMap<String, Object> _queryParameterValues = new HashMap<String, Object>();
            HashMap<String, Object> _headerParameterValues = new HashMap<String, Object>();
            _headerParameterValues.put("userName", username);
            _headerParameterValues.put("userId", userid);
            String _url = _uriBuilder.buildUri(_templateAndMatrixParameterValues, _queryParameterValues);
            Object _retVal = _jaxbDispatcher.doGET(_url, _headerParameterValues, "application/xml");
            if (_retVal == null) {
                return null;
            }
            return ((UserDetailsType) _retVal);
        }
 
    }
 
}

I think things may become a bit clearer once wadl2java supports the generation of server-side skeletons - however the handling of the link elements in the WADL could prove interesting.

[ UD: added a few linebreaks to preserve the layout ]
[ November 26, 2007: Message edited by: Ulf Dittmer ]