Jersey 3.0.0-M1 User Guide Jersey 3.0.0-M1 User Guide Table of Contents
Total Page:16
File Type:pdf, Size:1020Kb
Jersey 3.0.0-M1 User Guide Jersey 3.0.0-M1 User Guide Table of Contents Preface ........................................................................................................................... xvii 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 ............................................................. 42 3.1. Root Resource Classes ......................................................................................... 42 3.1.1. @Path ..................................................................................................... 42 3.1.2. @GET, @PUT, @POST, @DELETE, ... (HTTP Methods) ............................... 43 3.1.3. @Produces ............................................................................................... 44 3.1.4. @Consumes ............................................................................................. 45 3.2. Parameter Annotations (@*Param) ......................................................................... 46 3.3. Sub-resources ..................................................................................................... 50 3.4. Life-cycle of Root Resource Classes ....................................................................... 53 3.5. Rules of Injection ................................................................................................ 54 3.6. Use of @Context ................................................................................................ 57 3.7. Programmatic resource model ................................................................................ 57 4. Application Deployment and Runtime Environments ............................................................ 58 4.1. Introduction ........................................................................................................ 58 4.2. JAX-RS Application Model .................................................................................. 58 4.3. Auto-Discoverable Features ................................................................................... 59 4.3.1. Configuring Feature Auto-discovery Mechanism ............................................ 59 4.4. Configuring the Classpath Scanning ....................................................................... 60 4.5. Java SE Deployment Environments ........................................................................ 62 4.5.1. HTTP servers ........................................................................................... 62 4.6. Creating programmatic JAX-RS endpoint ................................................................ 65 4.7. Servlet-based Deployment ..................................................................................... 65 4.7.1. Servlet 2.x Container ................................................................................. 65 4.7.2. Servlet 3.x Container ................................................................................. 67 4.7.3. Jersey Servlet container modules ................................................................. 71 4.8. Java EE Platform ................................................................................................ 72 4.8.1. Managed Beans ........................................................................................ 72 4.8.2. Context and Dependency Injection (CDI) ...................................................... 72 4.8.3. Enterprise Java Beans (EJB) ....................................................................... 73 4.8.4. Java EE Servers ........................................................................................ 73 4.9. OSGi ................................................................................................................. 74 4.9.1. Enabling the OSGi shell in Glassfish ............................................................ 75 4.9.2. WAB Example ......................................................................................... 76 iii Jersey 3.0.0-M1 User Guide 4.9.3. HTTP Service Example ............................................................................. 76 4.10. Other Environments ........................................................................................... 77 4.10.1. Oracle Java Cloud Service ........................................................................ 77 5. Client API .................................................................................................................... 78 5.1. Uniform Interface Constraint ................................................................................. 78 5.2. Ease of use and reusing JAX-RS artifacts ................................................................ 79 5.3. Overview of the Client API .................................................................................. 80 5.3.1. Getting started with the client API ............................................................... 80 5.3.2. Creating and configuring a Client instance ..................................................... 80 5.3.3. Targeting a web resource ........................................................................... 82 5.3.4. Identifying resource on WebTarget .............................................................. 82 5.3.5. Invoking a HTTP request ........................................................................... 83 5.3.6. Example summary .................................................................................... 84 5.3.7. Setting ExecutorService and ScheduledExecutorService ................................... 85 5.4. Java instances and types for representations ............................................................. 86 5.4.1. Adding support for new representations ........................................................ 86 5.5. Client Transport Connectors .................................................................................. 86 5.6. Using client request and response filters .................................................................. 89 5.7. Closing connections ............................................................................................. 89 5.8. Injections into client providers ............................................................................... 90 5.9. Securing a Client ................................................................................................. 91 5.9.1. Http Authentication Support ....................................................................... 92 6. Reactive JAX-RS Client API ........................................................................................... 94 6.1. Motivation for Reactive Client Extension ................................................................ 94 6.2. Usage and Extension Modules ............................................................................. 100 6.3. Supported Reactive Libraries ............................................................................... 101 6.3.1. RxJava (Observable) ................................................................................ 101 6.3.2. RxJava (Flowable) ................................................................................... 103 6.3.3. Guava (ListenableFuture and Futures) ......................................................... 104 6.4. Implementing Support for Custom Reactive Libraries (SPI) ....................................... 105 7. Representations and Responses ....................................................................................... 107 7.1. Representations and Java Types ..........................................................................