RESTEasy JAX-RS
RESTFul Web
Services for Java
2.1.0.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
- 1
- 2
前往页