RESTful Web Services API

Sono state rilasciate da Sun in early access le API per lo sviluppo di web services RESTful.
Queste API fanno parte del Sun Web Development Pack e qui di seguito voglio mostrarvi un semplice esempio di utilizzo.

Supponiamo di voler esporre un servizio web di formattazione della data corrente in un formato deciso dal client. Più in dettaglio vorremmo che un client connettendosi ad alla URL

http://127.0.0.1:9998/swdp-restexample/dateformatter/format=EEEE dd/MM/yyyy HH:mm:ss Z

voglia ottenere la data corrente nel formato specificato come parametro:

EEEE dd/MM/yyyy HH:mm:ss Z

Costruiamo quindi il nostro POJO :

@UriTemplate("/dateformatter/format={dateformat}")
public class DateFormatter {

    /** Creates a new instance of DateFormatter */
    public DateFormatter() {
    }
   
    @HttpMethod("GET")
    @ProduceMime("text/plain")   
    public Representation format(@UriParam("dateformat")String dateformat) {
       
        /** Crea un formatter in base al pattern fornito */
        SimpleDateFormat formatter= new SimpleDateFormat(dateformat);
       
        /** Restituisce la data formattata secondo il pattern */
        return new StringRepresentation(formatter.format(new Date()));
       
    }
}

Come si può osservare, il POJO DateFormatter è annotato con @UriTemplate che specifica l'URI del servizio e ha un metodo format, annotato come @HttpMethod("GET").
Tale metodo accetta un parametro che rappresenta il pattern di formattazione della data, annotato come @UriParam.

Con queste semplici annotazioni, abbiamo creato un servizio web che ci permette di formattare la data corrente secondo il pattern fornito nella URL di richiesta HTTP GET.

A questo punto non ci resta che deployare il servizio attraverso un HttpServer:

public class Main {
   
    /** Creates a new instance of Main */
    public Main() {
    }
   
    /**
     * @param args the command line arguments
     */
    public static void main(String[] args) {
        try {
            HttpHandler handler = HttpHandlerFactory.create("swdp.rest.beans");
            final HttpServer server = HttpServer.create(new InetSocketAddress(9998), 0);
            server.createContext("/swdp-restexample", handler);
            server.setExecutor(null);
           
            Runnable r = new Runnable() {
                public void run() {
                    server.start();
                }
            };
           
            new Thread(r).start();
           
            System.out.println("Server running, hit return to stop...");
            System.out.println("Il formatter è raggiungibile all'url: http://localhost:9998/swdp-restexample/dateformatter/format={dateformat}");
            System.in.read();
            System.out.println("Stopping server");
           
            server.stop(0);
            System.out.println("Server stopped");
        } catch (WebApplicationException ex) {
            ex.printStackTrace();
        } catch (IOException ex) {
            ex.printStackTrace();
        }
    }   
}

Affinchè il tutto funzioni correttamente e vengano creati gli artifact necessari, occorre compilare utilizzando APT. Di seguito è ripostato il file di build.xml utilizzato nel progetto NetBeans:

<?xml version="1.0" encoding="UTF-8"?>
<project name="SWDP-RESTExample" default="default" basedir=".">
    <description>Builds, tests, and runs the project SWDP-RESTExample.</description>
    <import file="nbproject/build-impl.xml"/>
   <target name="-post-init">
        <mkdir dir="gen-src"/>
    </target>
   
    <target name="-post-clean">
        <delete dir="gen-src"/>
    </target>
   
    <property name="javac.source"  value="1.5"/>
    <property name="javac.target"  value="1.5"/>
   
    <property name="file.reference.tools.jar" value="${java.home}/../lib/tools.jar"/>
    <condition property="file.reference.tools.jar" value="${java.home}/lib/tools.jar">
        <available type="file" file="${java.home}/lib/tools.jar"/>
    </condition>
   
    <property name="file.reference.jaxws-tools.jar"  value="/lib/jaxws-tools.jar"/>

    <path id="apt.classpath.id">
        <pathelement location="${file.reference.tools.jar}"/>
        <pathelement location="${file.reference.jaxws-tools.jar}"/>
    </path>   
   
    <taskdef name="apt" classname="com.sun.tools.ws.ant.Apt">
        <classpath refid="apt.classpath.id"/>
    </taskdef>
    <target name="-pre-compile">
        <echo message="Processing resource classes"/>
        <echo message="${file.reference.jaxws-tools.jar}"/>
        <echo message="${file.reference.tools.jar}"/>       
        <apt fork="true" destdir="${build.classes.dir}"
             sourcedestdir="gen-src" sourcePath="${src.dir}">
            <classpath>
                <path refid="apt.classpath.id"/>
                <path path="${javac.classpath}"/>
                <pathelement location="${build.dir}"/>
            </classpath>                
            <option key="restbeansdestdir" value="."/>
            <option key="restbeanpkg" value="swdp.rest.beans"/>
            <option key="noservlet"/>
            <source dir="${src.dir}">
                <include name="**/*.java"/>
            </source>
        </apt>   
        <copy todir="${build.classes.dir}">
            <fileset dir="${src.dir}" excludes="**/*.java"/>
        </copy>
    </target>   
</project>

Il risultato ottenuto invocando l'URL http://127.0.0.1:9998/swdp-restexample/dateformatter/format=EEEE dd/MM/yyyy HH:mm:ss Z è il seguente:

domenica 15/04/2007 16:21:36 +0200

Per approfindimenti scaricate il Sun Web Development Pack contenente diversi esempi di sviluppo di RESTFul Web Services e leggete la Getting Started Guide