[seam-commits] Seam SVN: r11803 - branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US.

Author: jharting Date: 2009-12-09 05:49:22 -0500 (Wed, 09 Dec 2009) New Revision: 11803 Modified: branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Author_Group.xml branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Webservices.xml Log: Docs for ResourceHome and ResourceQuery. Modified: branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Author_Group.xml =================================================================== --- branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Author_Group.xml 2009-12-09 10:01:36 UTC (rev 11802) +++ branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Author_Group.xml 2009-12-09 10:49:22 UTC (rev 11803) @@ -71,6 +71,10 @@ <firstname>Marek</firstname> <surname>Novotny</surname> </author> + <author> + <firstname>Jozef</firstname> + <surname>Hartinger</surname> + </author> <othercredit> <firstname>James</firstname> <surname>Cobb</surname> Modified: branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Webservices.xml =================================================================== --- branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Webservices.xml 2009-12-09 10:01:36 UTC (rev 11802) +++ branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US/Webservices.xml 2009-12-09 10:49:22 UTC (rev 11803) @@ -603,6 +603,207 @@ </sect2> <sect2> + <title>Exposing entities via RESTful API</title> + + <para> + Seam makes it really easy to use RESTful approach for accessing application data. One of the improvements that + Seam introduces is an ability to expose parts of your relational-database for remote use via plain HTTP calls. + For this purpose, Seam-RESTEasy integration module provides two components: <literal>ResourceHome</literal> and + <literal>ResourceQuery</literal>, which benefit from the API provided by the Seam Application Framework (<xref linkend="framework"/>) + and bind it to the REST API. + </para> + + <sect3> + + <title>ResourceQuery</title> + + <para> + ResourceQuery allows querying capabilities to be exposed as a RESTful web service. By default, a simple + underlying Query component, which returns a list of instances of a given entity class, is created automatically. + Alternatively, the ResourceQuery component can be attached to an existing Query component in more sophisticated + cases. The following example demonstrates how easily ResourceQuery can be configured: + </para> + + <programlisting role="XML"><![CDATA[<resteasy:resource-query path="/user" name="userResourceQuery" +entity-class="com.example.User"/>]]></programlisting> + + <para> + With this single XML element, a ResourceQuery component is set up. The configuration is straightforward: + </para> + + <itemizedlist> + <listitem> + <para> + The component will return a list of <literal>com.example.User</literal> instances. + </para> + </listitem> + <listitem> + <para> + The component will listen on <literal>/user</literal> URI. + </para> + </listitem> + <listitem> + <para> + The component will by default marshall the result into XML or JSON (based on client's preference). + The set of supported mime types can be altered by using <literal>media-types</literal> attribute for example: + </para> + + </listitem> + </itemizedlist> + + <programlisting role="XML"><![CDATA[<resteasy:resource-query path="/user" name="userResourceQuery" +entity-class="com.example.User" media-types="application/fastinfoset"/>]]></programlisting> + + <para> + Alternatively, if you do not like configuring components using XML, you can set up the component by extension: + </para> + + <programlisting role="JAVA"><![CDATA[@Name("userResourceQuery") +@Path("user") +public class UserResourceQuery extends ResourceQuery<User> +{ +}]]></programlisting> + + <para> + Since queries are read-only operations, the resource only responds to GET requests. Furthermore, ResourceQuery allows clients + of a web service to manipulate the result of a query using the following path parameters: + </para> + + <informaltable> + <tgroup cols='3'> + <thead> + <row> + <entry>Parameter name</entry> + <entry>Example</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>start</entry> + <entry>/user?start=20</entry> + <entry>Returns a subset of a database query result starting with the 20th entry.</entry> + </row> + <row> + <entry>show</entry> + <entry>/user?show=10</entry> + <entry>Returns a subset of the database query result limited to 10 entries.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para> + For example, you can send an HTTP GET request to <literal>/user?start=30&amp;show=10</literal> to get a list of entries representing 10 rows starting with row 30. + </para> + + <note> + <para> + RESTEasy uses JAXB to marshall entities. Thus, in order to be able to transfer them over the wire, you need to annotate entity classes with <literal>@XMLRootElement</literal>. + </para> + </note> + + </sect3> + + <sect3> + + <title>ResourceHome</title> + + <para> + Just as ResourceQuery makes Query's API available for remote access, so does ResourceHome for the Home component. The following table describes + how the two APIs (HTTP and Home) are bound together. + </para> + + <table> + <tgroup cols='4'> + <thead> + <row> + <entry>HTTP method</entry> + <entry>Path</entry> + <entry>Function</entry> + <entry>ResourceHome method</entry> + </row> + </thead> + <tbody> + <row> + <entry>GET</entry> + <entry>{path}/{id}</entry> + <entry>Read</entry> + <entry>getResource()</entry> + </row> + <row> + <entry>POST</entry> + <entry>{path}</entry> + <entry>Create</entry> + <entry>postResource()</entry> + </row> + <row> + <entry>PUT</entry> + <entry>{path}/{id}</entry> + <entry>Update</entry> + <entry>putResource()</entry> + </row> + <row> + <entry>DELETE</entry> + <entry>{path}/{id}</entry> + <entry>Delete</entry> + <entry>deleteResource()</entry> + </row> + </tbody> + </tgroup> + </table> + + <itemizedlist> + <listitem> + <para> + You can GET, PUT, and DELETE a particular user instance by sending HTTP requests to /user/{userId} + </para> + </listitem> + <listitem> + <para> + Sending a POST request to <literal>/user</literal> creates a new user entity instance and persists it. Usually, you leave it + up to the persistence layer to provide the entity instance with an identifier and thus an URI. Therefore, the URI + is sent back to the client in the <literal>Location</literal> header of the HTTP response. + </para> + </listitem> + </itemizedlist> + + <para> + The configuration of ResourceHome is very similar to ResourceQuery except that you need to explicitly specify the underlying + Home component and a Java type of the entity identifier. + </para> + + <programlisting role="XML"><![CDATA[<resteasy:resource-home path="/user" name="userResourceHome" +entity-home="#{userHome}" entity-id-class="java.lang.Integer"/>]]></programlisting> + + <para>Again, you can write a subclass of ResourceHome instead of writting any XML code.</para> + + <programlisting role="JAVA"><![CDATA[@Name("userResourceHome") +@Path("user") +public class UserResourceHome extends ResourceHome<User, Integer> +{ + + @In + private EntityHome<User> userHome; + + @Override + public Home<?, User> getEntityHome() + { + return userHome; + } +}]]></programlisting> + + <para> + For more examples of how ResourceHome and ResourceQuery components can be used, take a look at the Seam Tasks sample application, which + demonstrates how Seam-RESTEasy integration can be used together with a jQuery client. In addition, you can find more code samples + in the Restbay example, which is used mainly for testing purposes. + </para> + + </sect3> + + </sect2> + + <sect2> <title>Testing resources and providers</title> <para>