Author: christian.bauer(a)jboss.com Date: 2009-03-16 09:36:39 -0400 (Mon, 16 Mar 2009) New Revision: 10172 Modified: trunk/doc/Seam_Reference_Guide/en-US/Webservices.xml trunk/src/resteasy/org/jboss/seam/resteasy/ResteasyDispatcher.java Log: JBSEAM-3265, documented RESTEasy exception handling Modified: trunk/doc/Seam_Reference_Guide/en-US/Webservices.xml =================================================================== --- trunk/doc/Seam_Reference_Guide/en-US/Webservices.xml 2009-03-16 13:16:36 UTC (rev 10171) +++ trunk/doc/Seam_Reference_Guide/en-US/Webservices.xml 2009-03-16 13:36:39 UTC (rev 10172) @@ -279,7 +279,7 @@ @GET @Path("/{customerId}") - @ProduceMime("text/plain") + @Produces("text/plain") public String getCustomer(@PathParam("customerId") int id) { return ...; } @@ -403,7 +403,7 @@ @GET @Path("/{customerId}") - @ProduceMime("text/plain") + @Produces("text/plain") public String getCustomer(@PathParam("customerId") int id) { return customerDAO.find(id).getName(); } @@ -436,6 +436,54 @@ </sect2> + <sect2> + <title>Mapping exceptions to HTTP response status codes</title> + + <para> + Section 3.3.4 of the JAX-RS specification defines how checked or unchecked exceptions are handled by the + JAX RS implementation. In addition to using an exception mapping provider as defined by JAX-RS, the integration + of RESTEasy with Seam allows you to map exceptions to HTTP response codes within Seam's <literal>pages.xml</literal> + facility. If you are already using <literal>pages.xml</literal> declarations, this is easier to maintain than + potentially many JAX RS exception mapper classes. + </para> + + <para> + For example, to convert the unchecked <literal>UnsupportedOperationException</literal> thrown by your resource + methods to a <literal>501 Not Implemented</literal> HTTP status response, add the following to your + <literal>pages.xml</literal> descriptor: + </para> + + <programlisting role="JAVA"><![CDATA[<exception class="java.lang.UnsupportedOperationException"> + <http-error error-code="501"> + <message>The request operation is not supported</message> + </http-error> +</exception>]]></programlisting> + + <para> + Custom or checked exceptions are handled the same: + </para> + + <programlisting role="JAVA"><![CDATA[<exception class="my.CustomException"> + <http-error error-code="503"> + <message>The service is currently not available</message> + </http-error> +</exception>]]></programlisting> + + <para> + You do not have to send an HTTP error to the client if an exception occurs. Seam allows you to map the + exception as a redirect to a view of your Seam application. As this feature is typically used for human + clients (web browsers) and not for REST API remote clients, you should pay extra attention to conflicting + exception mappings in <literal>pages.xml</literal>. + </para> + + <para> + Note that the HTTP response still passes through the servlet container, so an additional mapping might apply + if you have <literal>&lt;error-page&gt;</literal> mappings in your <literal>web.xml</literal> configuration. + The HTTP status code would then be mapped to a rendered HTML error page with status <literal>200 OK</literal>! + </para> + + </sect2> + </sect1> </chapter> Modified: trunk/src/resteasy/org/jboss/seam/resteasy/ResteasyDispatcher.java =================================================================== --- trunk/src/resteasy/org/jboss/seam/resteasy/ResteasyDispatcher.java 2009-03-16 13:16:36 UTC (rev 10171) +++ trunk/src/resteasy/org/jboss/seam/resteasy/ResteasyDispatcher.java 2009-03-16 13:36:39 UTC (rev 10172) @@ -25,7 +25,7 @@ /** * An extended version of the RESTEasy dispatcher, configured on Seam application - * startup with a custom ApplicationConfig instance. Registers custom resource + * startup with a custom JAX RS <tt>Application</tt> instance. Registers custom resource * and provider lifecycle handlers. * * @author Christian Bauer