RESTEasy JAX-RS RESTFul Web Services for Java 2.0.1.GA iii Preface ............................................................................................................................ vii 1. Overview ...................................................................................................................... 1 2. License ........................................................................................................................ 3 3. Installation/Configuration ............................................................................................ 5 3.1. Standalone Resteasy .......................................................................................... 5 3.2. Configuration Switches ........................................................................................ 6 3.3. javax.ws.rs.core.Application ................................................................................. 8 3.4. RESTEasy as a ServletContextListener ............................................................... 9 3.5. RESTEasy as a servlet Filter ............................................................................. 10 3.6. Install/Config in JBoss 6-M4 and Higher ............................................................. 11 3.7. RESTEasyLogging ............................................................................................ 11 4. Using @Path and @GET, @POST, etc. ...................................................................... 13 4.1. @Path and regular expression mappings ........................................................... 14 5. @PathParam .............................................................................................................. 17 5.1. Advanced @PathParam and Regular Expressions .............................................. 18 5.2. @PathParam and PathSegment ........................................................................ 18 6. @QueryParam ............................................................................................................ 21 7. @HeaderParam .......................................................................................................... 23 8. Linking resources ...................................................................................................... 25 8.1. Link Headers .................................................................................................... 25 8.2. Atom links in the resource representations ......................................................... 25 8.2.1. Configuration .......................................................................................... 25 8.2.2. Your first links injected ........................................................................... 25 8.2.3. Customising how the Atom links are serialised ......................................... 28 8.2.4. Specifying which JAX-RS methods are tied to which resources .................. 28 8.2.5. Specifying path parameter values for URI templates ................................. 29 8.2.6. Securing entities .................................................................................... 32 8.2.7. Extending the UEL context ..................................................................... 33 8.2.8. Resource facades .................................................................................. 35 9. @MatrixParam ............................................................................................................ 39 10. @CookieParam ........................................................................................................ 41 11. @FormParam ........................................................................................................... 43 12. @Form ..................................................................................................................... 45 13. @DefaultValue .......................................................................................................... 47 14. @Encoded and encoding ......................................................................................... 49 15. @Context ................................................................................................................. 51 16. JAX-RS Resource Locators and Sub Resources ..................................................... 53 17. JAX-RS Content Negotiation .................................................................................... 57 17.1. URL-based negotiation .................................................................................... 59 18. Content Marshalling/Providers ................................................................................. 61 18.1. Default Providers and default JAX-RS Content Marshalling ................................ 61 18.2. Content Marshalling with @Provider classes ..................................................... 61 18.3. Providers Utility Class ..................................................................................... 61 19. JAXB providers ........................................................................................................ 65 RESTEasy JAX-RS iv 19.1. JAXB Decorators ............................................................................................ 66 19.2. Pluggable JAXBContext's with ContextResolvers .............................................. 67 19.3. JAXB + XML provider ...................................................................................... 68 19.3.1. @XmlHeader and @Stylesheet ............................................................. 68 19.4. JAXB + JSON provider .................................................................................... 70 19.5. JAXB + FastinfoSet provider ............................................................................ 75 19.6. Arrays and Collections of JAXB Objects ........................................................... 76 19.6.1. JSON and JAXB Collections/arrays ....................................................... 79 19.7. Maps of JAXB Objects .................................................................................... 80 19.7.1. JSON and JAXB maps ......................................................................... 82 19.7.2. Possible Problems with Jettison Provider ............................................... 84 19.8. Interfaces, Abstract Classes, and JAXB ............................................................ 84 20. Resteasy Atom Support ........................................................................................... 85 20.1. Resteasy Atom API and Provider ..................................................................... 85 20.2. Using JAXB with the Atom Provider ................................................................. 86 21. Atom support through Apache Abdera .................................................................... 89 21.1. Abdera and Maven .......................................................................................... 89 21.2. Using the Abdera Provider ............................................................................... 89 22. JSON Support via Jackson ...................................................................................... 95 22.1. Possible Conflict With JAXB Provider ............................................................... 97 23. Multipart Providers .................................................................................................. 99 23.1. Input with multipart/mixed ................................................................................ 99 23.2. java.util.List with multipart data ....................................................................... 101 23.3. Input with multipart/form-data ......................................................................... 101 23.4. java.util.Map with multipart/form-data .............................................................. 102 23.5. Input with multipart/related ............................................................................. 102 23.6. Output with multipart ..................................................................................... 103 23.7. Multipart Output with java.util.List ................................................................... 104 23.8. Output with multipart/form-data ...................................................................... 105 23.9. Multipart FormData Output with java.util.Map .................................................. 106 23.10. Output with multipart/related ......................................................................... 106 23.11. @MultipartForm and POJOs ........................................................................ 108 23.12. XML-binary Optimized Packaging (Xop) ........................................................ 109 23.13. Note about multipart parsing and working with other frameworks ..................... 111 23.14. Overwriting the default fallback content type for multipart messages ................ 112 24. YAML Provider ....................................................................................................... 113 25. String marshalling for String based @*Param ....................................................... 115 25.1. StringConverter ............................................................................................. 115 25.2. StringParamUnmarshaller .............................................................................. 118 26. Responses using javax.ws.rs.core.Response ........................................................ 121 27. Exception Handling ................................................................................................ 123 27.1. Exception Mappers ........................................................................................ 123 27.2. Resteasy Built-in Internally-Thrown Exceptions ................................................ 124 27.3. Overriding Resteasy Builtin Exceptions ........................................................... 126 v 28. Configuring Individual JAX-RS Resource Beans ................................................... 127 29. GZIP Compression/Decompression ....................................................................... 129 30. Resteasy Caching Features ................................................................................... 131 30.1. @Cache and @NoCache Annotations ............................................................ 131 30.2. Client "Browser" Cache ................................................................................. 132 30.3. Local Server-Side Response Cache ............................................................... 133 31. Interceptors ............................................................................................................ 137 31.1. MessageBodyReader/Writer Interceptors ........................................................ 137 31.2. PreProcessInterceptor ................................................................................... 140 31.3. PostProcessInterceptors ................................................................................ 140 31.4. ClientExecutionInterceptors ............................................................................ 141 31.5. Binding Interceptors ....................................................................................... 141 31.6. Registering Interceptors ................................................................................. 142 31.7. Interceptor Ordering and Precedence ............................................................. 143 31.7.1. Custom Precedence ........................................................................... 144 32. Asynchronous HTTP Request Processing ............................................................. 147 32.1. Tomcat 6 and JBoss 4.2.3 Support ................................................................ 149 32.2. Servlet 3.0 Support ....................................................................................... 149 32.3. JBossWeb, JBoss AS 5.0.x Support ............................................................... 150 33. Asynchronous Job Service .................................................................................... 151 33.1. Using Async Jobs ......................................................................................... 151 33.2. Oneway: Fire and Forget ............................................................................... 152 33.3. Setup and Configuration ................................................................................ 152 34. Embedded Container ............................................................................................. 155 35. Server-side Mock Framework ................................................................................. 157 36. Securing JAX-RS and RESTeasy ........................................................................... 159 37. Authentication ........................................................................................................ 163 37.1. OAuth core 1.0a ............................................................................................ 163 37.1.1. Authenticating with OAuth ................................................................... 163 37.1.2. Accessing protected resources ............................................................ 164 37.1.3. Implementing an OAuthProvider .......................................................... 165 38. EJB Integration ...................................................................................................... 167 39. Spring Integration .................................................................................................. 169 40. CDI Integration ....................................................................................................... 173 40.1. Using CDI beans as JAX-RS components ...................................................... 173 40.2. Default scopes .............................................................................................. 173 40.3. Configuration within JBoss 6 M4 and Higher ................................................... 174 40.4. Configuration with different distributions .......................................................... 174 41. Seam Integration .................................................................................................... 175 42. Guice 2.0 Integration .............................................................................................. 177 42.1. Configuring Stage ......................................................................................... 178 43. Client Framework ................................................................................................... 181 43.1. Abstract Responses ...................................................................................... 182 43.2. Sharing an interface between client and server ............................................... 185 RESTEasy JAX-RS vi 43.3. Client Error Handling ..................................................................................... 186 43.4. Manual ClientRequest API ............................................................................. 188 43.5. Spring integration on client side ..................................................................... 188 44. AJAX Client ............................................................................................................ 189 44.1. Generated JavaScript API .............................................................................. 189 44.1.1. JavaScript API servlet ......................................................................... 189 44.1.2. JavaScript API usage ......................................................................... 190 44.1.3. MIME types and unmarshalling. ........................................................... 192 44.1.4. MIME types and marshalling. .............................................................. 193 44.2. Using the JavaScript API to build AJAX queries .............................................. 195 44.2.1. The REST object ................................................................................ 195 44.2.2. The REST.Request class .................................................................... 195 45. Maven and RESTEasy ............................................................................................ 197 46. JBoss AS 5.x Integration ....................................................................................... 201 47. JBoss AS 6 Integration .......................................................................................... 203 48. Migration from older versions ................................................................................ 205 48.1. Migrating from 1.2.x to 2.0 ............................................................................. 205 48.2. Migrating from 1.2.GA to 1.2.1.GA ................................................................. 205 48.3. Migrating from 1.1 to 1.2 ............................................................................... 205 49. Books You Can Read ............................................................................................. 207 vii Preface Commercial development support, production support and training for RESTEasy JAX-RS is available through JBoss, a division of Red Hat Inc. (see http://www.jboss.com/). In some of the example listings, what is meant to be displayed on one line does not fit inside the available page width. These lines have been broken up. A '\' at the end of a line means that a break has been introduced to fit in the page, with the following lines indented. So: Let's pretend to have an extremely \ long line that \ does not fit This one is short Is really: Let's pretend to have an extremely long line that does not fit This one is short viii Chapter 1. 1 Overview JAX-RS, JSR-311, is a new JCP specification that provides a Java API for RESTful Web Services over the HTTP protocol. Resteasy is an portable implementation of this specification which can run in any Servlet container. Tighter integration with JBoss Application Server is also available to make the user experience nicer in that environment. While JAX-RS is only a server-side specification, Resteasy has innovated to bring JAX-RS to the client through the RESTEasy JAX-RS Client Framework. This client-side framework allows you to map outgoing HTTP requests to remote servers using JAX-RS annotations and interface proxies. • JAX-RS implementation • Portable to any app-server/Tomcat that runs on JDK 5 or higher • Embeddedable server implementation for junit testing • EJB and Spring integration • Client framework to make writing HTTP clients easy (JAX-RS only define server bindings) 2 Chapter 2. 3 License RESTEasy is distributed under the ASL 2.0 license. It does not distribute any thirdparty libraries that are GPL. It does ship thirdparty libraries licensed under Apache ASL 2.0 and LGPL. 4 Chapter 3. 5 Installation/Configuration RESTEasy is installed and configured in different ways depending on which environment you are running in. If you are running in JBoss AS 6-M4 (milestone 4) or higher, resteasy is already bundled and integrated completely so there is very little you have to do. If you are running in a different distribution, there is some manual installation and configuration you will have to do. 3.1. Standalone Resteasy If you are using resteasy outside of JBoss AS 6, you will need to do a few manual steps to install and configure resteasy. RESTeasy is deployed as a WAR archive and thus depends on a Servlet container. We strongly suggest that you use Maven to build your WAR files as RESTEasy is split into a bunch of different modules. You can see an example Maven project in one of the examples in the examples/ directory Also, when you download RESTeasy and unzip it you will see a lib/ directory that contains the libraries needed by resteasy. Copy these into your /WEB-INF/lib directory. Place your JAX-RS annotated class resources and providers within one or more jars within /WEB-INF/lib or your raw class files within /WEB-INF/classes. RESTeasy is implemented as a Servlet and deployed within a WAR file. If you open up the WEB- INF/web.xml in one of the example projects of your RESTeasy download you will see this: <web-app> <display-name>Archetype Created Web Application</display-name> <servlet> <servlet-name>Resteasy</servlet-name> <servlet-class> org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher </servlet-class> <init-param> <param-name>javax.ws.rs.Application</param-name> <param-value>com.restfully.shop.services.ShoppingApplication</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>Resteasy</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> Chapter 3. Installation/Confi... 6 </web-app> The Resteasy servlet is responsible for initializing some basic components of RESTeasy. 3.2. Configuration Switches Resteasy receives configuration options from <context-param> elements. Table 3.1. Option Name Default Value Description resteasy.servlet.mapping.prefix no default If the url-pattern for the Resteasy servlet-mapping is not /* resteasy.scan false Automatically scan WEB-INF/ lib jars and WEB-INF/classes directory for both @Provider and JAX-RS resource classes (@Path, @GET, @POST etc..) and register them resteasy.scan.providers false Scan for @Provider classes and register them resteasy.scan.resources false Scan for JAX-RS resource classes resteasy.providers no default A comma delimited list of fully qualified @Provider class names you want to register resteasy.use.builtin.providers true Whether or not to register default, built-in @Provider classes. (Only available in 1.0- beta-5 and later) resteasy.resources no default A comma delimited list of fully qualified JAX-RS resource class names you want to register resteasy.jndi.resources no default A comma delimited list of JNDI names which reference objects you want to register as JAX-RS resources javax.ws.rs.Application no default Configuration Switches 7 Option Name Default Value Description Fully qualified name of Application class to bootstrap in a spec portable way resteasy.media.type.mappings no default Replaces the need for an Accept header by mapping file name extensions (like .xml or .txt) to a media type. Used when the client is unable to use a Accept header to choose a representation (i.e. a browser). See JAX-RS Content Negotiation chapter for more details. resteasy.language.mappings no default Replaces the need for an Accept-Language header by mapping file name extensions (like .en or .fr) to a language. Used when the client is unable to use a Accept-Language header to choose a language (i.e. a browser). See JAX-RS Content Negotiation chapter for more details The resteasy.servlet.mapping.prefix <context param> variable must be set if your servlet-mapping for the Resteasy servlet has a url-pattern other than /*. For example, if the url-pattern is <servlet-mapping> <servlet-name>Resteasy</servlet-name> <url-pattern>/restful-services/*</url-pattern> </servlet-mapping> Then the value of resteasy-servlet.mapping.prefix must be: <context-param> <param-name>resteasy.servlet.mapping.prefix</param-name>