<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="howto-use-jaxrs"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:m="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <title>Use JAX-RS 1.1 in JOnAS</title>

  <section>
    <title>Introduction</title>

    <para>JAX-RS stands for <emphasis>J</emphasis>ava <emphasis>A</emphasis>PI
    for <emphasis>X</emphasis>ML <emphasis>R</emphasis>ESTful
    <emphasis>S</emphasis>ervices (JAX-RS). It's a Java EE 6 specification
    that introduces the <link
    xlink:href="http://en.wikipedia.org/wiki/Representational_State_Transfer">REST</link>
    support in the Java EE platform.</para>

    <para>Its goal is to provide an easy to use REST development model based
    on annotations for the Java platform. It's a <emphasis>server-side
    only</emphasis> specification (no client API is described).</para>

    <para>The developer is responsible to declare REST
    <emphasis>resources</emphasis> that will act as entry point to its
    application:</para>

    <para><programlisting>// The Java class will be hosted at the URI path "/helloworld"
@Path("/helloworld")
public class HelloWorldResource {

    // The Java method will process HTTP GET requests
    @GET 
    // The Java method will produce content identified by the MIME Media type "text/plain"
    @Produces("text/plain")
    public String helloWorld() {
        // Return some cliched textual content
        return "Hello World";
    }
}</programlisting></para>
  </section>

  <section>
    <title>JAX-RS Applications</title>

    <para>A JAX-RS application is an application model abstraction that allows
    the developer to specify the list of resources and singleton classes that
    will be exposed by the REST container.</para>

    <para><programlisting>// Identifies the application path that serves as the base URI for all resource URIs provided by Path
@ApplicationPath("/application")
public class MyApplicaton extends Application {

    // Returns the list of resources that will be managed by the container
    public Set&lt;Class&lt;?&gt;&gt; getClasses() {
        Set&lt;Class&lt;?&gt;&gt; s = new HashSet&lt;Class&lt;?&gt;&gt;();
        s.add(HelloWorldResource.class);
        return s;
    }
}</programlisting></para>
  </section>

  <section>
    <title>JAX-RS Resources</title>

    <para>Resources are the main concept manipulated all along JAX-RS.</para>

    <section>
      <title>Using Resources</title>

      <para>Root resource classes are POJOs (Plain Old Java Objects) that are
      annotated with <classname>@Path</classname>, have at least one method
      annotated with <classname>@Path</classname> or a resource method
      designator annotation such as <classname>@GET</classname>,
      <classname>@PUT</classname>, <classname>@POST</classname>, or
      <classname>@DELETE</classname>. Resource methods are methods of a
      resource class annotated with a resource method designator.</para>

      <para><classname>HelloWorldResource</classname> is a root
      resource:</para>

      <para><programlisting>@Path("/helloworld")
public class HelloWorldResource {

    // Resource method
    @GET 
    public String getClichedMessage() {
        return "Hello World";
    }
}</programlisting></para>

      <section>
        <title>Sub Resources</title>

        <para>Root resource methods can return types that are also resources
        (annotated with <classname>@Path</classname>), that allows application
        decomposition.</para>

        <para><classname>HelloResource</classname>:</para>

        <para><programlisting>@Path("/hello")
public class HelloResource {

    // Resource method
    @GET 
    public WorldResource getClichedMessage() {
        return new WorldResource();
    }
}</programlisting>And it's sub-resource
        <classname>WorldResource</classname>:</para>

        <para><programlisting>@Path("/world")
public class WorldResource {

    @GET 
    public String getClichedMessage() {
        return "Hello World";
    }
}</programlisting></para>
      </section>
    </section>

    <section>
      <title>Using Parameters</title>

      <para></para>

      <section>
        <title>@PathParam</title>

        <para><classname>@Path</classname> declares an <emphasis>URI path
        template</emphasis>: it can contains variable definition. This
        variable can then be accessed as a resource method parameter:</para>

        <para><programlisting>@GET 
@Path("/hello/{username}")
public String hello(@PathParam("username") String username) {
    return "Hello " + username;
}</programlisting>A callable URI:</para>

        <para><programlisting>/hello/Guillaume</programlisting></para>
      </section>

      <section>
        <title>@QueryParam</title>

        <para>The HTTP query parameters (ex: <literal>?param=value</literal>)
        are also accessible as mapped method parameter:</para>

        <para><programlisting>@GET 
public String hello(@QueryParam("username") String username) {
    return "Hello " + username;
}</programlisting>A callable URI:</para>

        <para><programlisting>/hello?username=Guillaume</programlisting></para>
      </section>
    </section>

    <section>
      <title>Using Mime-Types</title>

      <para>Resources can be configured to accept and produces specific input
      (respectively output) types.</para>

      <para></para>
    </section>

    <section>
      <title>@Consumes</title>

      <para>The <classname>@Consumes</classname> annotation declares the
      expected MIME type that will be accepted by a resource.</para>

      <para>Only HTTP requests with the right <literal>Accept</literal> header
      will be dispatched to the resource method:</para>

      <para><programlisting>@POST
@Consumes("text/plain")
public void postClichedMessage(String message) {
    // ...
}</programlisting></para>
    </section>

    <section>
      <title>@Produces</title>

      <para>The <classname>@Produces</classname> annotation declares the MIME
      type that will be returned by this resource method:<programlisting>@GET
@Produces({"application/xml", "application/json"})
public String doGetAsXmlOrJson() {
    ...
}</programlisting></para>
    </section>
  </section>

  <section>
    <title>Activation in JOnAS</title>

    <para>In order to activate <acronym>JAX-RS</acronym> on JOnAS, the 'jaxrs'
    service must be declared in the
    <filename>$JONAS_BASE/conf/jonas.properties</filename> in the
    <literal>jonas.services</literal> property.</para>

    <para><programlisting>jonas.services    registry,jmx,... ,jaxrs
</programlisting>JOnAS is using Jersey (the reference implementation) as
    default JAX-RS provider.</para>

    <para><warning>
        <para>The JAX-RS support in JOnAS is currently limited to Web
        Applications</para>
      </warning><note>
        <para>JAX-RS Supports needs a Servlet 3.0 container: JOnAS
        '<literal>web</literal>' service in use must be Tomcat7 (at time of
        writing):</para>

        <para><programlisting>#
###################### JOnAS Web container service configuration
#
#  Set the name of the implementation class of the web container service.
jonas.service.web.class    org.ow2.jonas.web.tomcat7.Tomcat7Service
</programlisting></para>
      </note></para>
  </section>

  <section>
    <title>Resources</title>

    <para><itemizedlist>
        <listitem>
          <para><link xlink:href="http://jcp.org/en/jsr/detail?id=311">JAX-RS
          Specification</link></para>
        </listitem>

        <listitem>
          <para>Representational State Transfer (<link
          xlink:href="http://en.wikipedia.org/wiki/Representational_State_Transfer">REST</link>)</para>
        </listitem>

        <listitem>
          <para><link xlink:href="http://jersey.java.net">Oracle Jersey</link>
          (Reference Implementation) + <link
          xlink:href="http://jersey.java.net/nonav/documentation/latest/index.html">Documentation</link></para>
        </listitem>

        <listitem>
          <para><link xlink:href="http://cxf.apache.org">Apache CXF</link>
          (ASL2 Licensed Implementation) + <link
          xlink:href="http://cxf.apache.org/docs/jax-rs.html">Documentation</link></para>
        </listitem>
      </itemizedlist></para>
  </section>
</chapter>
