[seam-commits] Seam SVN: r11803 - branches/community/Seam_2_2/doc/Seam_Reference_Guide/en-US.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Wed Dec 9 05:49:22 EST 2009
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")
+ at 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&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")
+ at 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>
More information about the seam-commits
mailing list