resteasy手册

RESTEasy JAX-RS

RESTFul Web Services for Java

3.0.16.Final

iii

Preface ............................................................................................................................. ix

1. Overview ...................................................................................................................... 1

2. License ........................................................................................................................ 3

3. Installation/Configuration ............................................................................................ 5

3.1. Upgrading Resteasy Within JBoss AS 7 ............................................................... 5

3.7. Configuration Switches ........................................................................................ 9

3.8. javax.ws.rs.core.Application ............................................................................... 11

3.9. RESTEasy as a ServletContextListener .............................................................. 13

3.10. RESTEasy as a servlet Filter ........................................................................... 14

3.11. RESTEasyLogging .......................................................................................... 14

4. Using @Path and @GET, @POST, etc. ...................................................................... 17

4.1. @Path and regular expression mappings ........................................................... 18

5. @PathParam .............................................................................................................. 21

5.1. Advanced @PathParam and Regular Expressions .............................................. 22

5.2. @PathParam and PathSegment ........................................................................ 22

8.2.2. Your first links injected ........................................................................... 29

8.2.3. Customising how the Atom links are serialised ......................................... 32

8.2.4. Specifying which JAX-RS methods are tied to which resources .................. 32

8.2.5. Specifying path parameter values for URI templates ................................. 33

8.2.6. Securing entities .................................................................................... 36

8.2.7. Extending the UEL context ..................................................................... 36

8.2.8. Resource facades .................................................................................. 38

9. @MatrixParam ............................................................................................................ 41

10. @CookieParam ........................................................................................................ 43

11. @FormParam ........................................................................................................... 45

17.1. URL-based negotiation .................................................................................... 62

RESTEasy JAX-RS

iv

17.2. Query String Parameter-based negotiation ........................................................ 64

18. Content Marshalling/Providers ................................................................................. 65

18.1. Default Providers and default JAX-RS Content Marshalling ................................ 65

18.2. Content Marshalling with @Provider classes ..................................................... 65

18.3. Providers Utility Class ..................................................................................... 66

19.4. JAXB + JSON provider .................................................................................... 76

19.5. JAXB + FastinfoSet provider ............................................................................ 80

19.6. Arrays and Collections of JAXB Objects ........................................................... 81

19.6.1. JSON and JAXB Collections/arrays ....................................................... 83

19.7. Maps of JAXB Objects .................................................................................... 84

19.7.1. JSON and JAXB maps ......................................................................... 87

19.7.2. Possible Problems with Jettison Provider ............................................... 87

19.8. Interfaces, Abstract Classes, and JAXB ............................................................ 88

19.9. Configurating JAXB Marshalling ....................................................................... 88

20. Resteasy Atom Support ........................................................................................... 91

21.4. Using Jackson 2.2.x Inside of JBoss AS7 ......................................................... 96

21.5. Additional Resteasy Specifics .......................................................................... 96

21.6. Possible Conflict With JAXB Provider ............................................................... 97

21.7. JSONP Support .............................................................................................. 98

21.8. Jackson JSON Decorator ................................................................................ 99

22. JSON Support via Java EE 7 JSON-P API .............................................................. 101

23. Multipart Providers ................................................................................................. 103

23.1. Input with multipart/mixed .............................................................................. 103

23.2. java.util.List with multipart data ....................................................................... 105

23.3. Input with multipart/form-data ......................................................................... 105

23.10. Output with multipart/related ......................................................................... 110

v

23.11. @MultipartForm and POJOs ........................................................................ 111

23.12. XML-binary Optimized Packaging (Xop) ........................................................ 113

23.13. Note about multipart parsing and working with other frameworks ..................... 115

23.14. Overwriting the default fallback content type for multipart messages ................ 115

23.15. Overwriting the content type for multipart messages ...................................... 116

27.2. Resteasy Built-in Internally-Thrown Exceptions ................................................ 126

27.3. Overriding Resteasy Builtin Exceptions ........................................................... 127

28. Configuring Individual JAX-RS Resource Beans ................................................... 129

29. GZIP Compression/Decompression ....................................................................... 131

30. CORS ..................................................................................................................... 133

31. Content-Range Support ......................................................................................... 135

32. Resteasy Caching Features ................................................................................... 137

32.1. @Cache and @NoCache Annotations ............................................................ 137

32.2. Client "Browser" Cache ................................................................................. 138

32.3. Local Server-Side Response Cache ............................................................... 139

34. Asynchronous HTTP Request Processing ............................................................. 145

35. Asynchronous Job Service .................................................................................... 147

35.1. Using Async Jobs ......................................................................................... 147

35.2. Oneway: Fire and Forget ............................................................................... 148

35.3. Setup and Configuration ................................................................................ 148

36. Embedded Containers ............................................................................................ 151

36.1. Undertow ...................................................................................................... 151

36.2. Sun JDK HTTP Server .................................................................................. 153

36.3. TJWS Embeddable Servlet Container ............................................................. 154

36.4. Netty ............................................................................................................ 155

39.3.1. Setting up your Security Domain ......................................................... 164