From seam-commits at lists.jboss.org Mon Jul 28 04:00:05 2008 Content-Type: multipart/mixed; boundary="===============8650488847627228900==" MIME-Version: 1.0 From: seam-commits at lists.jboss.org To: seam-commits at lists.jboss.org Subject: [seam-commits] Seam SVN: r8505 - in trunk: src/resteasy/org/jboss/seam/resteasy and 1 other directory. Date: Mon, 28 Jul 2008 04:00:03 -0400 Message-ID: --===============8650488847627228900== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: christian.bauer(a)jboss.com Date: 2008-07-28 04:00:02 -0400 (Mon, 28 Jul 2008) New Revision: 8505 Modified: trunk/doc/Seam_Reference_Guide/en-US/Webservices.xml trunk/src/resteasy/org/jboss/seam/resteasy/reasteasy-2.1.xsd Log: Completed docs of RESTEasy integration Modified: trunk/doc/Seam_Reference_Guide/en-US/Webservices.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/doc/Seam_Reference_Guide/en-US/Webservices.xml 2008-07-28 04:58:5= 8 UTC (rev 8504) +++ trunk/doc/Seam_Reference_Guide/en-US/Webservices.xml 2008-07-28 08:00:0= 2 UTC (rev 8505) @@ -202,66 +202,240 @@ RESTful HTTP webservices with RESTEasy = - Seam integrates the RESTEasy implementation of the JAX-RS specific= ation (JSR 311). You can decided how - "deep" the integration into your Seam application is going to be: = >From simple integration of configuration - and bootstrap, serving the requests with the built-in Seam resourc= e servlet, writing resources as - Seam components, and integration with conversations and the Seam C= RUD Application Framework. + Seam integrates the RESTEasy implementation of the JAX-RS specific= ation (JSR 311). You can decide how + "deep" the integration into your Seam application is going to be: = + + + + Seamless integration of RESTEasy bootstrap and configuratio= n, automatic detection of resources + and providers. + + + + + Serving HTTP/REST requests with the SeamResourceServlet, no= external servlet or configuration in + web.xml required. + + + + + Writing resources as Seam components, with full Seam lifecy= cle management and interception (bijection). + + + + - RESTEasy bootstrap and request handling + RESTEasy configuration and request serving = - First, get the RESTEasy libraries and the jaxrs-api.j= ar, deploy it with the - other libraries of your application. Also deploy the integrati= on library, jboss-seam-resteasy.jar + First, get the RESTEasy libraries and the jaxrs-api.j= ar, deploy them with the + other libraries of your application. Also deploy the integrati= on library, + jboss-seam-resteasy.jar = On startup, all classes annotated @javax.ws.rs.Path will be discovered automatically - and registered as HTTP resources. Seam will serve any HTTP req= uest automatically under the URL basepath - you mapped the SeamResourceServlet at in web.xml. Most of the time and if you - follow this documentation, this would be /seam/resour= ce. - The hardcoded full path of your RESTful resources is therefore= /seam/resource/rest. + and registered as HTTP resources. Seam automatically accepts a= nd serves HTTP requests with its built-in + SeamResourceServlet. The URI of a resource = is build as follows: = + + + + The URI starts with the pattern mapped in web.x= ml for the + SeamResourceServlet, e.g /se= am/resource if you follow + the common examples. Change this setting to expose your = RESTful resources under a different base. + Note that this is a global change and other Seam resourc= es (e.g. s:graphicImage) + are then also served under that base path. + + + + + The RESTEasy integration for Seam then appends a configu= rable string to the base path, by default + this is /rest. Hence, the full base p= ath of your resources would e.g. be + /seam/resource/rest. We recommend tha= t you change this string in your application, + you could for example add a version number to prepare fo= r a future REST API upgrade of your services + (old clients would keep the old URI base): /sea= m/resource/restv1. + + + + + Finally, the actual resource is available under the defi= ned @Path, e.g. a resource + mapped with @Path("/customer") would = be available under + /seam/resource/rest/customer. + + + + - The following resource would serve a representation under - http://your.hostname/seam/resource/reset/item/123: + As an example, the following resource definition would return = a plaintext representation for any + GET requests using the URI http://your.hostname/seam/= resource/rest/customer/123: = - = - TODO: This is not true, today you need @Path("/seam/resource/r= est/item") on the resource class, we need - to implement some base-path mapping there. + No additional configuration is required, you do not have to ed= it web.xml or any + other setting if these defauls are acceptable. However, you ca= n configure RESTEasy in your Seam application. + First import the resteasy namespace into yo= ur XML configuration file header: = + ]]> + - You can configure the /seam/resource part b= y specifying a new mapping in web.xml - for the SeamResourceServlet. Note that this also chan= ges the URI path for all other resources - you want to serve with this servlet! You can not change the /rest segement of the path, - unless you subclass and override the ResteasyResource= Adapter.getResourcePath() method. + You can then change the /rest prefix as men= tioned earlier: = + ]]> + - TODO: TBC... + The full base path to your resources is now /seam/res= ource/restv1/{resource} - note + that your @Path definitions and mappings do= NOT change. This is an application-wide + switch usually used for versioning of the HTTP API. = + + You can disable stripping of the base path if you'd like to ma= p the full path in your resources: + + + ]]> + + + The path of a resource is now mapped with e.g. + @Path("/seam/resource/rest/customer"). We d= o not recommend disabling this feature, + as your resource class mappings are then bound to a particular= deployment scenario. + + + + Seam will scan your classpath for any deployed @javax= .ws.rs.Path resources and any + @javax.ws.rs.ext.Provider classes. You can = disable scanning and configure these + classes manually: + + = + + + + org.foo.MyCustomerResource + org.foo.MyOrderResource + + + + org.foo.MyFancyProvider + + + ]]> + + + The use-built-in-providers switch enables (= default) or disables the RESTEasy built-in + providers. We recommend you leave them enabled, as they provid= e plaintext, JSON, and JAXB marshalling + out of the box. + + + + Finally, you can configure media type and language URI extensi= ons: + + + + + + txttext/plain + + + + deutschde-DE + + +]]> + + + This definition would map the URI suffix of .txt.deut= sch to + additional Accept and Accept-Langu= age header values + text/plain and de-DE. + + = - + + Resources and providers as Seam components + + + Any resource and provider instances are managed by RESTEasy by= default. That means a resource class + will be instantiated by RESTEasy and serve a single request, a= fter which it will be destroyed. This is + the default JAX-RS lifecycle. Providers are instantiated once = for the whole application and are + effectively singletons and supposed to be stateless. + + + + You can write resources and providers as Seam components and b= enefit from the richer lifecycle management + of Seam, and interception for bijection, security, and so on. = Simply make your resource class a + Seam component: + + + + + + An instance of customerResource is now hand= led by Seam when a request hits the + server. This is a Seam JavaBean component that is EVE= NT-scoped, hence no different + than the default JAX-RS lifecycle. However, you get full Seam = injection support and all other Seam + components and contexts are available to you. Currently also s= upported are SESSION, + APPLICATION, and STATELESS resource components. Remember that any + HTTP request has to transmit a valid session identifier (cooki= e, URI path parameter) for correct handling + of the server-side session context. + + + + Conversation-scoped resource components and mapping of convers= ations is currently not supported but will + be available soon. + + + + Provider classes can also be Seam components, they must be APPLICATION-scoped + or STATELESS. + + + + Resources and providers can be EJBs or JavaBeans, like any oth= er Seam component. + + + + = Modified: trunk/src/resteasy/org/jboss/seam/resteasy/reasteasy-2.1.xsd =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/src/resteasy/org/jboss/seam/resteasy/reasteasy-2.1.xsd 2008-07-28= 04:58:58 UTC (rev 8504) +++ trunk/src/resteasy/org/jboss/seam/resteasy/reasteasy-2.1.xsd 2008-07-28= 08:00:02 UTC (rev 8505) @@ -29,6 +29,22 @@ + + + + Maps media type URI extensions to Accept header, s= ee RESTEasy documentation and JAX-RS (JSR 311). + + + + + + + Maps language URI extension to Accept header, see = RESTEasy documentation and JAX-RS (JSR 311). + + + --===============8650488847627228900==--