Jersey 2.5.1 User Guide Jersey 2.5.1 User Guide Table of Contents Preface ........................................................................................................................... xiv 1. Getting Started ............................................................................................................... 1 1.1. Creating a New Project from Maven Archetype ......................................................... 1 1.2. Exploring the Newly Created Project ....................................................................... 1 1.3. Running the Project .............................................................................................. 3 1.4. Creating a JavaEE Web Application ........................................................................ 5 1.5. Creating a Web Application that can be deployed on Heroku ........................................ 6 1.5.1. Deploy it on Heroku ................................................................................... 8 1.6. Exploring Other Jersey Examples .......................................................................... 11 2. Modules and dependencies .............................................................................................. 12 2.1. Java SE Compatibility ......................................................................................... 12 2.2. Introduction to Jersey dependencies ....................................................................... 12 2.3. Common Jersey Use Cases ................................................................................... 12 2.3.1. Servlet based application on Glassfish .......................................................... 12 2.3.2. Servlet based server-side application ............................................................ 13 2.3.3. Client application on JDK .......................................................................... 13 2.3.4. Server-side application on supported containers .............................................. 14 2.4. List of modules .................................................................................................. 15 3. JAX-RS Application, Resources and Sub-Resources ............................................................ 30 3.1. Root Resource Classes ......................................................................................... 30 3.1.1. @Path .................................................................................................... 30 3.1.2. @GET, @PUT, @POST, @DELETE, ... (HTTP Methods) ............................... 31 3.1.3. @Produces .............................................................................................. 32 3.1.4. @Consumes ............................................................................................ 33 3.2. Parameter Annotations (@*Param) ......................................................................... 34 3.3. Sub-resources ..................................................................................................... 38 3.4. Life-cycle of Root Resource Classes ...................................................................... 42 3.5. Rules of Injection ............................................................................................... 43 3.6. Use of @Context ................................................................................................ 46 3.7. Programmatic resource model ............................................................................... 47 4. Application Deployment and Runtime Environments ........................................................... 48 4.1. Introduction ....................................................................................................... 48 4.2. JAX-RS Application Model .................................................................................. 48 4.3. Auto-Discoverable Features .................................................................................. 49 4.3.1. Configuring Feature Auto-discovery Mechanism ............................................ 49 4.4. Configuring the Classpath Scanning ....................................................................... 50 4.5. Java SE Deployment Environments ........................................................................ 51 4.5.1. HTTP servers .......................................................................................... 51 4.6. Creating programmatic JAX-RS endpoint ................................................................ 53 4.7. Servlet-based Deployment .................................................................................... 54 4.7.1. Servlet 2.x Container ................................................................................ 54 4.7.2. Servlet 3.x Container ................................................................................ 56 4.7.3. Jersey Servlet container modules ................................................................. 60 4.8. Java EE Platform ................................................................................................ 60 4.8.1. Managed Beans ........................................................................................ 60 4.8.2. Context and Dependency Injection (CDI) ...................................................... 61 4.8.3. Enterprise Java Beans (EJB) ....................................................................... 61 4.8.4. Java EE Servers ....................................................................................... 62 4.9. OSGi ................................................................................................................ 62 4.9.1. Enabling the OSGi shell in Glassfish ........................................................... 63 4.9.2. WAB Example ........................................................................................ 64 iii Jersey 2.5.1 User Guide 4.9.3. HTTP Service Example ............................................................................. 64 4.10. Other Environments ........................................................................................... 66 4.10.1. Oracle Java Cloud Service ........................................................................ 66 5. Client API ................................................................................................................... 67 5.1. Uniform Interface Constraint ................................................................................ 67 5.2. Ease of use and reusing JAX-RS artifacts ................................................................ 68 5.3. Overview of the Client API .................................................................................. 69 5.3.1. Getting started with the client API ............................................................... 69 5.3.2. Creating and configuring a Client instance .................................................... 69 5.3.3. Targeting a web resource ........................................................................... 71 5.3.4. Identifying resource on WebTarget .............................................................. 71 5.3.5. Invoking a HTTP request ........................................................................... 72 5.3.6. Example summary .................................................................................... 73 5.4. Java instances and types for representations ............................................................. 74 5.4.1. Adding support for new representations ........................................................ 74 5.5. Client Transport Connectors ................................................................................. 75 5.6. Using client request and response filters .................................................................. 76 5.7. Closing connections ............................................................................................ 76 5.8. Securing a Client ................................................................................................ 76 5.8.1. Http Authentication Support ....................................................................... 77 6. Representations and Responses ........................................................................................ 79 6.1. Representations and Java Types ............................................................................ 79 6.2. Building Responses ............................................................................................. 80 6.3. WebApplicationException and Mapping Exceptions to Responses ................................ 81 6.4. Conditional GETs and Returning 304 (Not Modified) Responses ................................. 83 7. JAX-RS Entity Providers ................................................................................................ 85 7.1. Introduction ....................................................................................................... 85 7.2. How to Write Custom Entity Providers ................................................................... 85 7.2.1. MessageBodyWriter .................................................................................. 86 7.2.2. MessageBodyReader ................................................................................. 90 7.3. Entity Provider Selection ...................................................................................... 92 7.4. Jersey MessageBodyWorkers API ...................................................................