Jersey 1.8 User Guide Jersey 1.8 User Guide Table of Contents Preface ............................................................................................................................ ix 1. Getting Started ............................................................................................................... 1 1.1. Creating a root resource ........................................................................................ 2 1.2. Deploying the root resource ................................................................................... 3 1.3. Testing the root resource ....................................................................................... 3 1.4. Here's one Paul created earlier ................................................................................ 4 2. Overview of JAX-RS 1.1 ................................................................................................. 5 2.1. Root Resource Classes .......................................................................................... 5 2.1.1. @Path ...................................................................................................... 5 2.1.2. HTTP Methods .......................................................................................... 6 2.1.3. @Produces ................................................................................................ 7 2.1.4. @Consumes .............................................................................................. 9 2.2. Deploying a RESTful Web Service .......................................................................... 9 2.3. Extracting Request Parameters .............................................................................. 11 2.4. Representations and Java Types ............................................................................ 14 2.5. Building Responses ............................................................................................. 15 2.6. Sub-resources ..................................................................................................... 16 2.7. Building URIs .................................................................................................... 18 2.8. WebApplicationException and Mapping Exceptions to Responses ................................ 20 2.9. Conditional GETs and Returning 304 (Not Modified) Responses ................................. 21 2.10. Life-cycle of Root Resource Classes ..................................................................... 22 2.11. Security ........................................................................................................... 23 2.12. Rules of Injection .............................................................................................. 23 2.13. Use of @Context .............................................................................................. 24 2.14. Annotations Defined By JAX-RS ......................................................................... 25 3. Client API ................................................................................................................... 26 3.1. Introduction ....................................................................................................... 26 3.2. Uniform Interface Constraint ................................................................................ 26 3.3. Ease of use and reusing JAX-RS artifacts ................................................................ 27 3.4. Getting started with the Jersey client ...................................................................... 28 3.5. Overview of the API ........................................................................................... 28 3.5.1. Configuring a Client and WebResource ........................................................ 28 3.5.2. Building a request .................................................................................... 29 3.5.3. Receiving a response ................................................................................ 30 3.5.4. Creating new WebResources from a WebResource ......................................... 30 3.5.5. Java instances and types for representations ................................................... 31 3.6. Adding support for new representations .................................................................. 31 3.7. Using filters ....................................................................................................... 31 3.7.1. Supported filters ....................................................................................... 32 3.8. Testing services .................................................................................................. 33 3.9. Security with Http(s)URLConnection ..................................................................... 34 3.9.1. With Http(s)URLConnection ...................................................................... 34 3.9.2. With Apache HTTP client .......................................................................... 34 4. XML Support ............................................................................................................... 35 4.1. Low level XML support ...................................................................................... 35 4.2. Getting started with JAXB ................................................................................... 35 4.3. POJOs .............................................................................................................. 37 4.4. Using custom JAXBContext ................................................................................. 38 5. JSON Support .............................................................................................................. 40 5.1. POJO support ..................................................................................................... 40 5.2. JAXB Based JSON support .................................................................................. 40 iii Jersey 1.8 User Guide 5.2.1. Configuration Options ............................................................................... 41 5.2.2. JSON Notations ....................................................................................... 42 5.2.3. Examples ................................................................................................ 48 5.3. Low-Level JSON support ..................................................................................... 48 5.3.1. Examples ................................................................................................ 49 6. Declarative Hyperlinking ................................................................................................ 50 6.1. Links in Representations ...................................................................................... 50 6.2. Binding Template Parameters ................................................................................ 50 6.3. Conditional Link Injection .................................................................................... 51 6.4. Link Headers ..................................................................................................... 51 6.5. Configuration ..................................................................................................... 51 7. Jersey Test Framework ................................................................................................... 53 7.1. What is different in Jersey 1.2 .............................................................................. 53 7.2. Using test framework .......................................................................................... 53 7.3. Creating tests ..................................................................................................... 54 7.4. Creating own module .......................................................................................... 55 7.5. Running tests outside Maven ................................................................................ 55 8. OSGi .......................................................................................................................... 57 8.1. Feature Overview ............................................................................................... 57 8.2. WAB Example ................................................................................................... 58 8.3. Http Service Example .......................................................................................... 58 9. JRebel support .............................................................................................................. 60 9.1. How to use JRebel with Jersey .............................................................................. 60 9.2. Using JRebel with the hello world sample ............................................................... 60 9.3. Limitations ........................................................................................................ 61 10. Experimental Features .................................................................................................. 62 10.1. Hypermedia Actions .......................................................................................... 62 10.1.1. Introduction ........................................................................................... 62 10.1.2. Hypermedia by Example .......................................................................... 62 10.1.3. Server