User Guide

user-guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 352

Download
Open PDF In Browser	View PDF

Jersey 2.28 User Guide

Jersey 2.28 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 ............................................................. 37
3.1. Root Resource Classes ......................................................................................... 37
3.1.1. @Path ..................................................................................................... 37
3.1.2. @GET, @PUT, @POST, @DELETE, ... (HTTP Methods) ............................... 38
3.1.3. @Produces ............................................................................................... 39
3.1.4. @Consumes ............................................................................................. 40
3.2. Parameter Annotations (@*Param) ......................................................................... 41
3.3. Sub-resources ..................................................................................................... 45
3.4. Life-cycle of Root Resource Classes ....................................................................... 48
3.5. Rules of Injection ................................................................................................ 49
3.6. Use of @Context ................................................................................................ 52
3.7. Programmatic resource model ................................................................................ 52
4. Application Deployment and Runtime Environments ............................................................ 53
4.1. Introduction ........................................................................................................ 53
4.2. JAX-RS Application Model .................................................................................. 53
4.3. Auto-Discoverable Features ................................................................................... 54
4.3.1. Configuring Feature Auto-discovery Mechanism ............................................ 54
4.4. Configuring the Classpath Scanning ....................................................................... 55
4.5. Java SE Deployment Environments ........................................................................ 57
4.5.1. HTTP servers ........................................................................................... 57
4.6. Creating programmatic JAX-RS endpoint ................................................................ 60
4.7. Servlet-based Deployment ..................................................................................... 60
4.7.1. Servlet 2.x Container ................................................................................. 60
4.7.2. Servlet 3.x Container ................................................................................. 62
4.7.3. Jersey Servlet container modules ................................................................. 66
4.8. Java EE Platform ................................................................................................ 67
4.8.1. Managed Beans ........................................................................................ 67
4.8.2. Context and Dependency Injection (CDI) ...................................................... 67
4.8.3. Enterprise Java Beans (EJB) ....................................................................... 68
4.8.4. Java EE Servers ........................................................................................ 68
4.9. OSGi ................................................................................................................. 69
4.9.1. Enabling the OSGi shell in Glassfish ............................................................ 70
4.9.2. WAB Example ......................................................................................... 71

iii

Jersey 2.28 User Guide

5.

6.

7.

8.

9.

4.9.3. HTTP Service Example ............................................................................. 71
4.10. Other Environments ........................................................................................... 72
4.10.1. Oracle Java Cloud Service ........................................................................ 72
Client API .................................................................................................................... 74
5.1. Uniform Interface Constraint ................................................................................. 74
5.2. Ease of use and reusing JAX-RS artifacts ................................................................ 75
5.3. Overview of the Client API .................................................................................. 76
5.3.1. Getting started with the client API ............................................................... 76
5.3.2. Creating and configuring a Client instance ..................................................... 76
5.3.3. Targeting a web resource ........................................................................... 78
5.3.4. Identifying resource on WebTarget .............................................................. 78
5.3.5. Invoking a HTTP request ........................................................................... 79
5.3.6. Example summary .................................................................................... 80
5.3.7. Setting ExecutorService and ScheduledExecutorService ................................... 81
5.4. Java instances and types for representations ............................................................. 82
5.4.1. Adding support for new representations ........................................................ 82
5.5. Client Transport Connectors .................................................................................. 82
5.6. Using client request and response filters .................................................................. 85
5.7. Closing connections ............................................................................................. 85
5.8. Injections into client providers ............................................................................... 86
5.9. Securing a Client ................................................................................................. 86
5.9.1. Http Authentication Support ....................................................................... 88
Reactive JAX-RS Client API ........................................................................................... 90
6.1. Motivation for Reactive Client Extension ................................................................ 90
6.2. Usage and Extension Modules ............................................................................... 96
6.3. Supported Reactive Libraries ................................................................................. 97
6.3.1. RxJava (Observable) .................................................................................. 98
6.3.2. RxJava (Flowable) .................................................................................... 99
6.3.3. Guava (ListenableFuture and Futures) ......................................................... 100
6.4. Implementing Support for Custom Reactive Libraries (SPI) ....................................... 101
Representations and Responses ....................................................................................... 103
7.1. Representations and Java Types ........................................................................... 103
7.2. Building Responses ............................................................................................ 104
7.3. WebApplicationException and Mapping Exceptions to Responses .............................. 105
7.4. Conditional GETs and Returning 304 (Not Modified) Responses ................................ 107
JAX-RS Entity Providers ............................................................................................... 109
8.1. Introduction ...................................................................................................... 109
8.2. How to Write Custom Entity Providers .................................................................. 109
8.2.1. MessageBodyWriter ................................................................................. 110
8.2.2. MessageBodyReader ................................................................................ 114
8.3. Entity Provider Selection .................................................................................... 116
8.4. Jersey MessageBodyWorkers API ................................................................... 119
8.5. Default Jersey Entity Providers ............................................................................ 120
Support for Common Media Type Representations ............................................................. 122
9.1. JSON ............................................................................................................... 122
9.1.1. Approaches to JSON Support .................................................................... 122
9.1.2. MOXy ................................................................................................... 125
9.1.3. Java API for JSON Processing (JSON-P) ..................................................... 127
9.1.4. Jackson (1.x and 2.x) ............................................................................... 129
9.1.5. Jettison .................................................................................................. 131
9.1.6. @JSONP - JSON with Padding Support ....................................................... 135
9.2. XML ............................................................................................................... 137
9.2.1. Low level XML support ........................................................................... 137
9.2.2. Getting started with JAXB ........................................................................ 138

iv

Jersey 2.28 User Guide

10.

11.

12.

13.

14.

15.

9.2.3. POJOs ................................................................................................... 139
9.2.4. Using custom JAXBContext ...................................................................... 140
9.2.5. MOXy ................................................................................................... 141
9.3. Multipart .......................................................................................................... 142
9.3.1. Overview ............................................................................................... 142
9.3.2. Client .................................................................................................... 143
9.3.3. Server ................................................................................................... 145
Filters and Interceptors ................................................................................................ 148
10.1. Introduction ..................................................................................................... 148
10.2. Filters ............................................................................................................ 148
10.2.1. Server filters ......................................................................................... 148
10.2.2. Client filters ......................................................................................... 151
10.3. Interceptors ..................................................................................................... 151
10.4. Filter and interceptor execution order .................................................................. 153
10.5. Name binding .................................................................................................. 155
10.6. Dynamic binding ............................................................................................. 156
10.7. Priorities ......................................................................................................... 157
Asynchronous Services and Clients ................................................................................ 159
11.1. Asynchronous Server API .................................................................................. 159
11.1.1. Asynchronous Server-side Callbacks ......................................................... 161
11.1.2. Chunked Output .................................................................................... 162
11.2. Client API ...................................................................................................... 164
11.2.1. Asynchronous Client Callbacks ................................................................ 165
11.2.2. Chunked input ...................................................................................... 166
URIs and Links .......................................................................................................... 168
12.1. Building URIs ................................................................................................. 168
12.2. Resolve and Relativize ...................................................................................... 169
12.3. Link ............................................................................................................... 169
Declarative Hyperlinking ............................................................................................. 171
13.1. Dependency .................................................................................................... 171
13.2. Links in Representations ................................................................................... 171
13.3. List of Link Injection ........................................................................................ 172
13.4. Links from Resources ....................................................................................... 172
13.5. Binding Template Parameters ............................................................................. 172
13.6. Conditional Link Injection ................................................................................. 173
13.7. Link Headers ................................................................................................... 173
13.8. Prevent Recursive Injection ................................................................................ 174
13.9. Meta-annotation support .................................................................................... 174
13.10. Configure and register ..................................................................................... 175
Programmatic API for Building Resources ...................................................................... 176
14.1. Introduction ..................................................................................................... 176
14.2. Programmatic Hello World example .................................................................... 176
14.2.1. Deployment of programmatic resources ..................................................... 178
14.3. Additional examples ......................................................................................... 179
14.4. Model processors ............................................................................................. 180
Server-Sent Events (SSE) Support ................................................................................. 182
15.1. What are Server-Sent Events .............................................................................. 182
15.2. When to use Server-Sent Events ......................................................................... 183
15.3. Server-Sent Events API ..................................................................................... 183
15.4. Implementing SSE support in a JAX-RS resource (with JAX-RS SSE API) ................. 184
15.4.1. Simple SSE resource method ................................................................... 184
15.4.2. Broadcasting with Jersey SSE .................................................................. 186
15.5. Consuming SSE events within Jersey clients ......................................................... 188
15.5.1. SseEventSource reconnect support ...................................................... 190

v

Jersey 2.28 User Guide

16.

17.

18.

19.

20.

15.6. Jersey-specific Server-Sent Events API ................................................................ 190
15.6.1. Implementing SSE support in a JAX-RS resource ........................................ 191
15.6.2. Consuming SSE events with Jersey clients ................................................. 194
Security .................................................................................................................... 198
16.1. Securing server ................................................................................................ 198
16.1.1. SecurityContext ..................................................................................... 198
16.1.2. Authorization - securing resources ............................................................ 199
16.2. Client Security ................................................................................................. 201
16.3. OAuth Support ................................................................................................ 201
16.3.1. OAuth 1 ............................................................................................... 203
16.3.2. OAuth 2 Support ................................................................................... 207
WADL Support .......................................................................................................... 210
17.1. WADL introduction .......................................................................................... 210
17.2. Configuration .................................................................................................. 218
17.3. Extended WADL support .................................................................................. 219
Bean Validation Support .............................................................................................. 220
18.1. Bean Validation Dependencies ........................................................................... 220
18.2. Enabling Bean Validation in Jersey ..................................................................... 220
18.3. Configuring Bean Validation Support .................................................................. 221
18.4. Validating JAX-RS resources and methods ........................................................... 223
18.4.1. Constraint Annotations ........................................................................... 223
18.4.2. Annotation constraints and Validators ....................................................... 225
18.4.3. Entity Validation ................................................................................... 226
18.4.4. Annotation Inheritance ........................................................................... 227
18.5. @ValidateOnExecution ..................................................................................... 227
18.6. Injecting ......................................................................................................... 228
18.7. Error Reporting ............................................................................................... 229
18.7.1. ValidationError ..................................................................................... 230
18.8. Example ......................................................................................................... 232
Entity Data Filtering ................................................................................................... 233
19.1. Enabling and configuring Entity Filtering in your application ................................... 233
19.2. Components used to describe Entity Filtering concepts ........................................... 235
19.3. Using custom annotations to filter entities ............................................................ 237
19.3.1. Server-side Entity Filtering ...................................................................... 239
19.3.2. Client-side Entity Filtering ...................................................................... 241
19.4. Role-based Entity Filtering using (javax.annotation.security) annotations .... 242
19.5. Entity Filtering based on dynamic and configurable query parameters ........................ 242
19.6. Defining custom handling for entity-filtering annotations ......................................... 243
19.7. Supporting Entity Data Filtering in custom entity providers or frameworks .................. 244
19.8. Modules with support for Entity Data Filtering ...................................................... 245
19.9. Examples ........................................................................................................ 245
MVC Templates ......................................................................................................... 246
20.1. Viewable ........................................................................................................ 246
20.2. @Template ..................................................................................................... 247
20.2.1. Annotating Resource methods .................................................................. 247
20.2.2. Annotating Resource classes .................................................................... 247
20.3. Absolute vs. Relative template reference .............................................................. 248
20.3.1. Relative template reference ..................................................................... 248
20.3.2. Absolute template reference ..................................................................... 249
20.4. Handling errors with MVC ................................................................................ 249
20.4.1. MVC & Bean Validation ........................................................................ 250
20.5. Registration and Configuration ........................................................................... 251
20.6. Supported templating engines ............................................................................. 252
20.6.1. Mustache .............................................................................................. 252

vi

Jersey 2.28 User Guide

21.

22.

23.

24.

25.

26.

27.

28.

20.6.2. Freemarker ........................................................................................... 253
20.6.3. JSP ..................................................................................................... 254
20.7. Writing Custom Templating Engines ................................................................... 255
20.8. Other Examples ............................................................................................... 257
Logging .................................................................................................................... 258
21.1. Logging traffic ................................................................................................ 258
21.1.1. Introduction .......................................................................................... 258
21.1.2. Configuration and registering ................................................................... 258
Monitoring and Diagnostics .......................................................................................... 261
22.1. Monitoring Jersey Applications .......................................................................... 261
22.1.1. Introduction .......................................................................................... 261
22.1.2. Event Listeners ..................................................................................... 262
22.2. Tracing Support ............................................................................................... 271
22.2.1. Configuration options ............................................................................. 271
22.2.2. Tracing Log .......................................................................................... 272
22.2.3. Configuring tracing support via HTTP request headers ................................. 272
22.2.4. Format of the HTTP response headers ....................................................... 272
22.2.5. Tracing Examples .................................................................................. 273
Custom Injection and Lifecycle Management .................................................................. 275
23.1. Implementing Custom Injection Provider .............................................................. 275
23.2. Defining Custom Injection Annotation ................................................................. 277
23.3. Custom Life Cycle Management ......................................................................... 279
Jersey CDI Container Agnostic Support .......................................................................... 283
24.1. Introduction ..................................................................................................... 283
24.2. Containers Known to Work With Jersey CDI Support ............................................. 283
24.3. Request Scope Binding ..................................................................................... 283
24.4. Jersey Weld SE Support .................................................................................... 284
Spring DI .................................................................................................................. 285
25.1. Dependencies .................................................................................................. 285
25.2. Registration and Configuration ........................................................................... 286
25.3. Example ......................................................................................................... 286
Jersey Test Framework ................................................................................................ 287
26.1. Basics ............................................................................................................ 287
26.2. Supported Containers ........................................................................................ 288
26.3. Running TestNG Tests ...................................................................................... 289
26.4. Advanced features ............................................................................................ 292
26.4.1. JerseyTest Features .......................................................................... 292
26.4.2. External container .................................................................................. 292
26.4.3. Test Client configuration ......................................................................... 292
26.4.4. Accessing the logged test records programmatically ..................................... 293
26.5. Parallel Testing with Jersey Test Framework ......................................................... 293
Building and Testing Jersey ......................................................................................... 295
27.1. Checking Out the Source ................................................................................... 295
27.2. Building the Source .......................................................................................... 295
27.3. Testing ........................................................................................................... 295
27.4. Using NetBeans ............................................................................................... 296
Migration Guide ......................................................................................................... 297
28.1. Migrating from Jersey 2.23 to 2.27 ..................................................................... 297
28.1.1. Breaking Changes .................................................................................. 297
28.1.2. Breaking Changes - Injection Manager ...................................................... 297
28.1.3. Removed deprecated APIs ....................................................................... 298
28.2. Migrating from Jersey 2.22.1 to 2.23 ................................................................... 298
28.2.1. Release 2.23 Highlights .......................................................................... 298
28.2.2. Deprecated APIs .................................................................................... 298

vii

Jersey 2.28 User Guide

28.3. Breaking Changes ............................................................................................
28.4. Migrating from Jersey 2.22 to 2.22.1 ...................................................................
28.4.1. Breaking Changes ..................................................................................
28.5. Migrating from Jersey 2.21 to 2.22 .....................................................................
28.5.1. Breaking Changes ..................................................................................
28.6. Migrating from Jersey 2.19 to 2.20 .....................................................................
28.6.1. Breaking Changes ..................................................................................
28.7. Migrating from Jersey 2.18 to 2.19 .....................................................................
28.7.1. Breaking Changes ..................................................................................
28.8. Migrating from Jersey 2.17 to 2.18 .....................................................................
28.8.1. Release 2.18 Highlights ..........................................................................
28.8.2. Removed deprecated APIs .......................................................................
28.8.3. Breaking Changes ..................................................................................
28.9. Migrating from Jersey 2.16 to 2.17 .....................................................................
28.9.1. Release 2.17 Highlights ..........................................................................
28.10. Migrating from Jersey 2.15 to 2.16 ....................................................................
28.10.1. Release 2.16 Highlights ........................................................................
28.10.2. Deprecated APIs ..................................................................................
28.10.3. Breaking Changes ................................................................................
28.11. Migrating to 2.15 ...........................................................................................
28.11.1. Release 2.15 Highlights ........................................................................
28.11.2. Breaking Changes ................................................................................
28.12. Migrating from Jersey 2.11 to 2.12 ....................................................................
28.12.1. Release 2.12 Highlights ........................................................................
28.12.2. Breaking Changes ................................................................................
28.13. Migrating from Jersey 2.10 to 2.11 ....................................................................
28.13.1. Release 2.11 Highlights ........................................................................
28.14. Migrating from Jersey 2.9 to 2.10 .....................................................................
28.14.1. Removed deprecated APIs .....................................................................
28.15. Migrating from Jersey 2.8 to 2.9 .......................................................................
28.15.1. Release 2.9 Highlights ..........................................................................
28.15.2. Changes .............................................................................................
28.16. Migrating from Jersey 2.7 to 2.8 .......................................................................
28.16.1. Changes .............................................................................................
28.17. Migrating from Jersey 2.6 to 2.7 .......................................................................
28.17.1. Changes .............................................................................................
28.18. Migrating from Jersey 2.5.1 to 2.6 .....................................................................
28.18.1. Guava and ASM have been embedded .....................................................
28.18.2. Deprecated APIs ..................................................................................
28.18.3. Removed deprecated APIs .....................................................................
28.19. Migrating from Jersey 2.5 to 2.5.1 .....................................................................
28.20. Migrating from Jersey 2.4.1 to 2.5 .....................................................................
28.20.1. Client-side API and SPI changes ............................................................
28.20.2. Other changes .....................................................................................
28.21. Migrating from Jersey 2.4 to 2.4.1 .....................................................................
28.22. Migrating from Jersey 2.3 to 2.4 .......................................................................
28.23. Migrating from Jersey 2.0, 2.1 or 2.2 to 2.3 ........................................................
28.24. Migrating from Jersey 1.x to 2.0 .......................................................................
28.24.1. Server API ..........................................................................................
28.24.2. Migrating Jersey Client API ...................................................................
28.24.3. JSON support changes ..........................................................................
A. Configuration Properties ...............................................................................................
A.1. Common (client/server) configuration properties .....................................................
A.2. Server configuration properties ............................................................................

viii

299
299
299
299
299
300
300
300
300
300
300
301
301
302
302
302
302
302
303
303
303
303
304
304
304
304
304
305
305
305
305
306
306
306
309
309
310
310
310
311
312
312
312
313
314
314
314
315
315
318
321
324
324
325

Jersey 2.28 User Guide

A.3. Servlet configuration properties ........................................................................... 331
A.4. Client configuration properties ............................................................................ 332

ix

List of Figures
6.1. Travel Agency Orchestration Service .............................................................................. 91
6.2. Time consumed to create a response for the client – synchronous way ................................... 92
6.3. Time consumed to create a response for the client – asynchronous way ................................. 94

x

List of Tables
2.1. Jersey Core ................................................................................................................ 15
2.2. Jersey Containers ........................................................................................................ 15
2.3. Jersey Connectors ........................................................................................................ 16
2.4. Jersey Media .............................................................................................................. 17
2.5. Jersey Extensions ........................................................................................................ 19
2.6. Jersey Test Framework ................................................................................................. 21
2.7. Jersey Test Framework Providers ................................................................................... 23
2.8. Jersey Glassfish Bundles .............................................................................................. 25
2.9. Security ..................................................................................................................... 25
2.10. Jersey Examples ........................................................................................................ 25
3.1. Resource scopes .......................................................................................................... 49
3.2. Overview of injection types .......................................................................................... 51
4.1. Servlet 3 Pluggability Overview ..................................................................................... 66
5.1. List of Jersey Connectors .............................................................................................. 83
9.1. Default property values for MOXy MessageBodyReader / MessageBodyWriter ......... 127
28.1. List of changed configuration properties: ...................................................................... 308
28.2. Mapping of Jersey 1.x to JAX-RS 2.0 client classes ....................................................... 318
28.3. JSON approaches and usage in Jersey 1 vs Jersey 2 ........................................................ 321
A.1. List of common configuration properties ....................................................................... 324
A.2. List of server configuration properties .......................................................................... 325
A.3. List of servlet configuration properties .......................................................................... 331
A.4. List of client configuration properties ........................................................................... 332

xi

List of Examples
3.1. Simple hello world root resource class ............................................................................ 37
3.2. Specifying URI path parameter ...................................................................................... 38
3.3. PUT method ............................................................................................................... 39
3.4. Specifying output MIME type ....................................................................................... 39
3.5. Using multiple output MIME types ................................................................................ 40
3.6. Server-side content negotiation ...................................................................................... 40
3.7. Specifying input MIME type ......................................................................................... 41
3.8. Query parameters ........................................................................................................ 41
3.9. Custom Java type for consuming request parameters .......................................................... 41
3.10. Processing POSTed HTML form .................................................................................. 43
3.11. Obtaining general map of URI path and/or query parameters ............................................. 43
3.12. Obtaining general map of header parameters .................................................................. 43
3.13. Obtaining general map of form parameters ..................................................................... 43
3.14. Example of the bean which will be used as @BeanParam ................................................. 44
3.15. Injection of MyBeanParam as a method parameter: .......................................................... 44
3.16. Injection of more beans into one resource methods: ......................................................... 45
3.17. Sub-resource methods ................................................................................................. 45
3.18. Sub-resource locators ................................................................................................. 46
3.19. Sub-resource locators with empty path .......................................................................... 47
3.20. Sub-resource locators returning sub-type ........................................................................ 47
3.21. Sub-resource locators created from classes ..................................................................... 47
3.22. Sub-resource locators returning resource model ............................................................... 48
3.23. Injection ................................................................................................................... 49
3.24. Wrong injection into a singleton scope .......................................................................... 50
3.25. Injection of proxies into singleton ................................................................................. 50
3.26. Example of possible injections ..................................................................................... 51
4.1. Deployment agnostic application model ........................................................................... 53
4.2. Reusing Jersey implementation in your custom application model ........................................ 54
4.3. Registering SPI implementations using ResourceConfig ..................................................... 56
4.4. Registering SPI implementations using ResourceConfig subclass ................................... 56
4.5. Using Jersey with JDK HTTP Server .............................................................................. 57
4.6. Using Jersey with Grizzly HTTP Server .......................................................................... 58
4.7. Using Jersey with the Simple framework ......................................................................... 58
4.8. Using Jersey with Jetty HTTP Server .............................................................................. 59
4.9. Using Jersey with Netty HTTP Server ............................................................................ 59
4.10. Hooking up Jersey as a Servlet .................................................................................... 60
4.11. Hooking up Jersey as a Servlet Filter ............................................................................ 60
4.12. Configuring Jersey container Servlet or Filter to use custom Application subclass ............ 61
4.13. Configuring Jersey container Servlet or Filter to use package scanning ................................ 62
4.14. Configuring Jersey container Servlet or Filter to use a list of classes ................................... 62
4.15. Deployment of a JAX-RS application using @ApplicationPath with Servlet 3.0 .............. 63
4.16. Configuration of maven-war-plugin to ignore missing web.xml ........................................ 63
4.17. Deployment of a JAX-RS application using web.xml with Servlet 3.0 ............................... 63
4.18. web.xml of a JAX-RS application without an Application subclass ............................. 64
4.19. ................................................................................................................................ 65
4.20. ................................................................................................................................ 70
5.1. POST request with form parameters ............................................................................... 75
5.2. Using JAX-RS Client API ............................................................................................ 80
5.3. Using JAX-RS Client API fluently ................................................................................. 81
5.4. Setting JAX-RS Client ExecutorService .......................................................................... 81
5.5. Sending restricted headers with HttpUrlConnector ..................................................... 84

xii

Jersey 2.28 User Guide

5.6. Closing connections ..................................................................................................... 85
5.7. ServiceLocatorClientProvider example ............................................................................ 86
6.1. Excerpt from a synchronous approach while implementing the orchestration layer ................... 91
6.2. Excerpt from an asynchronous approach while implementing the orchestration layer ................ 93
6.3. Excerpt from a reactive approach while implementing the orchestration layer ......................... 95
6.4. Synchronous invocation of HTTP requests ....................................................................... 96
6.5. Asynchronous invocation of HTTP requests ..................................................................... 96
6.6. Reactive invocation of HTTP requests ............................................................................ 96
6.7. Creating JAX-RS Client with RxJava reactive extension ..................................................... 98
6.8. Obtaining Observable from Jersey/RxJava Client .............................................. 98
6.9. Creating JAX-RS Client with RxJava2 reactive extension ................................................... 99
6.10. Obtaining Flowable from Jersey/RxJava Client ............................................... 99
6.11. Creating Jersey/Guava Client ..................................................................................... 100
6.12. Obtaining ListenableFuture from Jersey/Guava Client .................................... 100
6.13. Extending RxIvoker .................................................................................................. 101
6.14. Extending RxInvokerProvider ..................................................................................... 102
7.1. Using File with a specific media type to produce a response ........................................... 104
7.2. Returning 201 status code and adding Location header in response to POST request ........... 104
7.3. Adding an entity body to a custom response ................................................................... 105
7.4. Throwing exceptions to control response ....................................................................... 105
7.5. Application specific exception implementation ................................................................ 105
7.6. Mapping generic exceptions to responses ....................................................................... 106
7.7. Conditional GET support ............................................................................................ 107
8.1. Example resource class ............................................................................................... 109
8.2. MyBean entity class ................................................................................................... 110
8.3. MessageBodyWriter example ....................................................................................... 111
8.4. Example of assignment of annotations to a response entity ................................................ 112
8.5. Client code testing MyBeanMessageBodyWriter ............................................................. 113
8.6. Result of MyBeanMessageBodyWriter test ..................................................................... 114
8.7. MessageBodyReader example ...................................................................................... 114
8.8. Testing MyBeanMessageBodyReader ............................................................................ 115
8.9. Result of testing MyBeanMessageBodyReader ................................................................ 116
8.10. MessageBodyReader registered on a JAX-RS client ....................................................... 116
8.11. Result of client code execution ................................................................................... 116
8.12. Usage of MessageBodyWorkers interface ..................................................................... 119
9.1. Simple JAXB bean implementation ............................................................................... 123
9.2. JAXB bean used to generate JSON representation ........................................................... 123
9.3. Tweaking JSON format using JAXB ............................................................................. 123
9.4. JAXB bean creation ................................................................................................... 124
9.5. Constructing a JsonObject (JSON-Processing) ........................................................... 124
9.6. Constructing a JSONObject (Jettison) ........................................................................ 124
9.7. MoxyJsonConfig - Setting properties. ............................................................................ 126
9.8. Creating ContextResolver .................................................... 126
9.9. Setting properties for MOXy providers into Configurable ................................................. 126
9.10. Building client with MOXy JSON feature enabled. ........................................................ 127
9.11. Creating JAX-RS application with MOXy JSON feature enabled. ..................................... 127
9.12. Building client with JSON-Processing JSON feature enabled. ........................................... 128
9.13. Creating JAX-RS application with JSON-Processing JSON feature enabled. ........................ 128
9.14. ContextResolver ................................................................... 130
9.15. Building client with Jackson JSON feature enabled. ....................................................... 130
9.16. Creating JAX-RS application with Jackson JSON feature enabled. .................................... 130
9.17. JAXB beans for JSON supported notations description, simple address bean ....................... 131
9.18. JAXB beans for JSON supported notations description, contact bean ................................. 132
9.19. JAXB beans for JSON supported notations description, initialization ................................. 132

xiii

Jersey 2.28 User Guide

9.20. XML namespace to JSON mapping configuration for Jettison based mapped notation .......... 132
9.21. JSON expression with XML namespaces mapped into JSON ........................................... 133
9.22. JSON Array configuration for Jettison based mapped notation ........................................ 133
9.23. JSON expression with JSON arrays explicitly configured via Jersey .................................. 133
9.24. JSON expression produced using badgerfish notation ................................................ 134
9.25. ContextResolver ................................................................... 134
9.26. Building client with Jettison JSON feature enabled. ........................................................ 134
9.27. Creating JAX-RS application with Jettison JSON feature enabled. ..................................... 135
9.28. Simplest case of using @JSONP ................................................................................. 135
9.29. JaxbBean for @JSONP example ................................................................................. 135
9.30. Example of @JSONP with configured parameters. .......................................................... 136
9.31. Low level XML test - methods added to HelloWorldResource.java ........................ 137
9.32. Planet class ............................................................................................................. 138
9.33. Resource class ......................................................................................................... 138
9.34. Method for consuming Planet ..................................................................................... 139
9.35. Resource class - JAXBElement .................................................................................. 139
9.36. Client side - JAXBElement ........................................................................................ 140
9.37. PlanetJAXBContextProvider ...................................................................................... 140
9.38. Using Provider with JAX-RS client ............................................................................. 141
9.39. Add jersey-media-moxy dependency. ................................................................... 141
9.40. Register the MoxyXmlFeature class. ....................................................................... 141
9.41. Configure and register an MoxyXmlFeature instance. ................................................. 142
9.42. Building client with MultiPart feature enabled. .............................................................. 143
9.43. Creating JAX-RS application with MultiPart feature enabled. ........................................... 143
9.44. MultiPart entity .................................................................................................. 143
9.45. MultiPart entity in HTTP message. ........................................................................ 144
9.46. FormDataMultiPart entity .................................................................................. 144
9.47. FormDataMultiPart entity in HTTP message. ........................................................ 144
9.48. Multipart - sending files. ........................................................................................... 145
9.49. Resource method using MultiPart as input parameter / return value. .............................. 145
9.50. Use of @FormDataParam annotation ........................................................................ 146
10.1. Container response filter ............................................................................................ 148
10.2. Container request filter .............................................................................................. 149
10.3. Pre-matching request filter ......................................................................................... 150
10.4. Client request filter .................................................................................................. 151
10.5. GZIP writer interceptor ............................................................................................. 152
10.6. GZIP reader interceptor ............................................................................................. 153
10.7. @NameBinding example ......................................................................................... 155
10.8. Dynamic binding example ......................................................................................... 156
10.9. Priorities example .................................................................................................... 158
11.1. Simple async resource .............................................................................................. 159
11.2. Simple async method with timeout .............................................................................. 160
11.3. CompletionCallback example ..................................................................................... 161
11.4. ChunkedOutput example ........................................................................................... 163
11.5. Simple client async invocation ................................................................................... 164
11.6. Simple client fluent async invocation ........................................................................... 164
11.7. Client async callback ................................................................................................ 165
11.8. Client async callback for specific entity ....................................................................... 165
11.9. ChunkedInput example .............................................................................................. 166
12.1. URI building ........................................................................................................... 168
12.2. Building URIs using query parameters ......................................................................... 169
13.1. Creating JAX-RS application with Declarative Linking feature enabled. ............................. 175
14.1. A standard resource class .......................................................................................... 176
14.2. A programmatic resource .......................................................................................... 177

xiv

Jersey 2.28 User Guide

14.3. A programmatic resource .......................................................................................... 178
14.4. A programmatic resource .......................................................................................... 179
14.5. A programmatic resource .......................................................................................... 179
14.6. A programmatic resource .......................................................................................... 180
15.1. Adding the SSE dependency ...................................................................................... 183
15.2. Simple SSE resource method ..................................................................................... 184
15.3. Broadcasting SSE messages (with JAX-RS 2.1 API) ...................................................... 186
15.4. Consuming SSE events with SseEventSource ................................................................ 188
15.5. SseEventSource subscribe() methods ........................................................................... 189
15.6. Add jersey-media-sse dependency. ..................................................................... 191
15.7. Simple SSE resource method ..................................................................................... 191
15.8. Broadcasting SSE messages ....................................................................................... 193
15.9. Registering EventListener with EventSource ..................................................... 195
15.10. Overriding EventSource.onEvent(InboundEvent) method ............................... 197
16.1. Using SecurityContext for a Resource Selection .................................................... 198
16.2. Injecting SecurityContext into a singleton resource ................................................ 198
16.3. Securing resources using web.xml ............................................................................ 199
16.4. Registering RolesAllowedDynamicFeature using ResourceConfig ..................................... 200
16.5. Registering RolesAllowedDynamicFeature by extending ResourceConfig ........................... 200
16.6. Applying javax.annotation.security to JAX-RS resource methods. ..................... 200
16.7. Build the authorization flow utility .............................................................................. 205
16.8. Perform the OAuth Authorization Flow ....................................................................... 205
16.9. Authenticated requests .............................................................................................. 206
16.10. Build feature from Access Token .............................................................................. 206
16.11. Specifying Access Token on a Request. ..................................................................... 206
16.12. Creating Public/Private RSA-SHA1 keys .................................................................... 207
16.13. Building OAuth 2 Authorization Flow. ....................................................................... 208
17.1. A simple WADL example - JAX-RS resource definition ................................................. 210
17.2. A simple WADL example - WADL content ................................................................. 211
17.3. OPTIONS method returning WADL ............................................................................ 214
17.4. More complex WADL example - JAX-RS resource definition .......................................... 215
17.5. More complex WADL example - WADL content .......................................................... 216
18.1. Configuring Jersey specific properties for Bean Validation. ............................................. 221
18.2. Using ValidationConfig to configure Validator. ............................................... 222
18.3. Constraint annotations on input parameters ................................................................... 223
18.4. Constraint annotations on fields .................................................................................. 224
18.5. Constraint annotations on class ................................................................................... 225
18.6. Definition of a constraint annotation ............................................................................ 225
18.7. Validator implementation. .......................................................................................... 225
18.8. Entity validation ...................................................................................................... 226
18.9. Entity validation 2 .................................................................................................... 226
18.10. Response entity validation ....................................................................................... 227
18.11. Validate getter on execution ..................................................................................... 227
18.12. Injecting UriInfo into a ConstraintValidator ................................................................ 228
18.13. Support for injecting Jersey's resources/providers via ConstraintValidatorFactory. .............. 229
18.14. ValidationError to text/plain ..................................................................... 231
18.15. ValidationError to text/html ....................................................................... 231
18.16. ValidationError to application/xml ........................................................... 231
18.17. ValidationError to application/json ......................................................... 232
19.1. Registering and configuring entity-filtering feature on server. ........................................... 234
19.2. Registering and configuring entity-filtering feature with security annotations on server. ......... 234
19.3. Registering and configuring entity-filtering feature based on dynamic and configurable query
parameters. ..................................................................................................................... 235
19.4. Registering and configuring entity-filtering feature on client. ........................................... 235

xv

Jersey 2.28 User Guide

19.5. Project .................................................................................................................... 235
19.6. User ....................................................................................................................... 236
19.7. Task ...................................................................................................................... 236
19.8. ProjectsResource ...................................................................................................... 236
19.9. ProjectDetailedView ................................................................................................. 237
19.10. Annotated Project ................................................................................................... 238
19.11. Annotated User ...................................................................................................... 238
19.12. Annotated Task ...................................................................................................... 238
19.13. ProjectsResource - Response entity-filtering annotations ................................................ 240
19.14. ProjectsResource - Entity-filtering annotations on methods ............................................ 240
19.15. Client - Request entity-filtering annotations ................................................................. 241
19.16. Client - Request entity-filtering annotations ................................................................. 241
19.17. Sever - Query Parameter driven entity-filtering ............................................................ 243
19.18. ............................................................................................................................ 243
19.19. Entity-filtering annotation with custom meaning .......................................................... 243
19.20. Entity Data Filtering support in MOXy JSON binding provider ....................................... 244
20.1. Using Viewable in a resource class .......................................................................... 246
20.2. Using @Template on a resource method .................................................................... 247
20.3. Using @Template on a resource class ....................................................................... 247
20.4. Using absolute path to template in Viewable .............................................................. 249
20.5. Using @ErrorTemplate on a resource method .......................................................... 250
20.6. Using @ErrorTemplate with Bean Validation .......................................................... 250
20.7. Iterating through ValidationError in JSP .............................................................. 250
20.8. Registering MvcFeature ......................................................................................... 251
20.9. Registering FreemarkerMvcFeature ..................................................................... 251
20.10. Setting MvcFeature.TEMPLATE_BASE_PATH value in ResourceConfig ............... 251
20.11. Setting FreemarkerMvcProperties.TEMPLATE_BASE_PATH value in
web.xml ....................................................................................................................... 252
20.12. Including JSP page into JSP page ............................................................................. 255
20.13. Custom TemplateProcessor ...................................................................................... 256
20.14. Registering custom TemplateProcessor ....................................................................... 256
21.1. Logging on the client side ......................................................................................... 259
21.2. Register LoggingFeature via constructor ................................................................ 259
21.3. Register LoggingFeature class ............................................................................. 260
22.1. Application event listener .......................................................................................... 262
22.2. Request event listener ............................................................................................... 262
22.3. Event listener test resource ........................................................................................ 263
22.4. Injecting MonitoringStatistics ..................................................................................... 265
22.5. Summary level messages ........................................................................................... 273
22.6. On demand request, snippet of MVC JSP forwarding ..................................................... 273
24.1. Bootstrapping Jersey application with Weld support on Grizzly ........................................ 284
28.1. Jersey 1 reloader implementation ................................................................................ 317
28.2. Jersey 1 reloader registration ...................................................................................... 317
28.3. Jersey 2 reloader implementation ................................................................................ 317
28.4. Jersey 2 reloader registration ...................................................................................... 318
28.5. Initializing JAXB-based support with MOXy ................................................................ 321

xvi

Preface
This is user guide for Jersey 2.28. We are trying to keep it up to date as we add new features. When reading
the user guide, please consult also our Jersey API documentation [https://jersey.github.io/apidocs/2.28/
jersey/index.html] as an additional source of information about Jersey features and API.
If you would like to contribute to the guide or have questions on things not covered in our docs, please
contact us atusers@jersey.java.net [mailto:users@jersey.java.net]. Similarly, in case you spot any errors
in the Jersey documentation, please report them by filing a new issue in our Jersey JIRA Issue Tracker
[http://java.net/jira/browse/JERSEY] under docs component. Please make sure to specify the version of
the Jersey User Guide where the error has been spotted by selecting the proper value for the Affected
Version field.

Text formatting conventions
First mention of any Jersey and JAX-RS API component in a section links to the API documentation of
the referenced component. Any sub-sequent mentions of the component in the same chapter are rendered
using a monospaced font.
Emphasised font is used to a call attention to a newly introduce concept, when it first occurs in the text.
In some of the code listings, certain lines are too long to be displayed on one line for the available page
width. In such case, the lines that exceed the available page width are broken up into multiple lines using
a '\' at the end of each line to indicate that a break has been introduced to fit the line in the page. For
example:

This is an overly long line that \
might not fit the available page \
width and had to be broken into \
multiple lines.
This line fits the page width.

Should read as:

This is an overly long line that might not fit the available page width and had to
This line fits the page width.

xvii

Chapter 1. Getting Started
This chapter provides a quick introduction on how to get started building RESTful services using Jersey.
The example described here uses the lightweight Grizzly HTTP server. At the end of this chapter you will
see how to implement equivalent functionality as a JavaEE web application you can deploy on any servlet
container supporting Servlet 2.5 and higher.

1.1. Creating a New Project from Maven
Archetype
Jersey project is built using Apache Maven [http://maven.apache.org/] software project build and
management tool. All modules produced as part of Jersey project build are pushed to the Central Maven
Repository [http://search.maven.org/]. Therefore it is very convenient to work with Jersey for any Mavenbased project as all the released (non-SNAPSHOT) Jersey dependencies are readily available without a
need to configure a special maven repository to consume the Jersey modules.

Note
In case you want to depend on the latest SNAPSHOT versions of Jersey modules, the following
repository configuration needs to be added to your Maven project pom:

snapshot-repository.java.net
Java.net Snapshot Repository for Maven
https://maven.java.net/content/repositories/snapshots/
default

Since starting from a Maven project is the most convenient way for working with Jersey, let's now have
a look at this approach. We will now create a new Jersey project that runs on top of a Grizzly [http://
grizzly.java.net/] container. We will use a Jersey-provided maven archetype. To create the project, execute
the following Maven command in the directory where the new project should reside:
mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-grizzly2 \
-DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode=false \
-DgroupId=com.example -DartifactId=simple-service -Dpackage=com.example \
-DarchetypeVersion=2.28
Feel free to adjust the groupId, package and/or artifactId of your new project. Alternatively,
you can change it by updating the new project pom.xml once it gets generated.

1.2. Exploring the Newly Created Project
Once the project generation from a Jersey maven archetype is successfully finished, you should see the new
simple-service project directory created in your current location. The directory contains a standard
Maven project structure:
Project build and management configuration is described in the pom.xml located in the project root
directory.
Project sources are located under src/main/java.

1

Getting Started

Project test sources are located under src/test/java.
There are 2 classes in the project source directory in the com.example package. The Main class is
responsible for bootstrapping the Grizzly container as well as configuring and deploying the project's JAXRS application to the container. Another class in the same package is MyResource class, that contains
implementation of a simple JAX-RS resource. It looks like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

package com.example;
import
import
import
import

javax.ws.rs.GET;
javax.ws.rs.Path;
javax.ws.rs.Produces;
javax.ws.rs.core.MediaType;

/**
* Root resource (exposed at "myresource" path)
*/
@Path("myresource")
public class MyResource {
/**
* Method handling HTTP GET requests. The returned object will be sent
* to the client as "text/plain" media type.
*
* @return String that will be returned as a text/plain response.
*/
@GET
@Produces(MediaType.TEXT_PLAIN)
public String getIt() {
return "Got it!";
}
}

A JAX-RS resource is an annotated POJO that provides so-called resource methods that are able to handle
HTTP requests for URI paths that the resource is bound to. See Chapter 3, JAX-RS Application, Resources
and Sub-Resources for a complete guide to JAX-RS resources. In our case, the resource exposes a single
resource method that is able to handle HTTP GET requests, is bound to /myresource URI path and
can produce responses with response message content represented in "text/plain" media type. In this
version, the resource returns the same "Got it!" response to all client requests.
The last piece of code that has been generated in this skeleton project is a MyResourceTest unit test
class that is located in the same com.example package as the MyResource class, however, this unit
test class is placed into the maven project test source directory src/test/java (certain code comments
and JUnit imports have been excluded for brevity):
1
2
3
4
5
6
7
8
9
10
11

package com.example;
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.WebTarget;
import org.glassfish.grizzly.http.server.HttpServer;
...
public class MyResourceTest {

2

Getting Started

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37 }

private HttpServer server;
private WebTarget target;
@Before
public void setUp() throws Exception {
server = Main.startServer();
Client c = ClientBuilder.newClient();
target = c.target(Main.BASE_URI);
}
@After
public void tearDown() throws Exception {
server.stop();
}

/**
* Test to see that the message "Got it!" is sent in the response.
*/
@Test
public void testGetIt() {
String responseMsg = target.path("myresource").request().get(String.cla
assertEquals("Got it!", responseMsg);
}

In this unit test, a Grizzly container is first started and server application is deployed in the test setUp()
method by a static call to Main.startServer(). Next, a JAX-RS client components are created in
the same test set-up method. First a new JAX-RS client instance c is built and then a JAX-RS web target
component pointing to the context root of our application deployed at http://localhost:8080/
myapp/ (a value of Main.BASE_URI constant) is stored into a target field of the unit test class. This
field is then used in the actual unit test method (testGetIt()).
In the testGetIt() method a fluent JAX-RS Client API is used to connect to and send a HTTP GET
request to the MyResource JAX-RS resource class listening on /myresource URI. As part of the
same fluent JAX-RS API method invocation chain, a response is read as a Java String type. On the
second line in the test method, the response content string returned from the server is compared with
the expected phrase in the test assertion. To learn more about using JAX-RS Client API, please see the
Chapter 5, Client API chapter.

1.3. Running the Project
Now that we have seen the content of the project, let's try to test-run it. To do this, we need to invoke
following command on the command line:
mvn clean test
This will compile the project and run the project unit tests. We should see a similar output that informs
about a successful build once the build is finished:
Results :
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

3

Getting Started

[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]

-----------------------------------------------------------------------BUILD SUCCESS
-----------------------------------------------------------------------Total time: 34.527s
Finished at: Sun May 26 19:26:24 CEST 2013
Final Memory: 17M/490M
------------------------------------------------------------------------

Now that we have verified that the project compiles and that the unit test passes, we can execute the
application in a standalone mode. To do this, run the following maven command:
mvn exec:java
The application starts and you should soon see the following notification in your console:

May 26, 2013 8:08:45 PM org.glassfish.grizzly.http.server.NetworkListener start
INFO: Started listener bound to [localhost:8080]
May 26, 2013 8:08:45 PM org.glassfish.grizzly.http.server.HttpServer start
INFO: [HttpServer] Started.
Jersey app started with WADL available at http://localhost:8080/myapp/application.w
Hit enter to stop it...
This informs you that the application has been started and it's WADL descriptor is available at http://
localhost:8080/myapp/application.wadl URL. You can retrieve the WADL content by
executing a curl http://localhost:8080/myapp/application.wadl command in your
console or by typing the WADL URL into your favorite browser. You should get back an XML document
in describing your deployed RESTful application in a WADL format. To learn more about working with
WADL, check the Chapter 17, WADL Support chapter.
The last thing we should try before concluding this section is to see if we can communicate with our
resource deployed at /myresource path. We can again either type the resource URL in the browser
or we can use curl:
$ curl http://localhost:8080/myapp/myresource
Got it!
As we can see, the curl command returned with the Got it! message that was sent by our resource.
We can also ask curl to provide more information about the response, for example we can let it display
all response headers by using the -i switch:
curl -i http://localhost:8080/myapp/myresource
HTTP/1.1 200 OK
Content-Type: text/plain
Date: Sun, 26 May 2013 18:27:19 GMT
Content-Length: 7
Got it!
Here we see the whole content of the response message that our Jersey/JAX-RS application returned,
including all the HTTP headers. Notice the Content-Type: text/plain header that was
derived from the value of @Produces [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
Produces.html] annotation attached to the MyResource class.
In case you want to see even more details about the communication between our curl client and our
resource running on Jersey in a Grizzly I/O container, feel free to try other various options and switches

4

Getting Started

that curl provides. For example, this last command will make curl output a lot of additional information
about the whole communication:

$ curl -v http://localhost:8080/myapp/myresource
* About to connect() to localhost port 8080 (#0)
*
Trying ::1...
* Connection refused
*
Trying 127.0.0.1...
* connected
* Connected to localhost (127.0.0.1) port 8080 (#0)
> GET /myapp/myresource HTTP/1.1
> User-Agent: curl/7.25.0 (x86_64-apple-darwin11.3.0) libcurl/7.25.0 OpenSSL/1.0.1e
> Host: localhost:8080
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: text/plain
< Date: Sun, 26 May 2013 18:29:18 GMT
< Content-Length: 7
<
* Connection #0 to host localhost left intact
Got it!* Closing connection #0

1.4. Creating a JavaEE Web Application
To create a Web Application that can be packaged as WAR and deployed in a Servlet container follow
a similar process to the one described in Section 1.1, “Creating a New Project from Maven Archetype”.
In addition to the Grizzly-based archetype, Jersey provides also a Maven archetype for creating web
application skeletons. To create the new web application skeleton project, execute the following Maven
command in the directory where the new project should reside:

mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-webapp \
-DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMod
-DgroupId=com.example -DartifactId=simple-service-webapp -Dpackage=
-DarchetypeVersion=2.28
As with the Grizzly based project, feel free to adjust the groupId, package and/or artifactId of
your new web application project. Alternatively, you can change it by updating the new project pom.xml
once it gets generated.
Once the project generation from a Jersey maven archetype is successfully finished, you should see the new
simple-service-webapp project directory created in your current location. The directory contains a
standard Maven project structure, similar to the simple-service project content we have seen earlier,
except it is extended with an additional web application specific content:
Project build and management configuration is described in the pom.xml located in the project root
directory.
Project sources are located under src/main/java.
Project resources are located under src/main/resources.
Project web application files are located under src/main/webapp.
The project contains the same MyResouce JAX-RS resource class. It does not contain any unit tests as
well as it does not contain a Main class that was used to setup Grizzly container in the previous project.
Instead, it contains the standard Java EE web application web.xml deployment descriptor under src/
main/webapp/WEB-INF. The last component in the project is an index.jsp page that serves as a
client for the MyResource resource class that is packaged and deployed with the application.

5

Getting Started

To compile and package the application into a WAR, invoke the following maven command in your
console:
mvn clean package
A successful build output will produce an output similar to the one below:
Results :
Tests run: 0, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]

--- maven-war-plugin:2.1.1:war (default-war) @ simple-service-webapp --Packaging webapp
Assembling webapp [simple-service-webapp] in [.../simple-service-webapp/targ
Processing war project
Copying webapp resources [.../simple-service-webapp/src/main/webapp]
Webapp assembled in [75 msecs]
Building war: .../simple-service-webapp/target/simple-service-webapp.war
WEB-INF/web.xml already added, skipping
-----------------------------------------------------------------------BUILD SUCCESS
-----------------------------------------------------------------------Total time: 9.067s
Finished at: Sun May 26 21:07:44 CEST 2013
Final Memory: 17M/490M
------------------------------------------------------------------------

Now you are ready to take the packaged WAR (located under ./target/simple-servicewebapp.war) and deploy it to a Servlet container of your choice.

Important
To deploy a Jersey application, you will need a Servlet container that supports Servlet 2.5 or later.
For full set of advanced features (such as JAX-RS 2.0 Async Support) you will need a Servlet
3.0 or later compliant container.

1.5. Creating a Web Application that can be
deployed on Heroku
To create a Web Application that can be either packaged as WAR and deployed in a Servlet container or
that can be pushed and deployed on Heroku [https://www.heroku.com] the process is very similar to the
one described in Section 1.4, “Creating a JavaEE Web Application”. To create the new web application
skeleton project, execute the following Maven command in the directory where the new project should
reside:

mvn archetype:generate -DarchetypeArtifactId=jersey-heroku-webapp \
-DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMod
-DgroupId=com.example -DartifactId=simple-heroku-webapp -Dpackage=c
-DarchetypeVersion=2.28
Adjust the groupId, package and/or artifactId of your new web application project to your needs
or, alternatively, you can change it by updating the new project pom.xml once it gets generated.

6

Getting Started

Once the project generation from a Jersey maven archetype is successfully finished, you should see the new
simple-heroku-webapp project directory created in your current location. The directory contains a
standard Maven project structure:
Project build and management configuration is described in the pom.xml located in the project root
directory.
Project sources are located under src/main/java.
Project resources are located under src/main/resources.
Project web application files are located under src/main/webapp.
Project test-sources (based on JerseyTest [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/
test/JerseyTest.html]) are located under src/test/java.
Heroku system properties (OpenJDK version) are defined in system.properties.
Lists of the process types in an application for Heroku is in Procfile.
The project contains one JAX-RS resource class, MyResouce, and one resource method which returns
simple text message. To make sure the resource is properly tested there is also a end-to-end testcase in MyResourceTest (the test is based on JerseyTest [https://jersey.github.io/apidocs/2.28/jersey/
org/glassfish/jersey/test/JerseyTest.html] from our Chapter 26, Jersey Test Framework). Similarly to
simple-service-webapp, the project contains the standard Java EE web application web.xml
deployment descriptor under src/main/webapp/WEB-INF since the goal is to deploy the application
in a Servlet container (the application will run in Jetty on Heroku).
To compile and package the application into a WAR, invoke the following maven command in your
console:
mvn clean package
A successful build output will produce an output similar to the one below:
Results :
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]

--- maven-war-plugin:2.2:war (default-war) @ simple-heroku-webapp --Packaging webapp
Assembling webapp [simple-heroku-webapp] in [.../simple-heroku-webapp/ta
Processing war project
Copying webapp resources [.../simple-heroku-webapp/src/main/webapp]
Webapp assembled in [57 msecs]
Building war: .../simple-heroku-webapp/target/simple-heroku-webapp.war
WEB-INF/web.xml already added, skipping

--- maven-dependency-plugin:2.8:copy-dependencies (copy-dependencies) @
Copying hk2-locator-2.2.0-b21.jar to .../simple-heroku-webapp/target/dep
Copying jetty-security-9.0.6.v20130930.jar to .../simple-heroku-webapp/t
Copying asm-all-repackaged-2.2.0-b21.jar to .../simple-heroku-webapp/tar
Copying jersey-common-2.5.jar to .../simple-heroku-webapp/target/depende
Copying validation-api-1.1.0.Final.jar to .../simple-heroku-webapp/targe
Copying jetty-webapp-9.0.6.v20130930.jar to .../simple-heroku-webapp/tar
Copying jersey-container-servlet-2.5.jar to .../simple-heroku-webapp/tar
Copying cglib-2.2.0-b21.jar to .../simple-heroku-webapp/target/dependenc
Copying osgi-resource-locator-1.0.1.jar to .../simple-heroku-webapp/targ
Copying hk2-utils-2.2.0-b21.jar to .../simple-heroku-webapp/target/depen
Copying hk2-api-2.2.0-b21.jar to .../simple-heroku-webapp/target/depende
Copying jetty-io-9.0.6.v20130930.jar to .../simple-heroku-webapp/target/

7

Getting Started

[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]
[INFO]

Copying jetty-server-9.0.6.v20130930.jar to .../simple-heroku-webapp/tar
Copying jetty-util-9.0.6.v20130930.jar to .../simple-heroku-webapp/targe
Copying jersey-client-2.5.jar to .../simple-heroku-webapp/target/depende
Copying jetty-http-9.0.6.v20130930.jar to .../simple-heroku-webapp/targe
Copying guava-14.0.1.jar to .../simple-heroku-webapp/target/dependency/g
Copying jetty-xml-9.0.6.v20130930.jar to .../simple-heroku-webapp/target
Copying jersey-server-2.5.jar to .../simple-heroku-webapp/target/depende
Copying jersey-container-servlet-core-2.5.jar to .../simple-heroku-webap
Copying javax.ws.rs-api-2.0.jar to .../simple-heroku-webapp/target/depen
Copying jetty-servlet-9.0.6.v20130930.jar to .../simple-heroku-webapp/ta
Copying javax.inject-2.2.0-b21.jar to .../simple-heroku-webapp/target/de
Copying javax.servlet-3.0.0.v201112011016.jar to .../simple-heroku-webap
Copying javax.annotation-api-1.2.jar to .../simple-heroku-webapp/target/
-----------------------------------------------------------------------BUILD SUCCESS
-----------------------------------------------------------------------Total time: 4.401s
Finished at: Mon Dec 09 20:19:06 CET 2013
Final Memory: 20M/246M
------------------------------------------------------------------------

Now that you know everything went as expected you are ready to:
• make some changes in your project,
• take the packaged WAR (located under ./target/simple-service-webapp.war) and deploy
it to a Servlet container of your choice, or
• Section 1.5.1, “Deploy it on Heroku”

Tip
If you want to make some changes to your application you can run the application
locally by simply running mvn clean package jetty:run (which starts the
embedded Jetty server) or by java -cp target/classes:target/dependency/*
com.example.heroku.Main (this is how Jetty is started on Heroku).

1.5.1. Deploy it on Heroku
We won't go into details how to create an account on Heroku [https://www.heroku.com] and setup the
Heroku tools on your machine. You can find a lot of information in this article: Getting Started with Java
on Heroku [https://devcenter.heroku.com/articles/getting-started-with-java]. Instead, we'll take a look at
the steps needed after your environment is ready.
The first step is to create a Git repository from your project:
$ git init
Initialized empty Git repository in /.../simple-heroku-webapp/.git/
Then, create a Heroku [https://www.heroku.com] instance and add a remote reference to your Git
repository:

$ heroku create
Creating simple-heroku-webapp... done, stack is cedar
http://simple-heroku-webapp.herokuapp.com/ | git@heroku.com:simple-heroku-webap

8

Getting Started

Git remote heroku added

Note
The name of the instance is changed in the output to simple-heroku-webapp. Your will be
named more like tranquil-basin-4744.
Add and commit files to your Git repository:
$ git add src/ pom.xml Procfile system.properties
$ git commit -a -m "initial commit"
[master (root-commit) e2b58e3] initial commit
7 files changed, 221 insertions(+)
create mode 100644 Procfile
create mode 100644 pom.xml
create mode 100644 src/main/java/com/example/MyResource.java
create mode 100644 src/main/java/com/example/heroku/Main.java
create mode 100644 src/main/webapp/WEB-INF/web.xml
create mode 100644 src/test/java/com/example/MyResourceTest.java
create mode 100644 system.properties
Push changes to Heroku:
$ git push heroku master
Counting objects: 21, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (11/11), done.
Writing objects: 100% (21/21), 3.73 KiB | 0 bytes/s, done.
Total 21 (delta 0), reused 0 (delta 0)
----->
----->
----->
----->
----->

Java app detected
Installing OpenJDK 1.7... done
Installing Maven 3.0.3... done
Installing settings.xml... done
executing /app/tmp/cache/.maven/bin/mvn -B -Duser.home=/tmp/build_992cc7
[INFO] Scanning for projects...
[INFO]
[INFO] ----------------------------------------------------------------[INFO] Building simple-heroku-webapp 1.0-SNAPSHOT
[INFO] ----------------------------------------------------------------[INFO]
[INFO] --- maven-clean-plugin:2.4.1:clean (default-clean) @ simple-herok
[INFO]
[INFO] --- maven-resources-plugin:2.4.3:resources (default-resources) @
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] skip non existing resourceDirectory /tmp/build_992cc747-26d6-4800
[INFO]
[INFO] --- maven-compiler-plugin:2.5.1:compile (default-compile) @ simpl
[INFO] Compiling 2 source files to /tmp/build_992cc747-26d6-4800-bdb1-ad
[INFO]
[INFO] --- maven-resources-plugin:2.4.3:testResources (default-testResou
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] skip non existing resourceDirectory /tmp/build_992cc747-26d6-4800
[INFO]

9

Getting Started

[INFO] --- maven-compiler-plugin:2.5.1:testCompile (default-testCompile)
[INFO] Compiling 1 source file to /tmp/build_992cc747-26d6-4800-bdb1-add
[INFO]
[INFO] --- maven-surefire-plugin:2.7.2:test (default-test) @ simple-hero
[INFO] Tests are skipped.
[INFO]
[INFO] --- maven-war-plugin:2.1.1:war (default-war) @ simple-heroku-weba
[INFO] Packaging webapp
[INFO] Assembling webapp [simple-heroku-webapp] in [/tmp/build_992cc747[INFO] Processing war project
[INFO] Copying webapp resources [/tmp/build_992cc747-26d6-4800-bdb1-add4
[INFO] Webapp assembled in [88 msecs]
[INFO] Building war: /tmp/build_992cc747-26d6-4800-bdb1-add47b9583cd/tar
[INFO] WEB-INF/web.xml already added, skipping
[INFO]
[INFO] --- maven-dependency-plugin:2.1:copy-dependencies (copy-dependenc
[INFO] Copying guava-14.0.1.jar to /tmp/build_992cc747-26d6-4800-bdb1-ad
[INFO] Copying javax.annotation-api-1.2.jar to /tmp/build_992cc747-26d6[INFO] Copying validation-api-1.1.0.Final.jar to /tmp/build_992cc747-26d
[INFO] Copying javax.ws.rs-api-2.0.jar to /tmp/build_992cc747-26d6-4800[INFO] Copying jetty-http-9.0.6.v20130930.jar to /tmp/build_992cc747-26d
[INFO] Copying jetty-io-9.0.6.v20130930.jar to /tmp/build_992cc747-26d6[INFO] Copying jetty-security-9.0.6.v20130930.jar to /tmp/build_992cc747
[INFO] Copying jetty-server-9.0.6.v20130930.jar to /tmp/build_992cc747-2
[INFO] Copying jetty-servlet-9.0.6.v20130930.jar to /tmp/build_992cc747[INFO] Copying jetty-util-9.0.6.v20130930.jar to /tmp/build_992cc747-26d
[INFO] Copying jetty-webapp-9.0.6.v20130930.jar to /tmp/build_992cc747-2
[INFO] Copying jetty-xml-9.0.6.v20130930.jar to /tmp/build_992cc747-26d6
[INFO] Copying javax.servlet-3.0.0.v201112011016.jar to /tmp/build_992cc
[INFO] Copying hk2-api-2.2.0-b21.jar to /tmp/build_992cc747-26d6-4800-bd
[INFO] Copying hk2-locator-2.2.0-b21.jar to /tmp/build_992cc747-26d6-480
[INFO] Copying hk2-utils-2.2.0-b21.jar to /tmp/build_992cc747-26d6-4800[INFO] Copying osgi-resource-locator-1.0.1.jar to /tmp/build_992cc747-26
[INFO] Copying asm-all-repackaged-2.2.0-b21.jar to /tmp/build_992cc747-2
[INFO] Copying cglib-2.2.0-b21.jar to /tmp/build_992cc747-26d6-4800-bdb1
[INFO] Copying javax.inject-2.2.0-b21.jar to /tmp/build_992cc747-26d6-48
[INFO] Copying jersey-container-servlet-2.5.jar to /tmp/build_992cc747-2
[INFO] Copying jersey-container-servlet-core-2.5.jar to /tmp/build_992cc
[INFO] Copying jersey-client-2.5.jar to /tmp/build_992cc747-26d6-4800-bd
[INFO] Copying jersey-common-2.5.jar to /tmp/build_992cc747-26d6-4800-bd
[INFO] Copying jersey-server-2.5.jar to /tmp/build_992cc747-26d6-4800-bd
[INFO]
[INFO] --- maven-install-plugin:2.3.1:install (default-install) @ simple
[INFO] Installing /tmp/build_992cc747-26d6-4800-bdb1-add47b9583cd/target
[INFO] Installing /tmp/build_992cc747-26d6-4800-bdb1-add47b9583cd/pom.xm
[INFO] ----------------------------------------------------------------[INFO] BUILD SUCCESS
[INFO] ----------------------------------------------------------------[INFO] Total time: 45.861s
[INFO] Finished at: Mon Dec 09 19:51:34 UTC 2013
[INFO] Final Memory: 17M/514M
[INFO] ---------------------------------------------------------------------> Discovering process types
Procfile declares types -> web

10

Getting Started

-----> Compiled slug size: 75.9MB
-----> Launching... done, v6
http://simple-heroku-webapp.herokuapp.com deployed to Heroku
To git@heroku.com:simple-heroku-webapp.git
* [new branch]
master -> master
Now you can access your application at, for example: http://simple-heroku-webapp.herokuapp.com/
myresource

1.6. Exploring Other Jersey Examples
In the sections above, we have covered an approach how to get dirty with Jersey quickly. Please consult
the other sections of the Jersey User Guide to learn more about Jersey and JAX-RS. Even though we try
our best to cover as much as possible in the User Guide, there is always a chance that you would not be
able to get a full answer to the problem you are solving. In that case, consider diving in our examples that
provide additional tips and hints to the features you may want to use in your projects.
Jersey codebase contains a number of useful examples on how to use various JAX-RS and Jersey features.
Feel free to browse through the code of individual Jersey Examples [https://github.com/jersey/jersey/
tree/2.28/examples] in the Jersey source repository. For off-line browsing, you can also download a bundle
with all the examples from here [https://maven.java.net/content/repositories/releases/org/glassfish/jersey/
bundles/jersey-examples/2.28/].

11

Chapter 2. Modules and dependencies
2.1. Java SE Compatibility
2.x branch:
• Until version 2.6, Jersey was compiled with Java SE 6. This has changed in Jersey 2.7.
• Up to version 2.25.x almost all Jersey components are compiled with Java SE 7 target. It means, that
you will need at least Java SE 7 to be able to compile and run your application that is using latest Jersey.
Only core-common and core-client modules are still compiled with Java class version runnable
with Java SE 6.
• Since Jersey 2.26, all modules are build using Java SE 8 and there is no support for running it on older
Java SE distributions.

2.2. Introduction to Jersey dependencies
Jersey is built, assembled and installed using Apache Maven [http://maven.apache.org/]. Non-snapshot
Jersey releases are deployed to the Central Maven Repository [http://search.maven.org/]. Jersey is
also being deployed to Java.Net Maven repositories [http://maven.java.net/], which contain also Jersey
SNAPSHOT versions. In case you would want to test the latest development builds check out the Java.Net
Snapshots Maven repository [https://maven.java.net/content/repositories/snapshots/org/glassfish/jersey].
An application that uses Jersey and depends on Jersey modules is in turn required to also include in the
application dependencies the set of 3rd party modules that Jersey modules depend on. Jersey is designed
as a pluggable component architecture and different applications can therefore require different sets of
Jersey modules. This also means that the set of external Jersey dependencies required to be included in the
application dependencies may vary in each application based on the Jersey modules that are being used
by the application.
Developers using Maven or a Maven-aware build system in their projects are likely to find it easier to
include and manage dependencies of their applications compared to developers using ant or other build
systems that are not compatible with Maven. This document will explain to both maven and non-maven
developers how to depend on Jersey modules in their application. Ant developers are likely to find the Ant
Tasks for Maven [http://maven.apache.org/ant-tasks/index.html] very useful.

2.3. Common Jersey Use Cases
2.3.1. Servlet based application on Glassfish
If you are using Glassfish application server, you don't need to package anything with your application,
everything is already included. You just need to declare (provided) dependency on JAX-RS API to be able
to compile your application.

jakarta.ws.rs
jakarta.ws.rs-api
2.1.5
provided

If you are using any Jersey specific feature, you will need to depend on Jersey directly.

12

Modules and dependencies


org.glassfish.jersey.containers
jersey-container-servlet
2.28
provided



org.glassfish.jersey.core
jersey-client
2.28
provided


2.3.2. Servlet based server-side application
Following dependencies apply to application server (servlet containers) without any integrated JAX-RS
implementation. Then application needs to include JAX-RS API and Jersey implementation in deployed
application.


org.glassfish.jersey.containers


org.glassfish.jersey.core
jersey-client
2.28


2.3.3. Client application on JDK
Applications running on plain JDK using only client part of JAX-RS specification need to depend only
on client. There are various additional modules which can be added, like for example grizzly or apache
or jetty connector (see dependencies snipped below). Jersey client runs by default with plain JDK (using
HttpUrlConnection). See Chapter 5, Client API. for more details.

org.glassfish.jersey.core
jersey-client
2.28


Currently available connectors:

org.glassfish.jersey.connectors
jersey-grizzly-connector
2.28

13

Modules and dependencies



org.glassfish.jersey.connectors
jersey-apache-connector
2.28


org.glassfish.jersey.connectors
jersey-jetty-connector
2.28


2.3.4. Server-side application on supported containers
Apart for a standard JAX-RS Servlet-based deployment that works with any Servlet container that supports
Servlet 2.5 and higher, Jersey provides support for programmatic deployment to the following containers:
Grizzly 2 (HTTP and Servlet), JDK Http server, Simple Http server and Jetty Http server. This chapter
presents only required maven dependencies, more information can be found in Chapter 4, Application
Deployment and Runtime Environments.

org.glassfish.jersey.containers
jersey-container-grizzly2-http
2.28


org.glassfish.jersey.containers
jersey-container-grizzly2-servlet
2.28


org.glassfish.jersey.containers
jersey-container-jdk-http
2.28


org.glassfish.jersey.containers
jersey-container-simple-http
2.28


org.glassfish.jersey.containers
jersey-container-jetty-http
2.28


org.glassfish.jersey.containers

14

Modules and dependencies

jersey-container-jetty-servlet
2.28


2.4. List of modules
The following chapters provide an overview of all Jersey modules and their dependencies with links to the
respective binaries (follow a link on a module name to get complete set of downloadable dependencies).

Table 2.1. Jersey Core
Jersey Core
jersey-client [https://
jersey.github.io/
project-info/2.28/
jersey/jersey-client/
dependencies.html]

Jersey core client implementation

jersey-common
Jersey core common packages
[https://jersey.github.io/
project-info/2.28/
jersey/jersey-common/
dependencies.html]
jersey-server [https://
jersey.github.io/
project-info/2.28/
jersey/jersey-server/
dependencies.html]

Jersey core server implementation

Table 2.2. Jersey Containers
Jersey Containers
jersey-containerGrizzly 2 Http Container.
grizzly2-http [https://
jersey.github.io/
project-info/2.28/
jersey/project/jerseycontainer-grizzly2-http/
dependencies.html]
jersey-containerGrizzly 2 Servlet Container.
grizzly2-servlet
[https://jersey.github.io/
project-info/2.28/jersey/
project/jersey-containergrizzly2-servlet/
dependencies.html]
jersey-containerJDK Http Container
jdk-http [https://
jersey.github.io/projectinfo/2.28/jersey/project/
jersey-container-jdkhttp/dependencies.html]

15

Modules and dependencies

Jersey Containers
jersey-containerJetty Http Container
jetty-http [https://
jersey.github.io/projectinfo/2.28/jersey/project/
jersey-container-jettyhttp/dependencies.html]
jersey-containerjetty-servlet [https://
jersey.github.io/
project-info/2.28/
jersey/project/jerseycontainer-jetty-servlet/
dependencies.html]

Jetty Servlet Container

jersey-containerNetty Http Container.
netty-http [https://
jersey.github.io/projectinfo/2.28/jersey/project/
jersey-container-nettyhttp/dependencies.html]
jersey-container-servlet Jersey core Servlet 3.x implementation
[https://jersey.github.io/
project-info/2.28/
jersey/project/jerseycontainer-servlet/
dependencies.html]
jersey-containerJersey core Servlet 2.x implementation
servlet-core [https://
jersey.github.io/projectinfo/2.28/jersey/project/
jersey-container-servletcore/dependencies.html]
jersey-containerSimple Http Container
simple-http [https://
jersey.github.io/projectinfo/2.28/jersey/project/
jersey-container-simplehttp/dependencies.html]
jersey-gf-ejb [https://
Jersey EJB for GlassFish integration
jersey.github.io/projectinfo/2.28/jersey/project/
project/jersey-gf-ejb/
dependencies.html]

Table 2.3. Jersey Connectors
Jersey Connectors
jersey-apacheconnector [https://
jersey.github.io/
project-info/2.28/

Jersey Client Transport via Apache

16

Modules and dependencies

Jersey Connectors
jersey/project/jerseyapache-connector/
dependencies.html]
jersey-grizzlyconnector [https://
jersey.github.io/
project-info/2.28/
jersey/project/jerseygrizzly-connector/
dependencies.html]

Jersey Client Transport via Grizzly

jersey-jdk-connector
Jersey Client Transport via JDK connector
[https://jersey.github.io/
project-info/2.28/
jersey/project/jerseyjdk-connector/
dependencies.html]
jersey-jetty-connector
Jersey Client Transport via Jetty
[https://jersey.github.io/
project-info/2.28/
jersey/project/jerseyjetty-connector/
dependencies.html]
jersey-netty-connector Jersey Client Transport via Netty
[https://jersey.github.io/
project-info/2.28/
jersey/project/jerseynetty-connector/
dependencies.html]

Table 2.4. Jersey Media
Jersey Media
jersey-media-jaxb
JAX-RS features based upon JAX-B.
[https://jersey.github.io/
project-info/2.28/jersey/
project/jersey-mediajaxb/dependencies.html]
jersey-media-jsonbinding [https://
jersey.github.io/
project-info/2.28/
jersey/project/jerseymedia-json-binding/
dependencies.html]

Jersey JSON-B support module.

jersey-media-jsonjackson [https://
jersey.github.io/
project-info/2.28/
jersey/project/jersey-

Jersey JSON Jackson (2.x) entity providers support module.

17

Modules and dependencies

Jersey Media
media-json-jackson/
dependencies.html]
jersey-media-jsonjackson1 [https://
jersey.github.io/
project-info/2.28/
jersey/project/jerseymedia-json-jackson1/
dependencies.html]

Jersey JSON Jackson (1.x) entity providers support module.

jersey-media-jsonjettison [https://
jersey.github.io/
project-info/2.28/
jersey/project/jerseymedia-json-jettison/
dependencies.html]

Jersey JSON Jettison entity providers support module.

jersey-media-jsonJersey JSON-P (JSR 353) entity providers support proxy module.
processing [https://
jersey.github.io/
project-info/2.28/
jersey/project/jerseymedia-json-processing/
dependencies.html]
jersey-media-kryo
Jersey/JAX-RS Message Body Writer and Reader using Kryo serialization framework
[https://jersey.github.io/
project-info/2.28/
jersey/project/
jersey-media-kryo/
dependencies.html]
jersey-media-moxy
Jersey JSON entity providers support module based on EclipseLink MOXy.
[https://jersey.github.io/
project-info/2.28/
jersey/project/
jersey-media-moxy/
dependencies.html]
jersey-media-multipart Jersey Multipart entity providers support module.
[https://jersey.github.io/
project-info/2.28/
jersey/project/jerseymedia-multipart/
dependencies.html]
jersey-media-sse
Jersey Server Sent Events entity providers support module.
[https://jersey.github.io/
project-info/2.28/jersey/
project/jersey-mediasse/dependencies.html]

18

Modules and dependencies

Table 2.5. Jersey Extensions
Jersey Extensions
jersey-bean-validation Jersey extension module providing support for Bean Validation (JSR-349) API.
[https://jersey.github.io/
project-info/2.28/
jersey/project/jerseybean-validation/
dependencies.html]
jersey-cdi1x [https://
Jersey CDI 1.1 integration
jersey.github.io/projectinfo/2.28/jersey/project/
project/jersey-cdi1x/
dependencies.html]
jersey-cdi1x-banJersey CDI integration - this module disables custom HK2 bindings
custom-hk2-binding
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-cdi1x-bancustom-hk2-binding/
dependencies.html]
jersey-cdi1x-servlet
Jersey CDI 1.x Servlet Support
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-cdi1x-servlet/
dependencies.html]
jersey-cdi1xJersey CDI 1.x Transactional Support
transaction [https://
jersey.github.io/projectinfo/2.28/jersey/
project/project/jerseycdi1x-transaction/
dependencies.html]
jersey-cdi1x-validation Jersey CDI 1.x Bean Validation Support
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-cdi1x-validation/
dependencies.html]
jersey-declarativelinking [https://
jersey.github.io/
project-info/2.28/
jersey/project/jerseydeclarative-linking/
dependencies.html]

Jersey support for declarative hyperlinking.

jersey-entity-filtering
Jersey extension module providing support for Entity Data Filtering.
[https://jersey.github.io/
project-info/2.28/

19

Modules and dependencies

Jersey Extensions
jersey/project/jerseyentity-filtering/
dependencies.html]
jersey-metainf-services Jersey extension module enabling automatic registration of JAX-RS providers (MBW/
[https://jersey.github.io/ MBR/EM) via META-INF/services mechanism.
project-info/2.28/
jersey/project/jerseymetainf-services/
dependencies.html]
jersey-mvc [https://
Jersey extension module providing support for MVC.
jersey.github.io/projectinfo/2.28/jersey/
project/jersey-mvc/
dependencies.html]
jersey-mvc-beanvalidation [https://
jersey.github.io/
project-info/2.28/
jersey/project/jerseymvc-bean-validation/
dependencies.html]

Jersey extension module providing support for Bean Validation in MVC.

jersey-mvc-freemarker Jersey extension module providing support for Freemarker templates.
[https://jersey.github.io/
project-info/2.28/
jersey/project/jerseymvc-freemarker/
dependencies.html]
jersey-mvc-jsp [https:// Jersey extension module providing support for JSP templates.
jersey.github.io/projectinfo/2.28/jersey/
project/jersey-mvc-jsp/
dependencies.html]
jersey-mvc-mustache
Jersey extension module providing support for Mustache templates.
[https://jersey.github.io/
project-info/2.28/
jersey/project/jerseymvc-mustache/
dependencies.html]
jersey-proxy-client
Jersey extension module providing support for (proxy-based) high-level client API.
[https://jersey.github.io/
project-info/2.28/
jersey/project/
jersey-proxy-client/
dependencies.html]
jersey-rx-client-guava Jersey Reactive Client - Guava (ListenableFuture) provider.
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/

20

Modules and dependencies

Jersey Extensions
jersey-rx-client-guava/
dependencies.html]
jersey-rx-client-rxjava Jersey Reactive Client - RxJava (Observable) provider.
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-rx-client-rxjava/
dependencies.html]
jersey-rx-client-rxjava2 Jersey Reactive Client - RxJava2 (Flowable) provider.
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-rx-client-rxjava2/
dependencies.html]
jersey-servletportability [https://
jersey.github.io/
project-info/2.28/
jersey/project/jerseyservlet-portability/
dependencies.html]

Library that enables writing web applications that run with both Jersey 1.x and Jersey 2.x
servlet containers.

jersey-spring4 [https:// Jersey extension module providing support for Spring 4 integration.
jersey.github.io/projectinfo/2.28/jersey/
project/jersey-spring4/
dependencies.html]
jersey-wadl-doclet
A doclet that generates a resourcedoc xml file: this file contains the javadoc
[https://jersey.github.io/ documentation of resource classes, so that this can be used for extending generated wadl
project-info/2.28/
with useful documentation.
jersey/project/
jersey-wadl-doclet/
dependencies.html]
jersey-weld2-se
WELD 2.x SE support
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-weld2-se/
dependencies.html]

Table 2.6. Jersey Test Framework
Jersey Test Framework
container-runnerThe container runner maven plugin provides means to start and stop a container
maven-plugin [https:// (currently, Weblogic, Tomcat and Glassfish4 are supported). To deploy an application to
jersey.github.io/project- this container or to repetitively redeploy and test an application in the container.
info/2.28/jersey/project/
project/containerrunner-maven-plugin/
dependencies.html]

21

Modules and dependencies

Jersey Test Framework
custom-enforcer-rules Jersey test framework Maven projects
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
custom-enforcer-rules/
dependencies.html]
jersey-test-framework- Jersey Test Framework Core
core [https://
jersey.github.io/projectinfo/2.28/jersey/project/
jersey-test-frameworkcore/dependencies.html]
jersey-test-framework- Jersey Test Framework Providers Bundle
provider-bundle
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-bundle/
dependencies.html]
jersey-test-framework- Jersey Test Framework - External container
provider-external
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-external/
dependencies.html]
jersey-test-framework- Jersey Test Framework - Grizzly2 container
provider-grizzly2
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-grizzly2/
dependencies.html]
jersey-test-framework- Jersey Test Framework - InMemory container
provider-inmemory
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-inmemory/
dependencies.html]
jersey-test-framework- Jersey Test Framework - JDK HTTP container
provider-jdk-http
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-framework-

22

Modules and dependencies

Jersey Test Framework
provider-jdk-http/
dependencies.html]
jersey-test-frameworkprovider-jetty [https://
jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-jetty/
dependencies.html]

Jersey Test Framework - Jetty HTTP container

jersey-test-framework- Jersey Test Framework - Netty container
provider-netty [https://
jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-netty/
dependencies.html]
jersey-test-framework- Jersey Test Framework - Simple HTTP container
provider-simple
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-simple/
dependencies.html]
jersey-test-framework- Jersey Test Framework Utils
util [https://
jersey.github.io/projectinfo/2.28/jersey/project/
jersey-test-frameworkutil/dependencies.html]
memleak-testJersey test framework umbrella project
common [https://
jersey.github.io/projectinfo/2.28/jersey/project/
memleak-test-common/
dependencies.html]

Table 2.7. Jersey Test Framework Providers
Jersey Test Framework Providers
jersey-test-framework- Jersey Test Framework Providers Bundle
provider-bundle
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-bundle/
dependencies.html]

23

Modules and dependencies

Jersey Test Framework Providers
jersey-test-framework- Jersey Test Framework - External container
provider-external
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-external/
dependencies.html]
jersey-test-framework- Jersey Test Framework - Grizzly2 container
provider-grizzly2
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-grizzly2/
dependencies.html]
jersey-test-framework- Jersey Test Framework - InMemory container
provider-inmemory
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-inmemory/
dependencies.html]
jersey-test-framework- Jersey Test Framework - JDK HTTP container
provider-jdk-http
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-jdk-http/
dependencies.html]
jersey-test-frameworkprovider-jetty [https://
jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-jetty/
dependencies.html]

Jersey Test Framework - Jetty HTTP container

jersey-test-framework- Jersey Test Framework - Netty container
provider-netty [https://
jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-netty/
dependencies.html]
jersey-test-frameworkprovider-simple

Jersey Test Framework - Simple HTTP container

24

Modules and dependencies

Jersey Test Framework Providers
[https://jersey.github.io/
project-info/2.28/
jersey/project/project/
jersey-test-frameworkprovider-simple/
dependencies.html]

Table 2.8. Jersey Glassfish Bundles
Jersey Glassfish Bundles
jersey-gf-ejb [https://
Jersey EJB for GlassFish integration
jersey.github.io/projectinfo/2.28/jersey/project/
project/jersey-gf-ejb/
dependencies.html]

Table 2.9. Security
Security
oauth1-client [https:// Module that adds an OAuth 1 support to Jersey client.
jersey.github.io/projectinfo/2.28/jersey/
project/oauth1-client/
dependencies.html]
oauth1-server [https:// Module that adds an OAuth 1 support to Jersey server
jersey.github.io/projectinfo/2.28/jersey/
project/oauth1-server/
dependencies.html]
oauth1-signature
OAuth1 signature module
[https://jersey.github.io/
project-info/2.28/
jersey/project/
oauth1-signature/
dependencies.html]
oauth2-client [https:// Module that adds an OAuth 2 support to Jersey client
jersey.github.io/projectinfo/2.28/jersey/
project/oauth2-client/
dependencies.html]

Table 2.10. Jersey Examples
Jersey Examples
additional-bundle
OSGi Helloworld Webapp - additional bundle
[https://jersey.github.io/
project-info/2.28/
jersey/project/osgihelloworld-webapp/

25

Modules and dependencies

Jersey Examples
additional-bundle/
dependencies.html]
alternate-versionOSGi Helloworld Webapp - alternate version bundle
bundle [https://
jersey.github.io/projectinfo/2.28/jersey/project/
osgi-helloworldwebapp/alternateversion-bundle/
dependencies.html]
assemblies [https://
Jersey examples shared assembly types.
jersey.github.io/projectinfo/2.28/jersey/
project/assemblies/
dependencies.html]
bean-validationwebapp [https://
jersey.github.io/
project-info/2.28/
jersey/project/webappexample-parent/beanvalidation-webapp/
dependencies.html]

Jersey Bean Validation (JSR-349) example.

bookmark [https://
Jersey Bookmark example.
jersey.github.io/projectinfo/2.28/jersey/project/
webapp-exampleparent/bookmark/
dependencies.html]
bookmark-em [https:// Jersey Bookmark example using EntityManager.
jersey.github.io/projectinfo/2.28/jersey/project/
webapp-exampleparent/bookmark-em/
dependencies.html]
bookstore-webapp
Jersey MVC Bookstore example.
[https://jersey.github.io/
project-info/2.28/
jersey/project/webappexample-parent/
bookstore-webapp/
dependencies.html]
bundle [https://
jersey.github.io/
project-info/2.28/
jersey/project/osgihttp-service/bundle/
dependencies.html]

OSGi HttpService example bundle

26

Modules and dependencies

Jersey Examples
cdi-webapp [https://
Jersey CDI example.
jersey.github.io/projectinfo/2.28/jersey/project/
webapp-exampleparent/cdi-webapp/
dependencies.html]
clipboard [https://
Jersey clipboard example.
jersey.github.io/projectinfo/2.28/jersey/
project/clipboard/
dependencies.html]
clipboardJersey programmatic resource API clipboard example.
programmatic [https://
jersey.github.io/projectinfo/2.28/jersey/
project/clipboardprogrammatic/
dependencies.html]
declarative-linking
Declarative Hyperlinking - Jersey Sample
[https://jersey.github.io/
project-info/2.28/
jersey/project/
declarative-linking/
dependencies.html]
entity-filtering [https:// Jersey Entity Data Filtering Example.
jersey.github.io/projectinfo/2.28/jersey/
project/entity-filtering/
dependencies.html]
entity-filtering-security Jersey Entity Data Filtering Security Example.
[https://jersey.github.io/
project-info/2.28/
jersey/project/entityfiltering-security/
dependencies.html]
entity-filteringselectable [https://
jersey.github.io/
project-info/2.28/
jersey/project/entityfiltering-selectable/
dependencies.html]

Jersey Entity Data Filtering Selectable Example.

exception-mapping
Jersey example showing exception mappers in action.
[https://jersey.github.io/
project-info/2.28/
jersey/project/
exception-mapping/
dependencies.html]

27

Modules and dependencies

Jersey Examples
extended-wadl-webapp Extended WADL example.
[https://jersey.github.io/
project-info/2.28/
jersey/project/webappexample-parent/
extended-wadl-webapp/
dependencies.html]
feed-combiner-java8Jersey Web Application (Servlet) examples parent POM.
webapp [https://
jersey.github.io/projectinfo/2.28/jersey/project/
webapp-exampleparent/feed-combinerjava8-webapp/
dependencies.html]
flight-managementwebapp [https://
jersey.github.io/
project-info/2.28/
jersey/project/webappexample-parent/flightmanagement-webapp/
dependencies.html]

Jersey Flight Management Demo Web Application Example

freemarker-webapp
Jersey Freemarker example.
[https://jersey.github.io/
project-info/2.28/
jersey/project/webappexample-parent/
freemarker-webapp/
dependencies.html]
functional-test [https:// Jersey examples
jersey.github.io/projectinfo/2.28/jersey/project/
osgi-helloworldwebapp/functional-test/
dependencies.html]
functional-test [https:// OSGi HttpService example
jersey.github.io/projectinfo/2.28/jersey/
project/osgi-httpservice/functional-test/
dependencies.html]
groovy [https://
jersey.github.io/
project-info/2.28/
jersey/project/groovy/
dependencies.html]

Groovy Jersey

helloworld [https://
Jersey annotated resource class "Hello world" example.
jersey.github.io/project-

28

Modules and dependencies

Jersey Examples
info/2.28/jersey/
project/helloworld/
dependencies.html]
helloworld-benchmark Jersey "Hello World" benchmark example.
[https://jersey.github.io/
project-info/2.28/
jersey/project/
helloworld-benchmark/
dependencies.html]
helloworld-cdi2-se
Jersey "Hello world" example with CDI 2 SE.
[https://jersey.github.io/
project-info/2.28/jersey/
project/helloworld-cdi2se/dependencies.html]
helloworld-netty
Jersey "Hello world" example on Netty container.
[https://jersey.github.io/
project-info/2.28/
jersey/project/
helloworld-netty/
dependencies.html]
helloworldJersey programmatic resource API "Hello world" example.
programmatic [https://
jersey.github.io/projectinfo/2.28/jersey/
project/helloworldprogrammatic/
dependencies.html]
helloworld-pureExample using only the standard JAX-RS API's and the lightweight HTTP server
jax-rs [https://
bundled in JDK.
jersey.github.io/projectinfo/2.28/jersey/project/
helloworld-pure-jax-rs/
dependencies.html]
helloworld-springSpring 4 Integration Jersey Example
annotations [https://
jersey.github.io/projectinfo/2.28/jersey/
project/helloworldspring-annotations/
dependencies.html]
helloworld-springSpring 4 Integration Jersey Example
webapp [https://
jersey.github.io/projectinfo/2.28/jersey/
project/helloworldspring-webapp/
dependencies.html]
helloworld-webapp
Jersey annotated resource class "Hello world" example.
[https://jersey.github.io/

29

Modules and dependencies

Jersey Examples
project-info/2.28/
jersey/project/webappexample-parent/
helloworld-webapp/
dependencies.html]
helloworld-weld
Jersey annotated resource class "Hello world" example with Weld support.
[https://jersey.github.io/
project-info/2.28/
jersey/project/
helloworld-weld/
dependencies.html]
http-patch [https://
Jersey example for implementing generic PATCH support via JAX-RS reader interceptor.
jersey.github.io/project- Taken from Gerard Davison's blog entry: http://kingsfleet.blogspot.co.uk/2014/02/
info/2.28/jersey/
transparent-patch-support-in-jax-rs-20.html
project/http-patch/
dependencies.html]
http-trace [https://
Jersey HTTP TRACE support example.
jersey.github.io/projectinfo/2.28/jersey/
project/http-trace/
dependencies.html]
https-clientservergrizzly [https://
jersey.github.io/
project-info/2.28/
jersey/project/httpsclientserver-grizzly/
dependencies.html]

Jersey HTTPS Client/Server example on Grizzly.

https-server-glassfish
Jersey HTTPS server on GlassFish example.
[https://jersey.github.io/
project-info/2.28/
jersey/project/webappexample-parent/httpsserver-glassfish/
dependencies.html]
java8-webapp [https:// Java 8 Types WebApp Example.
jersey.github.io/projectinfo/2.28/jersey/project/
webapp-exampleparent/java8-webapp/
dependencies.html]
jaxb [https://
Jersey JAXB example.
jersey.github.io/projectinfo/2.28/jersey/project/
jaxb/dependencies.html]
jaxrs-types-injection
Jersey JAX-RS types injection example.
[https://jersey.github.io/
project-info/2.28/
jersey/project/jaxrs-

30

Modules and dependencies

Jersey Examples
types-injection/
dependencies.html]
jersey-ejb [https://
Jersey Web Application (Servlet) examples parent POM.
jersey.github.io/projectinfo/2.28/jersey/project/
webapp-exampleparent/jersey-ejb/
dependencies.html]
json-binding-webapp
Jersey JSON Binding example.
[https://jersey.github.io/
project-info/2.28/
jersey/project/jsonbinding-webapp/
dependencies.html]
json-jackson [https://
Jersey JSON with Jackson example.
jersey.github.io/projectinfo/2.28/jersey/
project/json-jackson/
dependencies.html]
json-jackson1 [https:// Jersey JSON with Jackson 1.x example.
jersey.github.io/projectinfo/2.28/jersey/
project/json-jackson1/
dependencies.html]
json-jettison [https://
Jersey JSON with Jettison JAXB example.
jersey.github.io/projectinfo/2.28/jersey/
project/json-jettison/
dependencies.html]
json-moxy [https://
Jersey JSON with MOXy example.
jersey.github.io/projectinfo/2.28/jersey/
project/json-moxy/
dependencies.html]
json-processingwebapp [https://
jersey.github.io/
project-info/2.28/
jersey/project/webappexample-parent/jsonprocessing-webapp/
dependencies.html]

Jersey JSON-P (JSR 353) example.

json-with-padding
Jersey JSON with Padding example.
[https://jersey.github.io/
project-info/2.28/
jersey/project/
json-with-padding/
dependencies.html]

31

Modules and dependencies

Jersey Examples
lib-bundle [https://
OSGi Helloworld Webapp - lib bundle
jersey.github.io/projectinfo/2.28/jersey/project/
osgi-helloworldwebapp/lib-bundle/
dependencies.html]
managed-beansJersey Managed Beans Web Application Example.
webapp [https://
jersey.github.io/projectinfo/2.28/jersey/project/
webapp-exampleparent/managedbeans-webapp/
dependencies.html]
managed-client
Jersey managed client example.
[https://jersey.github.io/
project-info/2.28/jersey/
project/managed-client/
dependencies.html]
managed-clientJersey Web Application (Servlet) examples parent POM.
simple-webapp [https://
jersey.github.io/projectinfo/2.28/jersey/project/
webapp-exampleparent/managedclient-simple-webapp/
dependencies.html]
managed-clientJersey managed client web application example.
webapp [https://
jersey.github.io/projectinfo/2.28/jersey/project/
webapp-exampleparent/managedclient-webapp/
dependencies.html]
monitoring-webapp
Jersey Web Application (Servlet) examples parent POM.
[https://jersey.github.io/
project-info/2.28/
jersey/project/webappexample-parent/
monitoring-webapp/
dependencies.html]
multipart-webapp
Jersey Multipart example.
[https://jersey.github.io/
project-info/2.28/
jersey/project/webappexample-parent/
multipart-webapp/
dependencies.html]

32

Modules and dependencies

Jersey Examples
oauth-client-twitter
Twitter client using OAuth 1 support for Jersey that retrieves Tweets from the home
[https://jersey.github.io/ timeline of a registered Twitter account.
project-info/2.28/
jersey/project/
oauth-client-twitter/
dependencies.html]
oauth2-client-googlewebapp [https://
jersey.github.io/
project-info/2.28/
jersey/project/oauth2client-google-webapp/
dependencies.html]

Google API data retrieving example using OAuth2 for authentication and authorization

open-tracing [https://
Jersey OpenTracing example
jersey.github.io/projectinfo/2.28/jersey/
project/open-tracing/
dependencies.html]
osgi-helloworldwebapp [https://
jersey.github.io/
project-info/2.28/
jersey/project/osgihelloworld-webapp/
dependencies.html]

Jersey examples

osgi-http-service
OSGi HttpService example
[https://jersey.github.io/
project-info/2.28/
jersey/project/
osgi-http-service/
dependencies.html]
reload [https://
jersey.github.io/
project-info/2.28/
jersey/project/reload/
dependencies.html]

Jersey resource configuration reload example.

rx-client-webapp
Jersey Reactive Client WebApp Example.
[https://jersey.github.io/
project-info/2.28/
jersey/project/webappexample-parent/
rx-client-webapp/
dependencies.html]
server-async [https://
Jersey JAX-RS asynchronous server-side example.
jersey.github.io/projectinfo/2.28/jersey/
project/server-async/
dependencies.html]

33

Modules and dependencies

Jersey Examples
server-async-managed Jersey JAX-RS asynchronous server-side example with custom Jersey executor providers.
[https://jersey.github.io/
project-info/2.28/
jersey/project/serverasync-managed/
dependencies.html]
server-asyncstandalone [https://
jersey.github.io/
project-info/2.28/
jersey/project/serverasync-standalone/
dependencies.html]

Standalone Jersey JAX-RS asynchronous server-side processing example.

server-asyncStandalone Jersey JAX-RS asynchronous server-side processing example client.
standalone-client
[https://jersey.github.io/
project-info/2.28/jersey/
project/server-asyncstandalone/serverasync-standalone-client/
dependencies.html]
server-asyncStandalone Jersey JAX-RS asynchronous server-side processing example web
standalone-webapp
application.
[https://jersey.github.io/
project-info/2.28/
jersey/project/serverasync-standalone/
server-asyncstandalone-webapp/
dependencies.html]
server-sent-events-jaxrs Jersey JAX-RS 2.1 Server-Sent Events example.
[https://jersey.github.io/
project-info/2.28/
jersey/project/serversent-events-jaxrs/
dependencies.html]
server-sent-eventsjersey [https://
jersey.github.io/
project-info/2.28/
jersey/project/serversent-events-jersey/
dependencies.html]

Jersey Server-Sent Events example.

servlet3-webapp
Jersey Servlet 3 example with missing servlet-class in the web.xml file
[https://jersey.github.io/
project-info/2.28/
jersey/project/webappexample-parent/
servlet3-webapp/
dependencies.html]

34

Modules and dependencies

Jersey Examples
shortener-webapp
Jersey Shortener Webapp (MVC + Bean Validation).
[https://jersey.github.io/
project-info/2.28/
jersey/project/webappexample-parent/
shortener-webapp/
dependencies.html]
simple-console
Jersey Simple Console example
[https://jersey.github.io/
project-info/2.28/jersey/
project/simple-console/
dependencies.html]
sparklines [https://
Jersey examples
jersey.github.io/projectinfo/2.28/jersey/
project/sparklines/
dependencies.html]
sse-item-store-jaxrsJersey JAX-RS 2.1 SSE API-based item store example.
webapp [https://
jersey.github.io/projectinfo/2.28/jersey/project/
webapp-exampleparent/sse-itemstore-jaxrs-webapp/
dependencies.html]
sse-item-store-jerseyJersey SSE API-based item store example.
webapp [https://
jersey.github.io/projectinfo/2.28/jersey/project/
webapp-exampleparent/sse-itemstore-jersey-webapp/
dependencies.html]
sse-twitter-aggregator
Jersey SSE Twitter Message Aggregator Example.
[https://jersey.github.io/
project-info/2.28/
jersey/project/ssetwitter-aggregator/
dependencies.html]
system-propertiesexample [https://
jersey.github.io/
project-info/2.28/
jersey/project/systemproperties-example/
dependencies.html]

Jersey system properties example.

tone-generator [https:// Jersey examples
jersey.github.io/projectinfo/2.28/jersey/

35

Modules and dependencies

Jersey Examples
project/tone-generator/
dependencies.html]
war-bundle [https://
OSGi Helloworld Webapp WAR bundle
jersey.github.io/projectinfo/2.28/jersey/project/
osgi-helloworldwebapp/war-bundle/
dependencies.html]
webapp-exampleparent [https://
jersey.github.io/
project-info/2.28/
jersey/project/webappexample-parent/
dependencies.html]

Jersey Web Application (Servlet) examples parent POM.

xml-moxy [https://
Jersey XML MOXy example.
jersey.github.io/projectinfo/2.28/jersey/
project/xml-moxy/
dependencies.html]

36

Chapter 3. JAX-RS Application,
Resources and Sub-Resources
This chapter presents an overview of the core JAX-RS concepts - resources and sub-resources.
The JAX-RS 2.1.5 JavaDoc can be found online here [http://jax-rs-spec.java.net/nonav/2.1.5/apidocs/
index.html].
The JAX-RS 2.1.5 specification draft can be found online here [http://jcp.org/en/jsr/summary?id=339].

3.1. Root Resource Classes
Root resource classes are POJOs (Plain Old Java Objects) that are annotated with @Path [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Path.html] have at least one method annotated
with @Path [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Path.html] or a resource
method designator annotation such as @GET [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/
ws/rs/GET.html], @PUT [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/PUT.html],
@POST [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/POST.html], @DELETE [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/DELETE.html]. Resource methods are methods of
a resource class annotated with a resource method designator. This section shows how to use Jersey to
annotate Java objects to create RESTful web services.
The following code example is a very simple example of a root resource class using JAX-RS annotations.
The example code shown here is from one of the samples that ships with Jersey, the zip file of which can
be found in the maven repository here [https://maven.java.net/content/repositories/releases/org/glassfish/
jersey/examples/helloworld/2.28/].

Example 3.1. Simple hello world root resource class
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

package org.glassfish.jersey.examples.helloworld;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
@Path("helloworld")
public class HelloWorldResource {
public static final String CLICHED_MESSAGE = "Hello World!";
@GET
@Produces("text/plain")
public String getHello() {
return CLICHED_MESSAGE;
}
}

Let's look at some of the JAX-RS annotations used in this example.

3.1.1. @Path
The @Path [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Path.html] annotation's value is
a relative URI path. In the example above, the Java class will be hosted at the URI path /helloworld.

37

JAX-RS Application,
Resources and Sub-Resources
This is an extremely simple use of the @Path [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/
rs/Path.html] annotation. What makes JAX-RS so useful is that you can embed variables in the URIs.
URI path templates are URIs with variables embedded within the URI syntax. These variables are
substituted at runtime in order for a resource to respond to a request based on the substituted URI. Variables
are denoted by curly braces. For example, look at the following @Path [https://jersey.github.io/apidocsjavax.jax-rs/2.1.5/javax/ws/rs/Path.html] annotation:
@Path("/users/{username}")
In this type of example, a user will be prompted to enter their name, and then a Jersey web service
configured to respond to requests to this URI path template will respond. For example, if the user
entered their username as "Galileo", the web service will respond to the following URL: http://
example.com/users/Galileo
To obtain the value of the username variable the @PathParam [https://jersey.github.io/apidocs-javax.jaxrs/2.1.5/javax/ws/rs/PathParam.html] may be used on method parameter of a request method, for example:

Example 3.2. Specifying URI path parameter
1 @Path("/users/{username}")
2 public class UserResource {
3
4
@GET
5
@Produces("text/xml")
6
public String getUser(@PathParam("username") String userName) {
7
...
8
}
9 }
If it is required that a user name must only consist of lower and upper case numeric characters then it is
possible to declare a particular regular expression, which overrides the default regular expression, "[^/]+",
for example:
@Path("users/{username: [a-zA-Z][a-zA-Z_0-9]*}")
In this type of example the username variable will only match user names that begin with one upper or
lower case letter and zero or more alpha numeric characters and the underscore character. If a user name
does not match that a 404 (Not Found) response will occur.
A @Path [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Path.html] value may or may not
begin with a '/', it makes no difference. Likewise, by default, a @Path [https://jersey.github.io/apidocsjavax.jax-rs/2.1.5/javax/ws/rs/Path.html] value may or may not end in a '/', it makes no difference, and
thus request URLs that end or do not end in a '/' will both be matched.

3.1.2. @GET, @PUT, @POST, @DELETE, ... (HTTP
Methods)
@GET [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/GET.html], @PUT [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/PUT.html], @POST [https://jersey.github.io/
apidocs-javax.jax-rs/2.1.5/javax/ws/rs/POST.html],
@DELETE
[https://jersey.github.io/apidocsjavax.jax-rs/2.1.5/javax/ws/rs/DELETE.html] and @HEAD [https://jersey.github.io/apidocs-javax.jaxrs/2.1.5/javax/ws/rs/HEAD.html] are resource method designator annotations defined by JAX-RS and
which correspond to the similarly named HTTP methods. In the example above, the annotated Java method

38

JAX-RS Application,
Resources and Sub-Resources
will process HTTP GET requests. The behavior of a resource is determined by which of the HTTP methods
the resource is responding to.
The following example is an extract from the storage service sample that shows the use of the PUT method
to create or update a storage container:

Example 3.3. PUT method
1 @PUT
2 public Response putContainer() {
3
System.out.println("PUT CONTAINER " + container);
4
5
URI uri = uriInfo.getAbsolutePath();
6
Container c = new Container(container, uri.toString());
7
8
Response r;
9
if (!MemoryStore.MS.hasContainer(c)) {
10
r = Response.created(uri).build();
11
} else {
12
r = Response.noContent().build();
13
}
14
15
MemoryStore.MS.createContainer(c);
16
return r;
17 }
By default the JAX-RS runtime will automatically support the methods HEAD and OPTIONS, if not
explicitly implemented. For HEAD the runtime will invoke the implemented GET method (if present) and
ignore the response entity (if set). A response returned for the OPTIONS method depends on the requested
media type defined in the 'Accept' header. The OPTIONS method can return a response with a set of
supported resource methods in the 'Allow' header or return a WADL [http://wadl.java.net/] document. See
wadl section for more information.

3.1.3. @Produces
The
@Produces
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Produces.html]
annotation is used to specify the MIME media types of representations a resource can produce and
send back to the client. In this example, the Java method will produce representations identified by the
MIME media type "text/plain". @Produces [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/
rs/Produces.html] can be applied at both the class and method levels. Here's an example:

Example 3.4. Specifying output MIME type
1 @Path("/myResource")
2 @Produces("text/plain")
3 public class SomeResource {
4
@GET
5
public String doGetAsPlainText() {
6
...
7
}
8
9
@GET
10
@Produces("text/html")
11
public String doGetAsHtml() {
12
...

39

JAX-RS Application,
Resources and Sub-Resources
13
14 }

}

The doGetAsPlainText method defaults to the MIME type of the @Produces [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Produces.html] annotation at the class level.
The doGetAsHtml method's @Produces [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/
rs/Produces.html] annotation overrides the class-level @Produces [https://jersey.github.io/apidocsjavax.jax-rs/2.1.5/javax/ws/rs/Produces.html] setting, and specifies that the method can produce HTML
rather than plain text.
If a resource class is capable of producing more that one MIME media type then the resource method
chosen will correspond to the most acceptable media type as declared by the client. More specifically the
Accept header of the HTTP request declares what is most acceptable. For example if the Accept header
is "Accept: text/plain" then the doGetAsPlainText method will be invoked. Alternatively
if the Accept header is " Accept: text/plain;q=0.9, text/html", which declares that the
client can accept media types of "text/plain" and "text/html" but prefers the latter, then the doGetAsHtml
method will be invoked.
More than one media type may be declared in the same @Produces [https://jersey.github.io/apidocsjavax.jax-rs/2.1.5/javax/ws/rs/Produces.html] declaration, for example:

Example 3.5. Using multiple output MIME types
1
2
3
4
5

@GET
@Produces({"application/xml", "application/json"})
public String doGetAsXmlOrJson() {
...
}

The doGetAsXmlOrJson method will get invoked if either of the media types "application/xml" and
"application/json" are acceptable. If both are equally acceptable then the former will be chosen because
it occurs first.
Optionally, server can also specify the quality factor for individual media types. These are considered if
several are equally acceptable by the client. For example:

Example 3.6. Server-side content negotiation
1
2
3
4
5

@GET
@Produces({"application/xml; qs=0.9", "application/json"})
public String doGetAsXmlOrJson() {
...
}

In the above sample, if client accepts both "application/xml" and "application/json" (equally), then a server
always sends "application/json", since "application/xml" has a lower quality factor.
The examples above refers explicitly to MIME media types for clarity. It is possible to refer to constant
values, which may reduce typographical errors, see the constant field values of MediaType [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/core/MediaType.html].

3.1.4. @Consumes
The
@Consumes
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Consumes.html]
annotation is used to specify the MIME media types of representations that can be consumed by a resource.
The above example can be modified to set the cliched message as follows:

40

JAX-RS Application,
Resources and Sub-Resources

Example 3.7. Specifying input MIME type
1
2
3
4
5

@POST
@Consumes("text/plain")
public void postClichedMessage(String message) {
// Store the message
}

In this example, the Java method will consume representations identified by the MIME media type "text/
plain". Notice that the resource method returns void. This means no representation is returned and response
with a status code of 204 (No Content) will be returned to the client.
@Consumes [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Consumes.html] can be
applied at both the class and the method levels and more than one media type may be declared in the same
@Consumes [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Consumes.html] declaration.

3.2. Parameter Annotations (@*Param)
Parameters of a resource method may be annotated with parameter-based annotations to extract
information from a request. One of the previous examples presented the use of @PathParam [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/PathParam.html] to extract a path parameter from
the path component of the request URL that matched the path declared in @Path [https://jersey.github.io/
apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Path.html].
@QueryParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/QueryParam.html] is used
to extract query parameters from the Query component of the request URL. The following example is an
extract from the sparklines sample:

Example 3.8. Query parameters
1
2
3
4
5
6
7
8
9
10
11
12

@Path("smooth")
@GET
public Response smooth(
@DefaultValue("2") @QueryParam("step") int step,
@DefaultValue("true") @QueryParam("min-m") boolean hasMin,
@DefaultValue("true") @QueryParam("max-m") boolean hasMax,
@DefaultValue("true") @QueryParam("last-m") boolean hasLast,
@DefaultValue("blue") @QueryParam("min-color") ColorParam minColor,
@DefaultValue("green") @QueryParam("max-color") ColorParam maxColor,
@DefaultValue("red") @QueryParam("last-color") ColorParam lastColor) {
...
}

If a query parameter "step" exists in the query component of the request URI then the "step" value
will be extracted and parsed as a 32 bit signed integer and assigned to the step method parameter. If
"step" does not exist then a default value of 2, as declared in the @DefaultValue [https://jersey.github.io/
apidocs-javax.jax-rs/2.1.5/javax/ws/rs/DefaultValue.html] annotation, will be assigned to the step method
parameter. If the "step" value cannot be parsed as a 32 bit signed integer then a HTTP 404 (Not Found)
response is returned. User defined Java types such as ColorParam may be used, which as implemented
as follows:

Example 3.9. Custom Java type for consuming request parameters
1 public class ColorParam extends Color {
2

41

JAX-RS Application,
Resources and Sub-Resources
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24 }

public ColorParam(String s) {
super(getRGB(s));
}
private static int getRGB(String s) {
if (s.charAt(0) == '#') {
try {
Color c = Color.decode("0x" + s.substring(1));
return c.getRGB();
} catch (NumberFormatException e) {
throw new WebApplicationException(400);
}
} else {
try {
Field f = Color.class.getField(s);
return ((Color)f.get(null)).getRGB();
} catch (Exception e) {
throw new WebApplicationException(400);
}
}
}

In general the Java type of the method parameter may:
1. Be a primitive type;
2. Have a constructor that accepts a single String argument;
3. Have a static method named valueOf or fromString that accepts a
single String argument (see, for example, Integer.valueOf(String) and
java.util.UUID.fromString(String));
4. Have a registered implementation of javax.ws.rs.ext.ParamConverterProvider JAX-RS
extension SPI that returns a javax.ws.rs.ext.ParamConverter instance capable of a "from
string" conversion for the type. or
5. Be List, Set or SortedSet, where T satisfies 2 or 3 above. The resulting collection
is read-only.
Sometimes parameters may contain more than one value for the same name. If this is the case then types
in 5) may be used to obtain all values.
If the @DefaultValue [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/DefaultValue.html]
is not used in conjunction with @QueryParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/
ws/rs/QueryParam.html] and the query parameter is not present in the request then value will be an empty
collection forList, Set or SortedSet, null for other object types, and the Java-defined default for
primitive types.
The @PathParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/PathParam.html] and the
other parameter-based annotations, @MatrixParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/
javax/ws/rs/MatrixParam.html], @HeaderParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/
javax/ws/rs/HeaderParam.html], @CookieParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/
javax/ws/rs/CookieParam.html], @FormParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/
ws/rs/FormParam.html] obey the same rules as @QueryParam [https://jersey.github.io/apidocs-javax.jaxrs/2.1.5/javax/ws/rs/QueryParam.html]. @MatrixParam [https://jersey.github.io/apidocs-javax.jax-

42

JAX-RS Application,
Resources and Sub-Resources
rs/2.1.5/javax/ws/rs/MatrixParam.html] extracts information from URL path segments. @HeaderParam
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/HeaderParam.html] extracts information
from the HTTP headers. @CookieParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
CookieParam.html] extracts information from the cookies declared in cookie related HTTP headers.
@FormParam
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/FormParam.html]
is
slightly special because it extracts information from a request representation that is of the MIME media
type "application/x-www-form-urlencoded" and conforms to the encoding specified by
HTML forms, as described here. This parameter is very useful for extracting information that is POSTed
by HTML forms, for example the following extracts the form parameter named "name" from the POSTed
form data:

Example 3.10. Processing POSTed HTML form
1
2
3
4
5

@POST
@Consumes("application/x-www-form-urlencoded")
public void post(@FormParam("name") String name) {
// Store the message
}

If it is necessary to obtain a general map of parameter name to values then, for query and path parameters
it is possible to do the following:

Example 3.11. Obtaining general map of URI path and/or query parameters
1 @GET
2 public String get(@Context UriInfo ui) {
3
MultivaluedMap queryParams = ui.getQueryParameters();
4
MultivaluedMap pathParams = ui.getPathParameters();
5 }
For header and cookie parameters the following:

Example 3.12. Obtaining general map of header parameters
1 @GET
2 public String get(@Context HttpHeaders hh) {
3
MultivaluedMap headerParams = hh.getRequestHeaders();
4
Map pathParams = hh.getCookies();
5 }
In general @Context [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/core/Context.html]
can be used to obtain contextual Java types related to the request or response.
Because form parameters (unlike others) are part of the message entity, it is possible to do the following:

Example 3.13. Obtaining general map of form parameters
1
2
3
4
5

@POST
@Consumes("application/x-www-form-urlencoded")
public void post(MultivaluedMap formParams) {
// Store the message
}

I.e. you don't need to use the @Context [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
core/Context.html] annotation.

43

JAX-RS Application,
Resources and Sub-Resources
Another kind of injection is the @BeanParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/
javax/ws/rs/BeanParam.html] which allows to inject the parameters described above into a single
bean. A bean annotated with @BeanParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/
ws/rs/BeanParam.html] containing any fields and appropriate *param annotation(like @PathParam
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/PathParam.html]) will be initialized with
corresponding request values in expected way as if these fields were in the resource class. Then instead
of injecting request values like path param into a constructor parameters or class fields the @BeanParam
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/BeanParam.html] can be used to inject
such a bean into a resource or resource method. The @BeanParam [https://jersey.github.io/apidocsjavax.jax-rs/2.1.5/javax/ws/rs/BeanParam.html] is used this way to aggregate more request parameters
into a single bean.

Example 3.14. Example of the bean which will be used as @BeanParam [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/BeanParam.html]
1 public class MyBeanParam {
2
@PathParam("p")
3
private String pathParam;
4
5
@MatrixParam("m")
6
@Encoded
7
@DefaultValue("default")
8
private String matrixParam;
9
10
@HeaderParam("header")
11
private String headerParam;
12
13
private String queryParam;
14
15
public MyBeanParam(@QueryParam("q") String queryParam) {
16
this.queryParam = queryParam;
17
}
18
19
public String getPathParam() {
20
return pathParam;
21
}
22
...
23 }

Example 3.15. Injection of MyBeanParam as a method parameter:

1 @POST
2 public void post(@BeanParam MyBeanParam beanParam, String entity) {
3
final String pathParam = beanParam.getPathParam(); // contains injected pat
4
...
5 }
The example shows aggregation of injections @PathParam [https://jersey.github.io/apidocs-javax.jaxrs/2.1.5/javax/ws/rs/PathParam.html], @QueryParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/
javax/ws/rs/QueryParam.html] @MatrixParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/
ws/rs/MatrixParam.html] and @HeaderParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/
ws/rs/HeaderParam.html] into one single bean. The rules for injections inside the bean are the
same as described above for these injections. The @DefaultValue [https://jersey.github.io/apidocsjavax.jax-rs/2.1.5/javax/ws/rs/DefaultValue.html] is used to define the default value for matrix

44

JAX-RS Application,
Resources and Sub-Resources
parameter matrixParam. Also the @Encoded [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/
rs/Encoded.html] annotation has the same behaviour as if it were used for injection in the resource method
directly. Injecting the bean parameter into @Singleton resource class fields is not allowed (injections into
method parameter must be used instead).
@BeanParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/BeanParam.html] can
contain all parameters injections (@PathParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/
javax/ws/rs/PathParam.html], @QueryParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/
ws/rs/QueryParam.html], @MatrixParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/
rs/MatrixParam.html], @HeaderParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/
rs/HeaderParam.html], @CookieParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/
rs/CookieParam.html], @FormParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
FormParam.html]). More beans can be injected into one resource or method parameters even if they inject
the same request values. For example the following is possible:

Example 3.16. Injection of more beans into one resource methods:
1
2
3
4
5
6

@POST
public void post(@BeanParam MyBeanParam beanParam, @BeanParam AnotherBean anoth
String entity) {
// beanParam.getPathParam() == pathParam
...
}

3.3. Sub-resources
@Path [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Path.html] may be used on classes
and such classes are referred to as root resource classes. @Path [https://jersey.github.io/apidocs-javax.jaxrs/2.1.5/javax/ws/rs/Path.html] may also be used on methods of root resource classes. This enables
common functionality for a number of resources to be grouped together and potentially reused.
The first way @Path [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Path.html] may be
used is on resource methods and such methods are referred to as sub-resource methods. The following
example shows the method signatures for a root resource class from the jmaki-backend sample:

Example 3.17. Sub-resource methods
1 @Singleton
2 @Path("/printers")
3 public class PrintersResource {
4
5
@GET
6
@Produces({"application/json", "application/xml"})
7
public WebResourceList getMyResources() { ... }
8
9
@GET @Path("/list")
10
@Produces({"application/json", "application/xml"})
11
public WebResourceList getListOfPrinters() { ... }
12
13
@GET @Path("/jMakiTable")
14
@Produces("application/json")
15
public PrinterTableModel getTable() { ... }
16
17
@GET @Path("/jMakiTree")

45

JAX-RS Application,
Resources and Sub-Resources
18
19
20
21
22
23
24
25
26
27
28
29
30
31 }

@Produces("application/json")
public TreeModel getTree() { ... }

@GET @Path("/ids/{printerid}")
@Produces({"application/json", "application/xml"})
public Printer getPrinter(@PathParam("printerid") String printerId) { ... }

@PUT @Path("/ids/{printerid}")
@Consumes({"application/json", "application/xml"})
public void putPrinter(@PathParam("printerid") String printerId, Printer pr

@DELETE @Path("/ids/{printerid}")
public void deletePrinter(@PathParam("printerid") String printerId) { ... }

If the path of the request URL is "printers" then the resource methods not annotated with @Path
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Path.html] will be selected. If the request
path of the request URL is "printers/list" then first the root resource class will be matched and then
the sub-resource methods that match "list" will be selected, which in this case is the sub-resource
methodgetListOfPrinters. So, in this example hierarchical matching on the path of the request
URL is performed.
The second way @Path [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Path.html] may
be used is on methods not annotated with resource method designators such as @GET [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/GET.html] or @POST [https://jersey.github.io/
apidocs-javax.jax-rs/2.1.5/javax/ws/rs/POST.html]. Such methods are referred to as sub-resource
locators. The following example shows the method signatures for a root resource class and a resource
class from the optimistic-concurrency sample:

Example 3.18. Sub-resource locators
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

@Path("/item")
public class ItemResource {
@Context UriInfo uriInfo;
@Path("content")
public ItemContentResource getItemContentResource() {
return new ItemContentResource();
}
@GET
@Produces("application/xml")
public Item get() { ... }
}
}
public class ItemContentResource {
@GET
public Response get() { ... }
@PUT
@Path("{version}")
public void put(@PathParam("version") int version,

46

JAX-RS Application,
Resources and Sub-Resources
24
25
26
27
28 }

@Context HttpHeaders headers,
byte[] in) {
...
}

The root resource class ItemResource contains the sub-resource locator method
getItemContentResource that returns a new resource class. If the path of the request URL
is "item/content" then first of all the root resource will be matched, then the sub-resource locator
will be matched and invoked, which returns an instance of the ItemContentResource resource
class. Sub-resource locators enable reuse of resource classes. A method can be annotated with the
@Path [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Path.html] annotation with empty
path (@Path("/") or @Path("")) which means that the sub resource locator is matched for the path
of the enclosing resource (without sub-resource path).

Example 3.19. Sub-resource locators with empty path
1 @Path("/item")
2 public class ItemResource {
3
4
@Path("/")
5
public ItemContentResource getItemContentResource() {
6
return new ItemContentResource();
7
}
8 }
In the example above the sub-resource locator method getItemContentResource is matched for
example for request path "/item/locator" or even for only "/item".
In addition the processing of resource classes returned by sub-resource locators is performed at runtime
thus it is possible to support polymorphism. A sub-resource locator may return different sub-types
depending on the request (for example a sub-resource locator could return different sub-types dependent
on the role of the principle that is authenticated). So for example the following sub resource locator is valid:

Example 3.20. Sub-resource locators returning sub-type
1 @Path("/item")
2 public class ItemResource {
3
4
@Path("/")
5
public Object getItemContentResource() {
6
return new AnyResource();
7
}
8 }
Note that the runtime will not manage the life-cycle or perform any field injection onto instances returned
from sub-resource locator methods. This is because the runtime does not know what the life-cycle of the
instance is. If it is required that the runtime manages the sub-resources as standard resources the Class
should be returned as shown in the following example:

Example 3.21. Sub-resource locators created from classes
1 import javax.inject.Singleton;
2
3 @Path("/item")

47

JAX-RS Application,
Resources and Sub-Resources
4
5
6
7
8
9
10
11
12
13
14

public class ItemResource {
@Path("content")
public Class getItemContentResource() {
return ItemContentSingletonResource.class;
}
}
@Singleton
public class ItemContentSingletonResource {
// this class is managed in the singleton life cycle
}

JAX-RS resources are managed in per-request scope by default which means that new resource is created
for each request. In this example the javax.inject.Singleton annotation says that the resource
will be managed as singleton and not in request scope. The sub-resource locator method returns a class
which means that the runtime will managed the resource instance and its life-cycle. If the method would
return instance instead, the Singleton annotation would have no effect and the returned instance would
be used.
The sub resource locator can also return a programmatic resource model. See resource builder section for
information of how the programmatic resource model is constructed. The following example shows very
simple resource returned from the sub-resource locator method.

Example 3.22. Sub-resource locators returning resource model
1
2
3
4
5
6
7
8
9
10

import org.glassfish.jersey.server.model.Resource;
@Path("/item")
public class ItemResource {
@Path("content")
public Resource getItemContentResource() {
return Resource.from(ItemContentSingletonResource.class);
}
}

The code above has exactly the same effect as previous example. Resource is a resource simple resource
constructed from ItemContentSingletonResource. More complex programmatic resource can
be returned as long they are valid resources.

3.4. Life-cycle of Root Resource Classes
By default the life-cycle of root resource classes is per-request which, namely that a new instance of a
root resource class is created every time the request URI path matches the root resource. This makes for a
very natural programming model where constructors and fields can be utilized (as in the previous section
showing the constructor of the SparklinesResource class) without concern for multiple concurrent
requests to the same resource.
In general this is unlikely to be a cause of performance issues. Class construction and garbage collection
of JVMs has vastly improved over the years and many objects will be created and discarded to serve and
process the HTTP request and return the HTTP response.
Instances of singleton root resource classes can be declared by an instance of Application [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/core/Application.html].

48

JAX-RS Application,
Resources and Sub-Resources
Jersey supports two further life-cycles using Jersey specific annotations.

Table 3.1. Resource scopes
Scope

AnnotationAnnotation full class Description
name

Request
scope

@RequestScoped
org.glassfish.jersey.process.internal.RequestScoped
Default lifecycle (applied when no annotation is present).
(or none)
In this scope the resource instance is created for each
new request and used for processing of this request. If
the resource is used more than one time in the request
processing, always the same instance will be used. This
can happen when a resource is a sub resource and is
returned more times during the matching. In this situation
only one instance will serve the requests.

Perlookup
scope

@PerLookup
org.glassfish.hk2.api.PerLookup
In this scope the resource instance is created every time
it is needed for the processing even it handles the same
request.

Singleton @Singletonjavax.inject.Singleton In this scope there is only one instance
per jax-rs application. Singleton resource can
be either annotated with @Singleton and its
class can be registered using the instance
of Application [https://jersey.github.io/apidocs-javax.jaxrs/2.1.5/javax/ws/rs/core/Application.html]. You can also
create singletons by registering singleton instances into
Application [https://jersey.github.io/apidocs-javax.jaxrs/2.1.5/javax/ws/rs/core/Application.html].

3.5. Rules of Injection
Previous sections have presented examples of annotated types, mostly annotated method parameters but
also annotated fields of a class, for the injection of values onto those types.
This section presents the rules of injection of values on annotated types. Injection can be performed on
fields, constructor parameters, resource/sub-resource/sub-resource locator method parameters and bean
setter methods. The following presents an example of all such injection cases:

Example 3.23. Injection
1 @Path("{id:\\d+}")
2 public class InjectedResource {
3
// Injection onto field
4
@DefaultValue("q") @QueryParam("p")
5
private String p;
6
7
// Injection onto constructor parameter
8
public InjectedResource(@PathParam("id") int id) { ... }
9
10
// Injection onto resource method parameter
11
@GET
12
public String get(@Context UriInfo ui) { ... }
13
14
// Injection onto sub-resource resource method parameter

49

JAX-RS Application,
Resources and Sub-Resources
15
16
17
18
19
20
21
22
23
24
25
26 }

@Path("sub-id")
@GET
public String get(@PathParam("sub-id") String id) { ... }
// Injection onto sub-resource locator method parameter
@Path("sub-id")
public SubResource getSubResource(@PathParam("sub-id") String id) { ... }
// Injection using bean setter method
@HeaderParam("X-header")
public void setHeader(String header) { ... }

There are some restrictions when injecting on to resource classes with a life-cycle of singleton scope. In
such cases the class fields or constructor parameters cannot be injected with request specific parameters.
So, for example the following is not allowed.

Example 3.24. Wrong injection into a singleton scope
1
2
3
4
5
6
7
8
9
10
11
12
13

@Path("resource")
@Singleton
public static class MySingletonResource {

@QueryParam("query")
String param; // WRONG: initialization of application will fail as you cann
// inject request specific parameters into a singleton resour
@GET
public String get() {
return "query param: " + param;
}
}

The example above will cause validation failure during application initialization as singleton resources
cannot inject request specific parameters. The same example would fail if the query parameter would be
injected into constructor parameter of such a singleton. In other words, if you wish one resource instance
to server more requests (in the same time) it cannot be bound to a specific request parameter.
The exception exists for specific request objects which can injected even into constructor or class fields.
For these objects the runtime will inject proxies which are able to simultaneously server more request.
These request objects are HttpHeaders, Request, UriInfo, SecurityContext. These proxies
can be injected using the @Context [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/core/
Context.html] annotation. The following example shows injection of proxies into the singleton resource
class.

Example 3.25. Injection of proxies into singleton
1 @Path("resource")
2 @Singleton
3 public static class MySingletonResource {
4
@Context
5
Request request; // this is ok: the proxy of Request will be injected into
6
7
public MySingletonResource(@Context SecurityContext securityContext) {

50

JAX-RS Application,
Resources and Sub-Resources
8
9
10
11
12
13
14
15 }

// this is ok too: the proxy of SecurityContext will be injected
}
@GET
public String get() {
return "query param: " + param;
}

To summarize the injection can be done into the following constructs:

Table 3.2. Overview of injection types
Java construct Description
Class fields

Inject value directly into the field of the class. The field can be private and must not be
final. Cannot be used in Singleton scope except proxiable types mentioned above.

Constructor
parameters

The constructor will be invoked with injected values. If more constructors exists the one
with the most injectable parameters will be invoked. Cannot be used in Singleton scope
except proxiable types mentioned above.

Resource
methods

The resource methods (these annotated with @GET, @POST, ...) can contain parameters
that can be injected when the resource method is executed. Can be used in any scope.

Sub resource The sub resource locators (methods annotated with @Path but not @GET, @POST, ...)
locators
can contain parameters that can be injected when the resource method is executed. Can
be used in any scope.
Setter methods Instead of injecting values directly into field the value can be injected into
the setter method which will initialize the field. This injection can be used
only with @Context [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
core/Context.html] annotation. This means it cannot be used for example for injecting
of query params but it can be used for injections of request. The setters will be called
after the object creation and only once. The name of the method does not necessary have
a setter pattern. Cannot be used in Singleton scope except proxiable types mentioned
above.
The following example shows all possible java constructs into which the values can be injected.

Example 3.26. Example of possible injections

1 @Path("resource")
2 public static class SummaryOfInjectionsResource {
3
@QueryParam("query")
4
String param; // injection into a class field
5
6
7
@GET
8
public String get(@QueryParam("query") String methodQueryParam) {
9
// injection into a resource method parameter
10
return "query param: " + param;
11
}
12
13
@Path("sub-resource-locator")
14
public Class subResourceLocator(@QueryParam("query") String su
15
// injection into a sub resource locator parameter

51

JAX-RS Application,
Resources and Sub-Resources

16
return SubResource.class;
17
}
18
19
public SummaryOfInjectionsResource(@QueryParam("query") String constructorQ
20
// injection into a constructor parameter
21
}
22
23
24
@Context
25
public void setRequest(Request request) {
26
// injection into a setter method
27
System.out.println(request != null);
28
}
29 }
30
31 public static class SubResource {
32
@GET
33
public String get() {
34
return "sub resource";
35
}
36 }
The @FormParam [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/FormParam.html]
annotation is special and may only be utilized on resource and sub-resource methods. This is because it
extracts information from a request entity.

3.6. Use of @Context
Previous sections have introduced the use of @Context [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/
javax/ws/rs/core/Context.html]. Chapter "Context" in the JAX-RS specification presents all the standard
JAX-RS Java types that may be used with @Context [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/
javax/ws/rs/core/Context.html].
When deploying a JAX-RS application using servlet then ServletConfig [http://
docs.oracle.com/javaee/5/api/javax/servlet/ServletConfig.html], ServletContext [http://docs.oracle.com/
javaee/5/api/javax/servlet/ServletContext.html], HttpServletRequest [http://docs.oracle.com/javaee/5/api/
javax/servlet/http/HttpServletRequest.html] and HttpServletResponse [http://docs.oracle.com/javaee/5/
api/javax/servlet/http/HttpServletResponse.html] are available using @Context [https://jersey.github.io/
apidocs-javax.jax-rs/2.1.5/javax/ws/rs/core/Context.html].

3.7. Programmatic resource model
Resources can be constructed from classes or instances but also can be constructed from a programmatic
resource model. Every resource created from resource classes can also be constructed using the
programmatic resource builder api. See resource builder section for more information.

52

Chapter 4. Application Deployment and
Runtime Environments
4.1. Introduction
This chapter is an overview of various server-side environments currently capable of running JAX-RS
applications on top of Jersey server runtime. Jersey supports wide range of server environments from
lightweight http containers up to full-fledged Java EE servers. Jersey applications can also run in an OSGi
runtime. The way how the application is published depends on whether the application shall run in a Java
SE environment or within a container.

Note
This chapter is focused on server-side Jersey deployment models. The Jersey client runtime does
not have any specific container requirements and runs in plain Java SE 6 or higher runtime.

4.2. JAX-RS Application Model
JAX-RS provides a deployment agnostic abstract class Application [https://jersey.github.io/apidocsjavax.jax-rs/2.1.5/javax/ws/rs/core/Application.html] for declaring root resource and provider classes, and
root resource and provider singleton instances. A Web service may extend this class to declare root resource
and provider classes. For example,

Example 4.1. Deployment agnostic application model
1 public class MyApplication extends Application {
2
@Override
3
public Set> getClasses() {
4
Set> s = new HashSet>();
5
s.add(HelloWorldResource.class);
6
return s;
7
}
8 }
Alternatively it is possible to reuse ResourceConfig [https://jersey.github.io/apidocs/2.28/jersey/org/
glassfish/jersey/server/ResourceConfig.html] - Jersey's own implementations of Application class.
This class can either be directly instantiated and then configured or it can be extended and the configuration
code placed into the constructor of the extending class. The approach typically depends on the chosen
deployment runtime.
Compared to Application, the ResourceConfig provides advanced capabilities to simplify
registration of JAX-RS components, such as scanning for root resource and provider classes in a provided
classpath or a in a set of package names etc. All JAX-RS component classes that are either manually
registered or found during scanning are automatically added to the set of classes that are returned by
getClasses. For example, the following application class that extends from ResourceConfig scans
during deployment for JAX-RS components in packages org.foo.rest and org.bar.rest:

Note
Package scanning ignores an inheritance and therefore @Path annotation on parent classes and
interfaces will be ignored. These classes won't be registered as the JAX-RS component classes.

53

Application Deployment
and Runtime Environments

Example 4.2. Reusing Jersey implementation in your custom application model
1 public class MyApplication extends ResourceConfig {
2
public MyApplication() {
3
packages("org.foo.rest;org.bar.rest");
4
}
5 }

Note
Later in this chapter, the term Application subclass is frequently used. Whenever used, this
term refers to the JAX-RS Application Model explained above.

4.3. Auto-Discoverable Features
By default Jersey 2.x does not implicitly register any extension features from the modules available
on the classpath, unless explicitly stated otherwise in the documentation of each particular extension.
Users are expected to explicitly register the extension Feature [https://jersey.github.io/apidocs-javax.jaxrs/2.1.5/javax/ws/rs/core/Feature.html]s using their Application subclass. For a few Jersey provided
modules however there is no need to explicitly register their extension Features as these are
discovered and registered in the Configuration [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/
ws/rs/core/Configuration.html] (on client/server) automatically by Jersey runtime whenever the modules
implementing these features are present on the classpath of the deployed JAX-RS application. The modules
that are automatically discovered include:
• JSON binding feature from jersey-media-moxy
• jersey-media-json-processing
• jersey-bean-validation
Besides these modules there are also few features/providers present in jersey-server module that
are discovered by this mechanism and their availability is affected by Jersey auto-discovery support
configuration (see Section 4.3.1, “Configuring Feature Auto-discovery Mechanism”), namely:
• WadlFeature
[https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/server/wadl/
WadlFeature.html] - enables WADL processing.
• UriConnegFilter
[https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/server/filter/
UriConnegFilter.html] - a URI-based content negotiation filter.
Almost all Jersey auto-discovery implementations have AutoDiscoverable.DEFAULT_PRIORITY
@Priority set.

Note
Auto discovery functionality is in Jersey supported by implementing an internal
AutoDiscoverable Jersey SPI. This interface is not public at the moment, and is subject to
change in the future, so be careful when trying to use it.

4.3.1. Configuring Feature Auto-discovery Mechanism
The mechanism of feature auto-discovery in Jersey that described above is enabled by default. It can be
disabled by using special (common/server/client) properties:

54

Application Deployment
and Runtime Environments

Common auto discovery properties
• CommonProperties.FEATURE_AUTO_DISCOVERY_DISABLE
apidocs/2.28/jersey/org/glassfish/jersey/
CommonProperties.html#FEATURE_AUTO_DISCOVERY_DISABLE]

[https://jersey.github.io/

When set, disables auto discovery globally on client/server.
• CommonProperties.JSON_PROCESSING_FEATURE_DISABLE
apidocs/2.28/jersey/org/glassfish/jersey/
CommonProperties.html#JSON_PROCESSING_FEATURE_DISABLE]

[https://jersey.github.io/

When set, disables configuration of Json Processing (JSR-353) feature.
• CommonProperties.MOXY_JSON_FEATURE_DISABLE
[https://jersey.github.io/apidocs/2.28/
jersey/org/glassfish/jersey/CommonProperties.html#MOXY_JSON_FEATURE_DISABLE]
When set, disables configuration of MOXy Json feature.
For each of these properties there is a client/server counter-part that is only honored by the Jersey
client or server runtime respectively (see ClientProperties [https://jersey.github.io/apidocs/2.28/jersey/
org/glassfish/jersey/client/ClientProperties.html]/ServerProperties [https://jersey.github.io/apidocs/2.28/
jersey/org/glassfish/jersey/server/ServerProperties.html]). When set, each of these client/server specific
auto-discovery related properties overrides the value of the related common property.

Note
In case an auto-discoverable mechanism (in general or for a specific feature) is disabled, then
all the features, components and/or properties, registered by default using the auto-discovery
mechanism have to be registered manually.

4.4. Configuring the Classpath Scanning
Jersey uses a common Java Service Provider mechanism to obtain all service implementations. It means
that Jersey scans the whole class path to find appropriate META-INF/services/ files. The class path
scanning may be time consuming. The more jar or war files on the classpath the longer the scanning time.
In use cases where you need to save every millisecond of application bootstrap time, you may typically
want to disable the services provider lookup in Jersey.

List of SPIs recognized by Jersey
• AutoDiscoverable (server, client) - it means if you disable service loading the AutoDiscoverable
feature is automatically disabled too
• ForcedAutoDiscoverable (server, client) - Jersey always looks for these auto discoverable
features even if the service loading is disabled
• HeaderDelegateProvider (server, client)
• ComponentProvider (server)
• ContainerProvider (server)
• AsyncContextDelegateProvider (server/Servlet)
55

Application Deployment
and Runtime Environments

List of additional SPIs recognized by Jersey in case the metainf-services
module is on the classpath
• MessageBodyReader (server, client)
• MessageBodyWriter (server, client)
• ExceptionMapper (server, client)
Since it is possible to configure all SPI implementation classes or instances manually in your
Application subclass, disabling services lookup in Jersey does not affect any functionality of Jersey
core modules and extensions and can save dozens of ms during application initialization in exchange for
a more verbose application configuration code.
The services lookup in Jersey (enabled by default) can be disabled via a
dedicated CommonProperties.METAINF_SERVICES_LOOKUP_DISABLE [https://jersey.github.io/
apidocs/2.28/jersey/org/glassfish/jersey/
CommonProperties.html#METAINF_SERVICES_LOOKUP_DISABLE] property. There is a client/
server counter-part that only disables the feature on the client or server respectively:
ClientProperties.METAINF_SERVICES_LOOKUP_DISABLE [https://jersey.github.io/apidocs/2.28/
jersey/org/glassfish/jersey/client/
ClientProperties.html#METAINF_SERVICES_LOOKUP_DISABLE]/
ServerProperties.METAINF_SERVICES_LOOKUP_DISABLE [https://jersey.github.io/apidocs/2.28/
jersey/org/glassfish/jersey/server/
ServerProperties.html#METAINF_SERVICES_LOOKUP_DISABLE]. As in all other cases, the client/
server specific properties overrides the value of the related common property, when set.
For
example,
following
code
snippet
disables
service
provider
lookup
and
manually
registers
implementations
of
different
JAX-RS
and
Jersey
provider
types (ContainerRequestFilter [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/container/
ContainerRequestFilter.html], Feature [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
core/Feature.html], ComponentProvider [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/
server/spi/ComponentProvider.html] and ContainerProvider [https://jersey.github.io/apidocs/2.28/jersey/
org/glassfish/jersey/server/spi/ContainerProvider.html]):

Example 4.3. Registering SPI implementations using ResourceConfig
1
2
3
4
5
6

ResourceConfig resourceConfig = new ResourceConfig(MyResource.class);
resourceConfig.register(org.glassfish.jersey.server.filter.UriConnegFilter.clas
resourceConfig.register(org.glassfish.jersey.server.validation.ValidationFeatur
resourceConfig.register(org.glassfish.jersey.server.spring.SpringComponentProvi
resourceConfig.register(org.glassfish.jersey.grizzly2.httpserver.GrizzlyHttpCon
resourceConfig.property(ServerProperties.METAINF_SERVICES_LOOKUP_DISABLE, true)

Similarly, in scenarios where the deployment model requires extending the Application subclass (e.g.
in all Servlet container deployments), the following code could be used to achieve the same application
configuration:

Example 4.4. Registering SPI implementations using ResourceConfig subclass

1 public class MyApplication extends ResourceConfig {
2
public MyApplication() {
3
register(org.glassfish.jersey.server.filter.UriConnegFilter.class);
4
register(org.glassfish.jersey.server.validation.ValidationFeature.class
5
register(org.glassfish.jersey.server.spring.SpringComponentProvider.cla

56

Application Deployment
and Runtime Environments
6
7
8
9 }

register(org.glassfish.jersey.grizzly2.httpserver.GrizzlyHttpContainerP
property(ServerProperties.METAINF_SERVICES_LOOKUP_DISABLE, true);
}

4.5. Java SE Deployment Environments
4.5.1. HTTP servers
Java based HTTP servers represent a minimalistic and flexible way of deploying Jersey application. The
HTTP servers are usually embedded in the application and configured and started programmatically. In
general, Jersey container for a specific HTTP server provides a custom factory method that returns a
correctly initialized HTTP server instance.

4.5.1.1. JDK Http Server
Starting with Java SE 6, Java runtime ships with a built-in lightweight HTTP server.
Jersey offers integration with this Java SE HTTP server through the jersey-containerjdk-http container extension module. Instead of creating the HttpServer
[http://
docs.oracle.com/javase/6/docs/jre/api/net/httpserver/spec/com/sun/net/
httpserver/HttpServer.html] instance directly, use the createHttpServer() method
of JdkHttpServerFactory [https://jersey.github.io/apidocs/2.28/jersey/
org/glassfish/jersey/jdkhttp/JdkHttpServerFactory.html], which creates the
HttpServer instance configured as a Jersey container and initialized with the supplied Application
subclass.
Creating new Jersey-enabled jdk http server is as easy as:

Example 4.5. Using Jersey with JDK HTTP Server
1 URI baseUri = UriBuilder.fromUri("http://localhost/").port(9998).build();
2 ResourceConfig config = new ResourceConfig(MyResource.class);
3 HttpServer server = JdkHttpServerFactory.createHttpServer(baseUri, config);
A JDK HTTP Container dependency needs to be added:

org.glassfish.jersey.containers
jersey-container-jdk-http
2.28


4.5.1.2. Grizzly HTTP Server
Grizzly [http://grizzly.java.net/] is a multi-protocol framework built on top of Java NIO
[http://docs.oracle.com/javase/6/docs/api/java/nio/package-summary.html]. Grizzly aims to simplify
development of robust and scalable servers. Jersey provides a container extension module that enables
support for using Grizzly as a plain vanilla HTTP container that runs JAX-RS applications. Starting a
Grizzly server to run a JAX-RS or Jersey application is one of the most lightweight and easy ways how
to expose a functional RESTful services application.
Grizzly
HTTP
container
supports
injection
of
Grizzly-specific
org.glassfish.grizzly.http.server.Request
and
org.glassfish.grizzly.http.server.Response instances into JAX-RS and Jersey

57

Application Deployment
and Runtime Environments
application resources and providers. However, since Grizzly Request is not proxiable, the injection
of Grizzly Request into singleton (by default) JAX-RS / Jersey providers is only possible via
javax.inject.Provider instance. (Grizzly Response does not suffer the same restriction.)

Example 4.6. Using Jersey with Grizzly HTTP Server

1 URI baseUri = UriBuilder.fromUri("http://localhost/").port(9998).build();
2
ResourceConfig config = new ResourceConfig(MyResource.class);
3
HttpServer server = GrizzlyHttpServerFactory.createHttpServer(baseUri, conf
The container extension module dependency to be added is:

org.glassfish.jersey.containers
jersey-container-grizzly2-http
2.28


Note
Jersey uses Grizzly extensively in the project unit and end-to-end tests via test framework.

4.5.1.3. Simple server
Simple [http://www.simpleframework.org/] is a framework which allows developers to create a HTTP
server instance and embed it within an application. Again, creating the server instance is achieved by
calling a factory method from the jersey-container-simple-http container extension module.
Simple framework HTTP container supports injection of Simple framework-specific
org.simpleframework.http.Request and org.simpleframework.http.Response
instances into JAX-RS and Jersey application resources and providers.

Example 4.7. Using Jersey with the Simple framework
1 URI baseUri = UriBuilder.fromUri("http://localhost/").port(9998).build();
2
ResourceConfig config = new ResourceConfig(MyResource.class);
3
SimpleContainer server = SimpleContainerFactory.create(baseUri, config);
The necessary container extension module dependency in this case is:

org.glassfish.jersey.containers
jersey-container-simple-http
2.28


Note
Simple framework HTTP container does not support deployment on context paths other than root
path ("/"). Non-root context path is ignored during deployment.

4.5.1.4. Jetty HTTP Server
Jetty is a popular Servlet container and HTTP server. We will not look into Jetty's capabilities as a Servlet
container (although we are using it in our tests and examples), because there is nothing specific to Jetty

58

Application Deployment
and Runtime Environments
when using a Servlet-based deployment model, which is extensively described later in our Section 4.7,
“Servlet-based Deployment” section. We will here only focus on describing how to use Jetty's HTTP
server.
Jetty HTTP container supports injection of Jetty-specific org.eclipse.jetty.server.Request
and org.eclipse.jetty.server.Response instances into JAX-RS and Jersey application
resources and providers. However, since Jetty HTTP Request is not proxiable, the injection
of Jetty Request into singleton (by default) JAX-RS / Jersey providers is only possible via
javax.inject.Provider instance. (Jetty Response does not suffer the same restriction.)

Example 4.8. Using Jersey with Jetty HTTP Server
1 URI baseUri = UriBuilder.fromUri("http://localhost/").port(9998).build();
2 ResourceConfig config = new ResourceConfig(MyResource.class);
3 Server server = JettyHttpContainerFactory.createServer(baseUri, config);
And, of course, we add the necessary container extension module dependency:
1 
2
org.glassfish.jersey.containers
3
jersey-container-jetty-http
4
2.28
5 

Note
Jetty HTTP container does not support deployment on context paths other than root path ("/").
Non-root context path is ignored during deployment.

4.5.1.5. Netty HTTP Server
Netty is a NIO client server framework which enables quick and easy development of network applications
such as protocol servers and clients. Jersey supports Netty as a container and as a client connector - this
chapter will present how to use the container.

Example 4.9. Using Jersey with Netty HTTP Server

1 URI baseUri = UriBuilder.fromUri("http://localhost/").port(9998).build();
2 ResourceConfig resourceConfig = new ResourceConfig(HelloWorldResource.class);
3 Channel server = NettyHttpContainerProvider.createServer(baseUri, resourceConfi
And, of course, we add the necessary container extension module dependency:
1 
2
org.glassfish.jersey.containers
3
jersey-container-netty-http
4
2.28
5 

Note
Netty HTTP container does not support deployment on context paths other than root path ("/").
Non-root context path is ignored during deployment.

59

Application Deployment
and Runtime Environments

4.6. Creating programmatic JAX-RS endpoint
JAX-RS specification also defines the ability to programmatically create a JAX-RS application endpoint
(i.e. container) for any instance of a Application subclass. For example, Jersey supports creation of
Grizzly [http://grizzly.java.net/] HttpHandler instance as follows:
HttpHandler endpoint = RuntimeDelegate.getInstance()
.createEndpoint(new MyApplication(), HttpHandler.class);
Once the Grizzly HttpHandler endpoint is created, it can be used for in-process deployment to a specific
base URL.

4.7. Servlet-based Deployment
In a Servlet container, JAX-RS defines multiple deployment options depending on the Servlet API version
supported by the Servlet container. Following sections describe these options in detail.

4.7.1. Servlet 2.x Container
Jersey integrates with any Servlet containers supporting at least Servlet 2.5 specification. Running on
a Servlet container that supports Servlet API 3.0 or later gives you the advantage of wider feature set
(especially asynchronous request processing support) and easier and more flexible deployment options. In
this section we will focus on the basic deployment models available in any Servlet 2.5 or higher container.
In Servlet 2.5 environment, you have to explicitly declare the Jersey container Servlet in your Web
application's web.xml deployment descriptor file.

Example 4.10. Hooking up Jersey as a Servlet

1 
2

3
MyApplication
4
org.glassfish.jersey.servlet.ServletContainer
6
...
7

8

9
...
10

11
MyApplication
12
/myApp/*
13

14
...
15 
Alternatively, you can register Jersey container as a filter:

Example 4.11. Hooking up Jersey as a Servlet Filter
1 
2

3
MyApplication

60

Application Deployment
and Runtime Environments

4
org.glassfish.jersey.servlet.ServletContainer
6
...
7

8

9
...
10

11
MyApplication
12
/myApp/*
13

14
...
15 

Important
Servlet 2.x API does not provide a way how to programmatically read the filter mappings.
To make application deployed using filter work correctly, either Servlet 3.x container must
be used (jersey-container-servlet instead of jersey-container-servletcore), or the context path of the app needs to be defined using init parameter
jersey.config.servlet.filter.contextPath.
The content of the  element will vary depending on the way you decide to configure
Jersey resources.

4.7.1.1. Custom Application subclass
If you extend the Application [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/core/
Application.html] class to provide the list of relevant root resource classes (getClasses()) and
singletons (getSingletons()), i.e. your JAX-RS application model, you then need to register it in your
web application web.xml deployment descriptor using a Servlet or Servlet filter initialization parameter
with a name of javax.ws.rs.Application [sic] as follows:

Example 4.12. Configuring Jersey container Servlet or Filter to use custom
Application subclass
1 
2
javax.ws.rs.Application
3
org.foo.MyApplication
4 
Jersey will consider all the classes returned by getClasses() and getSingletons() methods of
your Application implementation.

Note
The name of the configuration property as defined by JAX-RS specification is indeed
javax.ws.rs.Application and not javax.ws.rs.core.Application as one
might expect.

4.7.1.2. Jersey package scanning
If there is no configuration properties to be set and deployed application consists only from resources and
providers stored in particular packages, you can instruct Jersey to scan these packages and register any
found resources and providers automatically:

61

Application Deployment
and Runtime Environments

Example 4.13. Configuring Jersey container Servlet or Filter to use package
scanning
1
2
3
4
5
6
7
8
9
10


jersey.config.server.provider.packages

org.foo.myresources,org.bar.otherresources



jersey.config.server.provider.scanning.recursive
false


Jersey will automatically discover the resources and providers in the selected packages. You
can also decide whether Jersey should recursively scan also sub-packages by setting the
jersey.config.server.provider.scanning.recursive property. The default value is
true, i.e. the recursive scanning of sub-packages is enabled.

4.7.1.3. Selecting concrete resource and provider classes
While the above-mentioned package scanning is useful esp. for development and testing, you
may want to have a little bit more control when it comes to production deployment in terms
of being able to enumerate specific resource and provider classes. In Jersey it is possible to
achieve this even without a need to implement a custom Application subclass. The specific
resource and provider fully-qualified class names can be provided in a comma-separated value of
jersey.config.server.provider.classnames initialization parameter.

Example 4.14. Configuring Jersey container Servlet or Filter to use a list of classes
1 
2
jersey.config.server.provider.classnames
3

4
org.foo.myresources.MyDogResource,
5
org.bar.otherresources.MyCatResource
6

7 

Note
All of the techniques that have been described in this section also apply to Servlet containers
that support Servlet API 3.0 and later specification. Newer Servlet specifications only give you
additional features, deployment options and more flexibility.

4.7.2. Servlet 3.x Container
4.7.2.1. Descriptor-less deployment
There are multiple deployment options in the Servlet 3.0 container for a JAX-RS application defined
by implementing a custom Application [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
core/Application.html] subclass. For simple deployments, no web.xml is necessary at all. Instead, an
@ApplicationPath [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/ApplicationPath.html]
annotation can be used to annotate the custom Application [https://jersey.github.io/apidocs-javax.jax-

62

Application Deployment
and Runtime Environments
rs/2.1.5/javax/ws/rs/core/Application.html] subclass and define the base application URI for all JAX-RS
resources configured in the application:

Example 4.15. Deployment of a JAX-RS application using @ApplicationPath
with Servlet 3.0
1 @ApplicationPath("resources")
2 public class MyApplication extends ResourceConfig {
3
public MyApplication() {
4
packages("org.foo.rest;org.bar.rest");
5
}
6 }

Note
There are many other convenience methods in the ResourceConfig that can
be used in the constructor of your custom subclass to configure your JAXRS application, see ResourceConfig [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/
jersey/server/ResourceConfig.html] API documentation for more details.
In case you are not providing web.xml deployment descriptor for your maven-based web
application project, you need to configure your maven-war-plugin to ignore the missing
web.xml file by setting failOnMissingWebXml [http://maven.apache.org/plugins/maven-war-plugin/
war-mojo.html#failOnMissingWebXml] configuration property to false in your project pom.xml file:

Example 4.16. Configuration of maven-war-plugin to ignore missing web.xml
1 
2
...
3

4
org.apache.maven.plugins
5
maven-war-plugin
6
2.3
7

8
false
9

10

11
...
12 

4.7.2.2. Deployment using web.xml descriptor
Another Servlet 3.x container deployment model is to declare the JAX-RS application details in the
web.xml. This is typically suitable for more complex deployments, e.g. when security model needs
to be properly defined or when additional initialization parameters have to be passed to Jersey runtime.
JAX-RS 1.1 and later specifies that a fully qualified name of the class that implements Application
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/core/Application.html] may be used in the
definition of a  element as part of your application's web.xml deployment descriptor.
Following example illustrates this approach:

Example 4.17. Deployment of a JAX-RS application using web.xml with Servlet
3.0
1 

63

Application Deployment
and Runtime Environments
2

3
org.foo.rest.MyApplication
4

5
...
6

7
org.foo.rest.MyApplication
8
/resources
9

10
...
11 
Note that the  element is omitted from the Servlet declaration. This is a correct
declaration utilizing the Servlet 3.0 extension mechanism described in detail in the Section 4.7.2.3, “Servlet
Pluggability Mechanism” section. Also note that  is used in the example to define
the base resource URI.

Tip
When running in a Servlet 2.x it would instead be necessary to declare the Jersey container Servlet
or Filter and pass the Application implementation class name as one of the init-param
entries, as described in Section 4.7.1, “Servlet 2.x Container”.

4.7.2.3. Servlet Pluggability Mechanism
Servlet framework pluggability mechanism is a feature introduced with Servlet 3.0 specification. It
simplifies the configuration of various frameworks built on top of Servlets. Instead of having one
web.xml file working as a central point for all the configuration options, it is possible to modularize
the deployment descriptor by using the concept of so-called web fragments - several specific and focused
web.xml files. A set of web fragments basically builds up the final deployment descriptor. This
mechanism also provides SPI hooks that enable web frameworks to register themselves in the Servlet
container or customize the Servlet container deployment process in some other way. This section describes
how JAX-RS and Jersey leverage the Servlet pluggability mechanism.

4.7.2.3.1. JAX-RS application without an Application subclass
If no Application (or ResourceConfig) subclass is present, Jersey will dynamically add a Jersey
container Servlet and set its name to javax.ws.rs.core.Application. The web application
path will be scanned and all the root resource classes (the classes annotated with @Path [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Path.html] annotation) as well as any providers
that are annotated with @Provider [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/ext/
Provider.html] annotation packaged with the application will be automatically registered in the JAX-RS
application. The web application has to be packaged with a deployment descriptor specifying at least the
mapping for the added javax.ws.rs.core.Application Servlet:

Example 4.18. web.xml of a JAX-RS application without an Application
subclass
1 
4
5

7


64

Application Deployment
and Runtime Environments
8
javax.ws.rs.core.Application
9

10
11

12
javax.ws.rs.core.Application
13
/myresources/*
14

15 

4.7.2.3.2. JAX-RS application with a custom Application subclass
When a custom Application subclass is provided, in such case the Jersey server runtime behavior
depends od whether or not there is a Servlet defined to handle the application subclass.
If the web.xml contains a Servlet definition, that has an initialization parameter
javax.ws.rs.Application whose value is the fully qualified name of the Application
subclass, Jersey does not perform any additional steps in such case.
If no such Servlet is defined to handle the custom Application subclass, Jersey dynamically adds a
Servlet with a fully qualified name equal to the name of the provided Application subclass. To define
the mapping for the added Servlet, you can either annotate the custom Application subclass with an
@ApplicationPath [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/ApplicationPath.html]
annotation (Jersey will use the annotation value appended with /* to automatically define the mapping
for the Servlet), or specify the mapping for the Servlet in the web.xml descriptor directly.
In the following example, let's assume that the JAX-RS application is defined using a custom
Application subclass named org.example.MyApplication. Then the web.xml file could
have the following structure:

Example 4.19.
1 
4
5

7

8
org.example.MyApplication
9

10
11

14

15
org.example.MyApplication
16
/myresources/*
17

18 

Note
If your custom Application subclass is packaged in the war, it defines which resources will
be taken into account.

65

Application Deployment
and Runtime Environments
• If both getClasses() and getSingletons() methods return an empty collection, then
ALL the root resource classes and providers packaged in the web application archive will be
used, Jersey will automatically discover them by scanning the .war file.
• If any of the two mentioned methods - getClasses() or getSingletons() returns a
non-empty collection, only those classes and/or singletons will be published in the JAX-RS
application.

Table 4.1. Servlet 3 Pluggability Overview
Condition

Jersey action

Servlet Name

No Application
subclass

Adds Servlet

javax.ws.rs.core.Application
Servlet mapping is required

web.xml

Application subclass
No action
handled by existing Servlet

Already defined

Not required

Application subclass
NOT handled by existing
Servlet

FQN of the
Application subclass

if no
@ApplicationPath
on the Application
subclass, then Servlet
mapping is required

Adds Servlet

4.7.3. Jersey Servlet container modules
Jersey uses its own ServletContainer [https://jersey.github.io/apidocs/2.28/
jersey/org/glassfish/jersey/servlet/ServletContainer.html] implementation
of Servlet and Servlet Filter API to integrate with Servlet containers. As any JAX-RS runtime, Jersey
provides support for Servlet containers that support Servlet specification version 2.5 and higher. To support
JAX-RS 2.0 asynchronous resources on top of a Servlet container, support for Servlet specification version
3.0 or higher is required.
When deploying to a Servlet container, Jersey application is typically packaged as a .war file. As with
any other Servlet application, JAX-RS application classes are packaged in WEB-INF/classes or WEBINF/lib and required application libraries are located in WEB-INF/lib. For more details, please refer
to the Servlet Specification (JSR 315 [http://jcp.org/en/jsr/detail?id=315]).
Jersey provides two Servlet modules. The first module is the Jersey core Servlet module that provides the
core Servlet integration support and is required in any Servlet 2.5 or higher container:

org.glassfish.jersey.containers
jersey-container-servlet-core

To support additional Servlet 3.x deployment modes and asynchronous JAX-RS resource programming
model, an additional Jersey module is required:

org.glassfish.jersey.containers
jersey-container-servlet

The jersey-container-servlet module depends on jersey-container-servlet-core
module, therefore when it is used, it is not necessary to explicitly declare the jersey-containerservlet-core dependency.

66

Application Deployment
and Runtime Environments
Note that in simple cases, you don't need to provide the deployment descriptor (web.xml) and can use
the @ApplicationPath annotation, as described in Section 4.7.2.3.1, “JAX-RS application without
an Application subclass” section.

4.8. Java EE Platform
This section describes, how you can publish Jersey JAX-RS resources as various Java EE platform
elements. JAX-RS and Jersey give you wide choice of possibilities and it is up to your taste (and design
of your application), what Java EE technology you decide to use for the management of your resources.

4.8.1. Managed Beans
Jersey supports the use of Java EE Managed beans as root resource classes, providers as well as
Application subclasses.
In the code below, you can find an example of a bean, that uses a managed-bean interceptor defined as a
JAX-RS bean. The bean is used to intercept calls to the resource method getIt():
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

@ManagedBean
@Path("/managedbean")
public class ManagedBeanResource {
public static class MyInterceptor {
@AroundInvoke
public String around(InvocationContext ctx) throws Exception {
System.out.println("around() called");
return (String) ctx.proceed();
}
}
@GET
@Produces("text/plain")
@Interceptors(MyInterceptor.class)
public String getIt() {
return "Hi managed bean!";
}
}

4.8.2. Context and Dependency Injection (CDI)
CDI beans can be used as Jersey root resource classes, providers as well as Application subclasses.
Providers and Application subclasses have to be singleton or application scoped.
The next example shows a usage of a CDI bean as a JAX-RS root resource class. We assume, that CDI
has been enabled. The code snipped uses the type-safe dependency injection provided in CDI by using
another bean (MyOtherCdiBean):
1 @Path("/cdibean")
2 public class CdiBeanResource {
3
@Inject MyOtherCdiBean bean;
4
5
@GET
6
@Produces("text/plain")

67

// CDI injected bean

Application Deployment
and Runtime Environments
7
8
9
10 }

public String getIt() {
return bean.getIt();
}

The above works naturally inside any Java EE compliant AS container. In Jersey version 2.15, container
agnostic CDI support was introduced. This feature allows you to publish CDI based JAX-RS resources
also in other containers. Jersey cdi-webapp example shows Jersey/CDI integration in Grizzly HTTP and
Apache Tomcat server. Detailed description of Jersey CDI support outside of a fully fledged Java EE
application container could be found in Chapter 24, Jersey CDI Container Agnostic Support.

4.8.3. Enterprise Java Beans (EJB)
Stateless and Singleton Session beans can be used as Jersey root resource classes, providers and/or
Application subclasses. You can choose from annotating the methods in the EJB's local interface
or directly the method in an interface-less EJB POJO. JAX-RS specifications requires its implementors
to discover EJBs by inspecting annotations on classes (or local interfaces), but not in the deployment
descriptors (ejb-jar.xml). As such, to keep your JAX-RS application portable, do not override EJB
annotations or provide any additional meta-data in the deployment descriptor file.
Following example consists of a stateless EJB and a local interface used in Jersey:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

@Local
public interface LocalEjb {
@GET
@Produces("text/plain")
public String getIt();
}
@Stateless
@Path("/stateless")
public class StatelessEjbResource implements LocalEjb {
@Override
public String getIt() {
return "Hi Stateless!";
}
}

Note
Please note that Jersey currently does not support deployment of JAX-RS applications packaged
as standalone EJB modules (ejb-jars). To use EJBs as JAX-RS resources, the EJBs need to be
packaged either directly in a WAR or in an EAR that contains at least one WAR. This is to ensure
Servlet container initialization that is necessary for bootstrapping of the Jersey runtime.

4.8.4. Java EE Servers
4.8.4.1. GlassFish Application Server
As explained in 2.3.1 , you don't need to add any specific dependencies on GlassFish, Jersey is already
packaged within GlassFish. You only need to add the provided-scoped dependencies to you project to
be able to compile it. At runtime, GlassFish will make sure that your application has access to the Jersey
libraries.

68

Application Deployment
and Runtime Environments
Started with version 2.7, Jersey allows injecting Jersey specific types into CDI enabled JAX-RS
components using the @javax.inject.Inject annotation. This covers also custom HK2 bindings,
that are configured as part of Jersey application. The feature specifically enables usage of Jersey monitoring
statistics (provided that the statistic feature is turned on) in CDI environment, where injection is the only
mean to get access to monitoring data.
Since both CDI and HK2 use the same injection annotation, Jersey could get confused
in certain cases, which could lead to nasty runtime issues. The get better control
over what Jersey evaluates as HK2 injection, end-users could take advantage of newly
introduced, Hk2CustomBoundTypesProvider [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/
jersey/ext/cdi1x/spi/Hk2CustomBoundTypesProvider.html], SPI. Please see the linked javadoc to get
detailed information on how to use the SPI in your application.

4.8.4.2. Oracle WebLogic Server
WebLogic 12.1.2 and earlier supports only JAX-RS 1.1 (JSR 311 [http://jcp.org/en/jsr/detail?id=311])
out of the box with Jersey 1.x (WebLogic 12.1.2 ships with Jersey 1.13). To update the version of
Jersey 1.x in these earlier WebLogic releases, please read the Updating the Version of Jersey JAXRS RI [http://docs.oracle.com/middleware/1212/wls/RESTF/version-restful-service.htm] chapter in the
WebLogic RESTful Web Services Development Guide.
In WebLogic 12.1.3, Jersey 1.18 is shipped as a default JAX-RS 1.1 provider. In this version of
WebLogic, JAX-RS 2.0 (using Jersey 2.5.1) is supported as an optionally installable shared library. Please
read through the WebLogic 12.1.3 RESTful Web Services Development Guide [http://docs.oracle.com/
middleware/1213/wls/RESTF/use-jersey20-ri.htm#RESTF290] for details how to enable JAX-RS 2.0
support on WebLogic 12.1.3.

4.8.4.3. Other Application Servers
Third party Java EE application servers usually ship with a JAX-RS implementation. If you want to use
Jersey instead of the default JAX-RS provider, you need to add Jersey libraries to your classpath and
disable the default JAX-RS provider in the container.
In general, Jersey will be deployed as a Servlet and the resources can be deployed in various ways, as
described in this section. However, the exact steps will vary from vendor to vendor.

4.9. OSGi
OSGi support has been added to the Jersey version 1.2. Since then, you should be able to utilize standard
OSGi means to run Jersey based web applications in OSGi runtime as described in the OSGi Service
Platform Enterprise Specification. Jersey is currently compatible with OSGi 4.2.0, the specification could
be downloaded from the OSGi 4.2.0 Download Site [http://www.osgi.org/Download/Release4V42].
The two supported ways of running an OSGi web application are:
• WAB (Web Application Bundle)
• HTTP Service
WAB is in fact just an OSGified WAR archive. HTTP Service feature allows you to publish Java EE
Servlets in the OSGi runtime.
Two examples were added to the Jersey distribution to depict the above mentioned features and show how
to use them with Jersey:

69

Application Deployment
and Runtime Environments
• WAB Example [https://github.com/jersey/jersey/tree/2.28/examples/osgi-helloworld-webapp]
• HTTP Service example [https://github.com/jersey/jersey/tree/2.28/examples/osgi-http-service]
Both examples are multi-module maven projects and both consist of an application OSGi bundle
module and a test module. The tests are based on the PAX Exam [http://ops4j1.jira.com/wiki/display/
PAXEXAM3/Pax+Exam] framework. Both OSGi examples also include a readme file containing
instructions how to manually run the example applications using Apache Felix [http://felix.apache.org/
site/index.html] framework.
The rest of the chapter describes how to run the above mentioned examples on GlassFish 4 application
server.

4.9.1. Enabling the OSGi shell in Glassfish
Since GlassFish utilizes Apache Felix, an OSGi runtime comes out of the box with GlassFish.
However, for security reasons, the OSGi shell has been turned off. You can however explicitly
enable it either by starting GlassFish the asadmin console and creating a Java system property
glassfish.osgi.start.level.final and setting its value to 3:

Example 4.20.
Start the admin console:
1
2 ~/glassfish/bin$ ./asadmin
3 Use "exit" to exit and "help" for online help.
4 asadmin>
You can check the actual value of the java property (loaded from the configuration file):
26
27
28
29
30

asadmin> list-jvm-options
...
-Dglassfish.osgi.start.level.final=2
...

And change the value by typing:
26
27 asadmin>

create-jvm-options --target server -Dglassfish.osgi.start.level.final

The second option is to change the value in the osgi.properties configuration file:
1
2
3
4
5
6

# Final start level of OSGi framework. This is used by GlassFish launcher code
# to set the start level of the OSGi framework once server is up and running so
# optional services can start. The initial start level of framework is controll
# the standard framework property called org.osgi.framework.startlevel.beginnin
glassfish.osgi.start.level.final=3

You can then execute the Felix shell commands by typing osgi  in the asadmin
console. For example:
1
2 asadmin> osgi lb
3 ... list of bundles ...

70

Application Deployment
and Runtime Environments
or launching the shell using osgi-shell command in the admin console (the domain must be started,
otherwise the osgi shell won't launch):
1
2 asadmin> osgi-shell
3 Use "exit" to exit and "help" for online help.
4 gogo$
and execute the osgi commands directly (without the "osgi" prefix):
1
2 gogo$ lb
3 ... list of bundles ...

4.9.2. WAB Example
As mentioned above, WAB is just an OSGi-fied WAR archive. Besides the usual OSGi headers it must
in addition contain a special header, Web-ContextPath, specifying the web application context path. Our
WAB has (beside some other) the following headers present in the manifest:
1 Web-ContextPath: helloworld
2 Webapp-Context: helloworld
3 Bundle-ClassPath: WEB-INF/classese
Here, the second header is ignored by GlassFish, but may be required by other containers not fully
compliant with the OSGi Enterprise Specification mentioned above. The third manifest header worth
mentioning is the Bundle-ClassPath specifying where to find the application Java classes within the bundle
archive. More about manifest headers in OSGi can be found in the OSGi Wiki [http://wiki.osgi.org/wiki/
Category:Manifest_Header].
For more detailed information on the example please see the WAB Example [https://github.com/jersey/
jersey/tree/2.28/examples/osgi-helloworld-webapp] source code. This example does not package into a
single war file. Instead a war and a set of additional jars is produced during the build. See the next
example to see how to deploy OSGi based Jersey application to GlassFish.

4.9.3. HTTP Service Example
Note
When deploying an OSGi HTTP Service example to GlassFish, please make sure the OSGi HTTP
Service bundle is installed on your GlassFish instance.
You can directly install and activate the Jersey application bundle. In case of our example, you can either
install the example bundle stored locally (and alternatively build from Jersey sources):
1) Build (optional)
1
2 examples$ cd osgi-http-service/bundle
3 bundle$ mvn clean package
You can also get the binary readily compiled from Java.net Maven Repository [https://maven.java.net/
content/repositories/releases/org/glassfish/jersey/examples/osgi-http-service/bundle/2.28].
2) Install into OSGi runtime:

71

Application Deployment
and Runtime Environments
1
2 gogo$ install file:///path/to/file/bundle.jar
3 Bundle ID: 303
or install it directly from the maven repository:

1
2 gogo$ install http://maven.java.net/content/repositories/releases/org/glassfish
3 Bundle ID: 303
Make sure to replace  with an appropriate version number. Which one is appropriate depends
on the specific GlassFish 4.x version you are using. The version of the bundle cannot be higher than the
version of Jersey integrated in your GlassFish 4.x server. Jersey bundles declare dependencies on other
bundles at the OSGi level and those dependencies are version-sensitive. If you use example bundle from
let's say version 2.5, but Glassfish has Jersey 2.3.1, dependencies will not be satisfied and bundle will not
start. If this happens, the error will look something like this:
1
2
3
4
5
6
7
8
9
10
11

gogo$ lb
...
303 | Installed
gogo$ start 303

|

1| jersey-examples-osgi-http-service-bundle (2.5.0.SNAPSH

org.osgi.framework.BundleException: Unresolved constraint in bundle
org.glassfish.jersey.examples.osgi-http-service.bundle [303]: Unable to resolve
[303.0] osgi.wiring.package; (&(osgi.wiring.package=org.glassfish.jersey.servle
(version>=2.5.0)(!(version>=3.0.0)))
gogo$

In the opposite scenario (example bundle version 2.3.1 and Glassfish Jersey version higher), everything
should work fine.
Also, if you build GlassFish from the main trunk sources and use the example from most recent Jersey
release, you will most likely be able to run the examples from the latest Jersey release, as Jersey team
typically integrates all newly released versions of Jersey immediately into GlassFish.
As a final step, start the bundle:
1 gogo$ start 303
Again, the Bundle ID (in our case 303) has to be replaced by the correct one returned from the install
command.
The example app should now be up and running. You can access it on http://localhost:8080/osgi/
jersey-http-service/status [http://localhost:8080/osgi/jersey-http-service/status]. Please see HTTP Service
example [https://github.com/jersey/jersey/tree/2.28/examples/osgi-http-service] source code for more
details on the example.

4.10. Other Environments
4.10.1. Oracle Java Cloud Service
As Oracle Public Cloud is based on WebLogic server, the same applies as in the paragraph about WebLogic
deployment (see Section 4.8.4.2, “Oracle WebLogic Server”). More on developing applications for Oracle

72

Application Deployment
and Runtime Environments
Java Cloud Service can be found in this guide [http://docs.oracle.com/cloud/131/developer_services/
CSJSU/java-develop.htm#BABHDAJH].

73

Chapter 5. Client API
This section introduces the JAX-RS Client API, which is a fluent Java based API for communication
with RESTful Web services. This standard API that is also part of Java EE 7 is designed to make it very
easy to consume a Web service exposed via HTTP protocol and enables developers to concisely and
efficiently implement portable client-side solutions that leverage existing and well established client-side
HTTP connector implementations.
The JAX-RS client API can be utilized to consume any Web service exposed on top of a HTTP protocol or
it's extension (e.g. WebDAV), and is not restricted to services implemented using JAX-RS. Yet, developers
familiar with JAX-RS should find the client API complementary to their services, especially if the client
API is utilized by those services themselves, or to test those services. The JAX-RS client API finds
inspiration in the proprietary Jersey 1.x Client API and developers familiar with the Jersey 1.x Client API
should find it easy to understand all the concepts introduced in the new JAX-RS Client API.
The goals of the client API are threefold:
1. Encapsulate a key constraint of the REST architectural style, namely the Uniform Interface Constraint
and associated data elements, as client-side Java artifacts;
2. Make it as easy to consume RESTful Web services exposed over HTTP, same as the JAX-RS serverside API makes it easy to develop RESTful Web services; and
3. Share common concepts and extensibility points of the JAX-RS API between the server and the client
side programming models.
As an extension to the standard JAX-RS Client API, the Jersey Client API supports a pluggable architecture
to enable the use of different underlying HTTP client Connector [https://jersey.github.io/apidocs/2.28/
jersey/org/glassfish/jersey/client/spi/Connector.html] implementations. Several such implementations are
currently provided with Jersey. We have a default client connector using Http(s)URLConnection
supplied with the JDK as well as connector implementations based on Apache HTTP Client, Jetty HTTP
client and Grizzly Asynchronous Client.

5.1. Uniform Interface Constraint
The uniform interface constraint bounds the architecture of RESTful Web services so that a client, such as
a browser, can utilize the same interface to communicate with any service. This is a very powerful concept
in software engineering that makes Web-based search engines and service mash-ups possible. It induces
properties such as:
1. simplicity, the architecture is easier to understand and maintain; and
2. evolvability or loose coupling, clients and services can evolve over time perhaps in new and unexpected
ways, while retaining backwards compatibility.
Further constraints are required:
1. every resource is identified by a URI;
2. a client interacts with the resource via HTTP requests and responses using a fixed set of HTTP methods;
3. one or more representations can be returned and are identified by media types; and
4. the contents of which can link to further resources.

74

Client API

The above process repeated over and again should be familiar to anyone who has used a browser to fill in
HTML forms and follow links. That same process is applicable to non-browser based clients.
Many existing Java-based client APIs, such as the Apache HTTP client API or HttpUrlConnection
supplied with the JDK place too much focus on the Client-Server constraint for the exchanges of request
and responses rather than a resource, identified by a URI, and the use of a fixed set of HTTP methods.
A resource in the JAX-RS client API is an instance of the Java class WebTarget [https://jersey.github.io/
apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/WebTarget.html]. and encapsulates an URI. The fixed set of
HTTP methods can be invoked based on the WebTarget. The representations are Java types, instances
of which, may contain links that new instances of WebTarget may be created from.

5.2. Ease of use and reusing JAX-RS artifacts
Since a JAX-RS component is represented as an annotated Java type, it makes it easy to configure, pass
around and inject in ways that are not so intuitive or possible with other client-side APIs. The Jersey Client
API reuses many aspects of the JAX-RS and the Jersey implementation such as:
1. URI building using UriBuilder [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/core/
UriBuilder.html] and UriTemplate [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/
uri/UriTemplate.html] to safely build URIs;
2. Built-in support for Java types of representations such as byte[], String, Number, Boolean,
Character, InputStream, java.io.Reader, File, DataSource, JAXB beans as well
as additional Jersey-specific JSON and Multi Part [https://jersey.github.io/apidocs/2.28/jersey/org/
glassfish/jersey/media/multipart/package-summary.html] support.
3. Using the fluent builder-style API pattern to make it easier to construct requests.
Some APIs, like the Apache HTTP Client or HttpURLConnection [http://docs.oracle.com/javase/6/
docs/api/java/net/HttpURLConnection.html] can be rather hard to use and/or require too much code
to do something relatively simple, especially when the client needs to understand different payload
representations. This is why the Jersey implementation of JAX-RS Client API provides support for
wrapping HttpUrlConnection and the Apache HTTP client. Thus it is possible to get the benefits of
the established JAX-RS implementations and features while getting the ease of use benefit of the simple
design of the JAX-RS client API. For example, with a low-level HTTP client library, sending a POST
request with a bunch of typed HTML form parameters and receiving a response de-serialized into a JAXB
bean is not straightforward at all. With the new JAX-RS Client API supported by Jersey this task is very
easy:

Example 5.1. POST request with form parameters
1
2
3
4
5
6
7
8
9
10
11

Client client = ClientBuilder.newClient();
WebTarget target = client.target("http://localhost:9998").path("resource");
Form form = new Form();
form.param("x", "foo");
form.param("y", "bar");
MyJAXBBean bean =
target.request(MediaType.APPLICATION_JSON_TYPE)
.post(Entity.entity(form,MediaType.APPLICATION_FORM_URLENCODED_TYPE),
MyJAXBBean.class);

75

Client API

In the Example 5.1, “POST request with form parameters” a new WebTarget instance is created using
a new Client [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/Client.html] instance
first, next a Form [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/core/Form.html] instance
is created with two form parameters. Once ready, the Form instance is POSTed to the target resource. First,
the acceptable media type is specified in the request(...) method. Then in the post(...) method,
a call to a static method on JAX-RS Entity [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
client/Entity.html] is made to construct the request entity instance and attach the proper content media type
to the form entity that is being sent. The second parameter in the post(...) method specifies the Java
type of the response entity that should be returned from the method in case of a successful response. In
this case an instance of JAXB bean is requested to be returned on success. The Jersey client API takes care
of selecting the proper MessageBodyWriter [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/
ws/rs/ext/MessageBodyWriter.html] for the serialization of the Form instance, invoking the POST request
and producing and de-serialization of the response message payload into an instance of a JAXB bean
using a proper MessageBodyReader [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
ext/MessageBodyReader.html].
If the code above had to be written using HttpUrlConnection, the developer would have to write
custom code to serialize the form data that are sent within the POST request and de-serialize the response
input stream into a JAXB bean. Additionally, more code would have to be written to make it easy to reuse
the logic when communicating with the same resource “http://localhost:8080/resource”
that is represented by the JAX-RS WebTarget instance in our example.

5.3. Overview of the Client API
5.3.1. Getting started with the client API
Refer to the dependencies for details on the dependencies when using the Jersey JAX-RS Client support.
You may also want to use a custom Connector [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/
jersey/client/spi/Connector.html] implementation. In such case you would need to include additional
dependencies on the module(s) containing the custom client connector that you want to use. See section
"Configuring custom Connectors" about how to use and configure a custom Jersey client transport
Connector.

5.3.2. Creating and configuring a Client instance
JAX-RS Client API is a designed to allow fluent programming model. This means, a construction of
a Client instance, from which a WebTarget is created, from which a request Invocation [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/Invocation.html] is built and invoked can
be chained in a single "flow" of invocations. The individual steps of the flow will be
shown in the following sections. To utilize the client API it is first necessary to build an
instance of a Client [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/Client.html]
using one of the static ClientBuilder [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/
ClientBuilder.html] factory methods. Here's the most simple example:
Client client = ClientBuilder.newClient();
The ClientBuilder is a JAX-RS API used to create new instances of Client. In a slightly more
advanced scenarios, ClientBuilder can be used to configure additional client instance properties,
such as a SSL transport settings, if needed (see ??? below).
A
Client
instance
can
be
configured
during
creation
by
passing
a
ClientConfig [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/client/ClientConfig.html]

76

Client API

to the newClient(Configurable) ClientBuilder factory method. ClientConfig
[https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/client/ClientConfig.html] implements
Configurable [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/core/Configurable.html] and
therefore it offers methods to register providers (e.g. features or individual entity providers, filters or
interceptors) and setup properties. The following code shows a registration of custom client filters:
1
2
3
4

ClientConfig clientConfig = new ClientConfig();
clientConfig.register(MyClientResponseFilter.class);
clientConfig.register(new AnotherClientFilter());
Client client = ClientBuilder.newClient(clientConfig);

In the example, filters are registered using the ClientConfig.register(...) method. There are
multiple overloaded versions of the method that support registration of feature and provider classes or
instances. Once a ClientConfig instance is configured, it can be passed to the ClientBuilder to
create a pre-configured Client instance.
Note that the Jersey ClientConfig supports the fluent API model of Configurable [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/core/Configurable.html]. With that the code that
configures a new client instance can be also written using a more compact style as shown below.
1
2 Client client = ClientBuilder.newClient(new ClientConfig()
3
.register(MyClientResponseFilter.class)
4
.register(new AnotherClientFilter());
The ability to leverage this compact pattern is inherent to all JAX-RS and Jersey Client API components.
Since Client implements Configurable [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
core/Configurable.html] interface too, it can be configured further even after it has been created. Important
is to mention that any configuration change done on a Client instance will not influence the ClientConfig
[https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/client/ClientConfig.html] instance that
was used to provide the initial Client instance configuration at the instance creation time. The next piece
of code shows a configuration of an existing Client instance.
1 client.register(ThirdClientFilter.class);
Similarly to earlier examples, since Client.register(...) method supports the fluent API style,
multiple client instance configuration calls can be chained:
1 client.register(FilterA.class)
2
.register(new FilterB())
3
.property("my-property", true);
To get the current configuration of the Client instance a getConfiguration() method can be used.
1
2
3
4
5
6

ClientConfig clientConfig = new ClientConfig();
clientConfig.register(MyClientResponseFilter.class);
clientConfig.register(new AnotherClientFilter());
Client client = ClientBuilder.newClient(clientConfig);
client.register(ThirdClientFilter.class);
Configuration newConfiguration = client.getConfiguration();

In the code, an additional MyClientResponseFilter class and AnotherClientFilter instance
are registered in the clientConfig. The clientConfig is then used to construct a new Client
instance. The ThirdClientFilter is added separately to the constructed Client instance. This

77

Client API

does not influence the configuration represented by the original clientConfig. In the last step a
newConfiguration is retrieved from the client. This configuration contains all three registered
filters while the original clientConfig instance still contains only two filters. Unlike clientConfig
created separately, the newConfiguration retrieved from the client instance represents a live client
configuration view. Any additional configuration changes made to the client instance are also reflected
in the newConfiguration. So, newConfiguration is really a view of the client configuration
and not a configuration state copy. These principles are important in the client API and will be used in
the following sections too. For example, you can construct a common base configuration for all clients (in
our case it would be clientConfig) and then reuse this common configuration instance to configure
multiple client instances that can be further specialized. Similarly, you can use an existing client
instance configuration to configure another client instance without having to worry about any side effects
in the original client instance.

5.3.3. Targeting a web resource
Once you have a Client instance you can create a WebTarget from it.
1 WebTarget webTarget = client.target("http://example.com/rest");
A Client contains several target(...) methods that allow for creation of WebTarget instance.
In this case we're using target(String uri) version. The uri passed to the method as a String
is the URI of the targeted web resource. In more complex scenarios it could be the context root URI
of the whole RESTful application, from which WebTarget instances representing individual resource
targets can be derived and individually configured. This is possible, because JAX-RS WebTarget also
implements Configurable:
1 WebTarget webTarget = client.target("http://example.com/rest");
2 webTarget.register(FilterForExampleCom.class);
The configuration principles used in JAX-RS client API apply to WebTarget as well. Each WebTarget
instance inherits a configuration from it's parent (either a client or another web target) and can be
further custom-configured without affecting the configuration of the parent component. In this case, the
FilterForExampleCom will be registered only in the webTarget and not in client. So, the
client can still be used to create new WebTarget instances pointing at other URIs using just the
common client configuration, which FilterForExampleCom filter is not part of.

5.3.4. Identifying resource on WebTarget
Let's assume we have a webTarget pointing at "http://example.com/rest" URI that represents
a context root of a RESTful application and there is a resource exposed on the URI "http://
example.com/rest/resource". As already mentioned, a WebTarget instance can be used to
derive other web targets. Use the following code to define a path to the resource.
1 WebTarget resourceWebTarget = webTarget.path("resource");
The resourceWebTarget now points to the resource on URI "http://example.com/rest/
resource". Again if we configure the resourceWebTarget with a filter specific to the resource,
it will not influence the original webTarget instance. However, the filter FilterForExampleCom
registration will still be inherited by the resourceWebTarget as it has been created from webTarget.
This mechanism allows you to share the common configuration of related resources (typically hosted
under the same URI root, in our case represented by the webTarget instance), while allowing for further
configuration specialization based on the specific requirements of each individual resource. The same
configuration principles of inheritance (to allow common config propagation) and decoupling (to allow
individual config customization) applies to all components in JAX-RS Client API discussed below.

78

Client API

Let's say there is a sub resource on the path "http://example.com/rest/resource/
helloworld". You can derive a WebTarget for this resource simply by:
1 WebTarget helloworldWebTarget = resourceWebTarget.path("helloworld");
Let's assume that the helloworld resource accepts a query param for GET requests which defines the
greeting message. The next code snippet shows a code that creates a new WebTarget with the query
param defined.
1 WebTarget helloworldWebTargetWithQueryParam =
2
helloworldWebTarget.queryParam("greeting", "Hi World!");
Please note that apart from methods that can derive new WebTarget instance based on a URI path
or query parameters, the JAX-RS WebTarget API contains also methods for working with matrix
parameters too.

5.3.5. Invoking a HTTP request
Let's now focus on invoking a GET HTTP request on the created web targets. To start building a new
HTTP request invocation, we need to create a new Invocation.Builder [https://jersey.github.io/apidocsjavax.jax-rs/2.1.5/javax/ws/rs/client/Invocation.Builder.html].
1 Invocation.Builder invocationBuilder =
2
helloworldWebTargetWithQueryParam.request(MediaType.TEXT_PLAIN_TYPE);
3 invocationBuilder.header("some-header", "true");
A new invocation builder instance is created using one of the request(...) methods that are available
on WebTarget. A couple of these methods accept parameters that let you define the media type of the
representation requested to be returned from the resource. Here we are saying that we request a "text/
plain" type. This tells Jersey to add a Accept: text/plain HTTP header to our request.
The invocationBuilder is used to setup request specific parameters. Here we can setup headers for
the request or for example cookie parameters. In our example we set up a "some-header" header to
value true.
Once finished with request customizations, it's time to invoke the request. We have two options
now. We can use the Invocation.Builder to build a generic Invocation [https://jersey.github.io/
apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/Invocation.html] instance that will be invoked some time
later. Using Invocation we will be able to e.g. set additional request properties which are properties
in a batch of several requests and use the generic JAX-RS Invocation API to invoke the batch of
requests without actually knowing all the details (such as request HTTP method, configuration etc.).
Any properties set on an invocation instance can be read during the request processing. For example,
in a custom ClientRequestFilter [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/
ClientRequestFilter.html] you can call getProperty() method on the supplied ClientRequestContext
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/ClientRequestContext.html] to read
a request property. Note that these request properties are different from the configuration properties set
on Configurable. As mentioned earlier, an Invocation instance provides generic invocation API
to invoke the HTTP request it represents either synchronously or asynchronously. See the Chapter 11,
Asynchronous Services and Clients for more information on asynchronous invocations.
In case you do not want to do any batch processing on your HTTP request invocations prior to invoking
them, there is another, more convenient approach that you can use to invoke your requests directly from
an Invocation.Builder instance. This approach is demonstrated in the next Java code listing.
1 Response response = invocationBuilder.get();

79

Client API

While short, the code in the example performs multiple actions. First, it will build the the request from the
invocationBuilder. The URI of request will be http://example.com/rest/resource/
helloworld?greeting="Hi%20World!" and the request will contain some-header: true
and Accept: text/plain headers. The request will then pass trough all configured request
filters ( AnotherClientFilter, ThirdClientFilter and FilterForExampleCom). Once
processed by the filters, the request will be sent to the remote resource. Let's say the resource then returns an
HTTP 200 message with a plain text response content that contains the value sent in the request greeting
query parameter. Now we can observe the returned response:
1 System.out.println(response.getStatus());
2 System.out.println(response.readEntity(String.class));
which will produce the following output to the console:
200
Hi World!
As we can see, the request was successfully processed (code 200) and returned an entity
(representation) is "Hi World!". Note that since we have configured a MyClientResponseFilter
in the resource target, when response.readEntity(String.class) gets called, the
response returned from the remote endpoint is passed through the response filter chain
(including the MyClientResponseFilter) and entity interceptor chain and at last
a proper MessageBodyReader [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/ext/
MessageBodyReader.html] is located to read the response content bytes from the response stream into a
Java String instance. Check Chapter 10, Filters and Interceptors to lear more about request and response
filters and entity interceptors.
Imagine now that you would like to invoke a POST request but without any query parameters. You would
just use the helloworldWebTarget instance created earlier and call the post() instead of get().

1 Response postResponse =
2
helloworldWebTarget.request(MediaType.TEXT_PLAIN_TYPE)
3
.post(Entity.entity("A string entity to be POSTed", MediaType.T

5.3.6. Example summary
The following code puts together the pieces used in the earlier examples.

Example 5.2. Using JAX-RS Client API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

ClientConfig clientConfig = new ClientConfig();
clientConfig.register(MyClientResponseFilter.class);
clientConfig.register(new AnotherClientFilter());
Client client = ClientBuilder.newClient(clientConfig);
client.register(ThirdClientFilter.class);
WebTarget webTarget = client.target("http://example.com/rest");
webTarget.register(FilterForExampleCom.class);
WebTarget resourceWebTarget = webTarget.path("resource");
WebTarget helloworldWebTarget = resourceWebTarget.path("helloworld");
WebTarget helloworldWebTargetWithQueryParam =
helloworldWebTarget.queryParam("greeting", "Hi World!");
Invocation.Builder invocationBuilder =

80

Client API

16
17
18
19
20
21

helloworldWebTargetWithQueryParam.request(MediaType.TEXT_PLAIN_TYPE);
invocationBuilder.header("some-header", "true");
Response response = invocationBuilder.get();
System.out.println(response.getStatus());
System.out.println(response.readEntity(String.class));

Now we can try to leverage the fluent API style to write this code in a more compact way.

Example 5.3. Using JAX-RS Client API fluently
1 Client client = ClientBuilder.newClient(new ClientConfig()
2
.register(MyClientResponseFilter.class)
3
.register(new AnotherClientFilter()));
4
5 String entity = client.target("http://example.com/rest")
6
.register(FilterForExampleCom.class)
7
.path("resource/helloworld")
8
.queryParam("greeting", "Hi World!")
9
.request(MediaType.TEXT_PLAIN_TYPE)
10
.header("some-header", "true")
11
.get(String.class);
The code above does the same thing except it skips the generic Response processing and directly requests
an entity in the last get(String.class) method call. This shortcut method let's you specify that (in
case the response was returned successfully with a HTTP 2xx status code) the response entity should be
returned as Java String type. This compact example demonstrates another advantage of the JAX-RS
client API. The fluency of JAX-RS Client API is convenient especially with simple use cases. Here is
another a very simple GET request returning a String representation (entity):
1 String responseEntity = ClientBuilder.newClient()
2
.target("http://example.com").path("resource/rest")
3
.request().get(String.class);

5.3.7. Setting ExecutorService and
ScheduledExecutorService
Some client invocations, like asynchronous or reactive, could lead to a need to start a new thread.
This is being done on provided ExecutorService or ScheduledExecutorService. ClientBuilder
has two methods, which can be used to define them: executorService(ExecutorService)
and scheduledExecutorService(ScheduledExecutorService). When specified, all
invocations which do require running on another thread, should be executed using provided services.
Default values do depend on the environment - in Java EE container, it
has to be ManagedExecutorService [http://docs.oracle.com/javaee/7/api/javax/enterprise/concurrent/
ManagedExecutorService.html] and ManagedScheduledExecutorService [http://docs.oracle.com/
javaee/7/api/javax/enterprise/concurrent/ManagedScheduledExecutorService.html], for Java SE it would
be ForkJoinPool.commonPool for Executor service and something undefined for Scheduled
executor service.

Example 5.4. Setting JAX-RS Client ExecutorService

1 ExecutorService myExecutorService = Executors.newCachedThreadPool();
2 Client client = ClientBuilder.newBuilder().executorService(myExecutorService).b

81

Client API

5.4. Java instances and types for
representations
All the Java types and representations supported by default on the Jersey server side for requests and
responses are also supported on the client side. For example, to process a response entity (or representation)
as a stream of bytes use InputStream as follows:
InputStream in = response.readEntity(InputStream.class);
... // Read from the stream
in.close();

Note that it is important to close the stream after processing so that resources are freed up.
To POST a file use a File instance as follows:
File f = ...
...
webTarget.request().post(Entity.entity(f, MediaType.TEXT_PLAIN_TYPE));

5.4.1. Adding support for new representations
The support for new application-defined representations as Java types requires the implementation
of the same JAX-RS entity provider extension interfaces as for the server side JAX-RS
API, namely MessageBodyReader [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
ext/MessageBodyReader.html] and MessageBodyWriter [https://jersey.github.io/apidocs-javax.jaxrs/2.1.5/javax/ws/rs/ext/MessageBodyWriter.html] respectively, for request and response entities (or
inbound and outbound representations).
Classes or implementations of the provider-based interfaces need to be registered as providers within the
JAX-RS or Jersey Client API components that implement Configurable contract (ClientBuilder,
Client, WebTarget or ClientConfig), as was shown in the earlier sections. Some media types
are provided in the form of JAX-RS Feature [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/
rs/core/Feature.html] a concept that allows the extension providers to group together multiple different
extension providers and/or configuration properties in order to simplify the registration and configuration
of the provided feature by the end users. For example, MoxyJsonFeature [https://jersey.github.io/
apidocs/2.28/jersey/org/glassfish/jersey/moxy/json/MoxyJsonFeature.html] can be register to enable and
configure JSON binding support via MOXy library.

5.5. Client Transport Connectors
By default, the transport layer in Jersey is provided by HttpUrlConnection. This
transport is implemented in Jersey via HttpUrlConnectorProvider [https://jersey.github.io/apidocs/2.28/
jersey/org/glassfish/jersey/client/HttpUrlConnector.html] that implements Jersey-specific Connector
[https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/client/spi/Connector.html] SPI. You can
implement and/or register your own Connector instance to the Jersey Client implementation, that

82

Client API

will replace the default HttpUrlConnection-based transport layer. Jersey provides several alternative
client transport connector implementations that are ready-to-use.

Table 5.1. List of Jersey Connectors
Transport framework

Jersey Connector
implementation

Maven dependency

Grizzly NIO framework

GrizzlyConnectorProvider
org.glassfish.jersey.connectors:jers
[https://jersey.github.io/
grizzly-connector
apidocs/2.28/jersey/
org/glassfish/jersey/
grizzly/connector/
GrizzlyConnectorProvider.html]

Apache HTTP client

ApacheConnectorProvider
org.glassfish.jersey.connectors:jers
[https://jersey.github.io/
apache-connector
apidocs/2.28/jersey/
org/glassfish/jersey/
apache/connector/
ApacheConnectorProvider.html]

Jetty HTTP client

JettyConnectorProvider
[https://jersey.github.io/
apidocs/2.28/jersey/org/
glassfish/jersey/jetty/connector/
JettyConnectorProvider.html]

Netty NIO framework

NettyConnectorProvider
org.glassfish.jersey.connectors:jers
[https://jersey.github.io/
netty-connector
apidocs/2.28/jersey/org/
glassfish/jersey/netty/connector/
NettyConnectorProvider.html]

JDK NIO client

JdkConnectorProvider
[https://jersey.github.io/
apidocs/2.28/jersey/org/
glassfish/jersey/jdk/connector/
JdkConnectorProvider.html]

org.glassfish.jersey.connectors:jers
jetty-connector

org.glassfish.jersey.connectors:jers
jdk-connector

Warning
Be aware of using other than default Connector implementation. There is an issue
handling HTTP headers in WriterInterceptor or MessageBodyWriter. If
you need to change header fields do not use nor ApacheConnectorProvider
nor GrizzlyConnectorProvider nor JettyConnectorProvider neither
NettyConnectorProvider. The issue for example applies to Jersey Multipart feature that
also modifies HTTP headers.
On the other hand, in the default transport connector, there are some restrictions on the
headers, that can be sent in the default configuration. HttpUrlConnectorProvider uses
HttpUrlConnection as an underlying connection implementation. This JDK class by default
restricts the use of following headers:
• Access-Control-Request-Headers
• Access-Control-Request-Method

83

Client API

• Connection (with one exception - Connection header with value Closed is allowed
by default)
• Content-Length
• Content-Transfer-Encoding• Host
• Keep-Alive
• Origin
• Trailer
• Transfer-Encoding
• Upgrade
• Via
• all the headers starting with SecThe underlying connection can be configured to permit all headers to be sent,
however this behaviour can be changed only by setting the system property
sun.net.http.allowRestrictedHeaders.

Example 5.5. Sending restricted headers with HttpUrlConnector
1
2
3
4
5
6
7
8
9

Client client = ClientBuilder.newClient();
System.setProperty("sun.net.http.allowRestricted

Response response = client.target(yourUri).path(
header("Origin", "http://example.com").
header("Access-Control-Request-Method", "POST").
get();

Note, that internally the HttpUrlConnection instances are pooled, so (un)setting the
property after already creating a target typically does not have any effect. The property influences
all the connections created after the property has been (un)set, but there is no guarantee, that your
request will use a connection created after the property change.
In a simple environment, setting the property before creating the first target is sufficient,
but in complex environments (such as application servers), where some poolable connections
might exist before your application even bootstraps, this approach is not 100% reliable and
we recommend using a different client transport connector, such as Apache Connector. These
limitations have to be considered especially when invoking CORS (Cross Origin Resource
Sharing) requests.
As indicated earlier, Connector [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/client/
spi/Connector.html] and ConnectorProvider [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/
jersey/client/spi/ConnectorProvider.html] contracts are Jersey-specific extension APIs that would only
work with Jersey and as such are not part of JAX-RS. Following example shows how to setup the custom
Grizzly Asynchronous HTTP Client based ConnectorProvider in a Jersey client instance:

84

Client API

1 ClientConfig clientConfig = new ClientConfig();
2 clientConfig.connectorProvider(new GrizzlyConnectorProvider());
3 Client client = ClientBuilder.newClient(clientConfig);
Client accepts as as a constructor argument a Configurable instance. Jersey implementation
of the Configurable provider for the client is ClientConfig. By using the Jersey
ClientConfig you can configure the custom ConnectorProvider into the ClientConfig.
The GrizzlyConnectorProvider is used as a custom connector provider in the example
above. Please note that the connector provider cannot be registered as a provider using
Configurable.register(...). Also, please note that in this API has changed in Jersey 2.5, where
the ConnectorProvider SPI has been introduced in order to decouple client initialization from the
connector instantiation. Starting with Jersey 2.5 it is therefore not possible to directly register Connector
instances in the Jersey ClientConfig [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/
client/ClientConfig.html]. The new ConnectorProvider SPI must be used instead to configure a
custom client-side transport connector.

5.6. Using client request and response filters
Filtering requests and responses can provide useful lower-level concept focused on a certain independent
aspect or domain that is decoupled from the application layer of building and sending requests, and
processing responses. Filters can read/modify the request URI, headers and entity or read/modify the
response status, headers and entity.
Jersey contains the following useful client-side filters (and features registering filters) that you may want
to use in your applications:
CsrfProtectionFilter
[https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/client/filter/
CsrfProtectionFilter.html]: Cross-site request forgery protection filter (adds X-Requested-By to each
state changing request).
EncodingFeature
[https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/client/filter/
EncodingFeature.html]: Feature that registers encoding filter which use registered ContentEncoder
[https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/spi/ContentEncoder.html]s to encode and
decode the communication. The encoding/decoding is performed in interceptor (you don't need to register
this interceptor). Check the javadoc of the EncodingFeature [https://jersey.github.io/apidocs/2.28/jersey/
org/glassfish/jersey/client/filter/EncodingFeature.html] in order to use it.
HttpAuthenticationFeature
[https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/client/
authentication/HttpAuthenticationFeature.html]: HTTP Authentication Feature (see ??? below).
Note that these features are provided by Jersey, but since they use and implement JAX-RS API, the features
should be portable and run in any JAX-RS implementation, not just Jersey. See Chapter 10, Filters and
Interceptors chapter for more information on filters and interceptors.

5.7. Closing connections
The underlying connections are opened for each request and closed after the response is received and entity
is processed (entity is read). See the following example:

Example 5.6. Closing connections
1
2
3
4
5

final WebTarget target = ... some web target
Response response = target.path("resource").request().get();
System.out.println("Connection is still open.");
System.out.println("string response: " + response.readEntity(String.class));
System.out.println("Now the connection is closed.");

85

Client API

If you don't read the entity, then you need to close the response manually by response.close().
Also if the entity is read into an InputStream [http://docs.oracle.com/javase/6/docs/api/java/io/
InputStream.html] (by response.readEntity(InputStream.class)), the connection stays
open until you finish reading from the InputStream. In that case, the InputStream or the Response
should be closed manually at the end of reading from InputStream.

5.8. Injections into client providers
In some cases you might need to inject some custom types into your client provider instance. JAX-RS types
do not need to be injected as they are passed as arguments into API methods. Injections into client providers
(filters, interceptor) are possible as long as the provider is registered as a class. If the provider is registered
as an instance then runtime will not inject the provider. The reason is that this provider instance might
be registered into multiple client configurations. For example one instance of ClientRequestFilter [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/ClientRequestFilter.html] can be registered
to two Client [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/Client.html]s.
To
solve
injection
of
a
custom
type
into
a
client
provider
instance
use ServiceLocatorClientProvider [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/client/
ServiceLocatorClientProvider.html] to extract ServiceLocator [https://hk2.java.net/apidocs/org/glassfish/
hk2/api/ServiceLocator.html] which can return the required injection. The following example shows how
to utilize ServiceLocatorClientProvider:

Example 5.7. ServiceLocatorClientProvider example

1 public static class MyRequestFilter implements ClientRequestFilter {
2
// this injection does not work as filter is registered as an instance:
3
// @Inject
4
// private MyInjectedService service;
5
6
@Override
7
public void filter(ClientRequestContext requestContext) throws IOException
8
// use ServiceLocatorClientProvider to extract HK2 ServiceLocator from
9
final ServiceLocator locator = ServiceLocatorClientProvider.getServiceL
10
11
// and ask for MyInjectedService:
12
final MyInjectedService service = locator.getService(MyInjectedService.
13
14
final String name = service.getName();
15
...
16
}
17 }
For
more
information
see
javadoc
of
ServiceLocatorClientProvider
[https://
jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/client/ServiceLocatorClientProvider.html] (and
javadoc of ServiceLocatorProvider [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/
ServiceLocatorProvider.html] which supports common JAX-RS components).

5.9. Securing a Client
This section describes how to setup SSL configuration on Jersey client (using JAXRS API). The SSL configuration is setup in ClientBuilder [https://jersey.github.io/apidocsjavax.jax-rs/2.1.5/javax/ws/rs/client/ClientBuilder.html]. The client builder contains methods for

86

Client API

definition of KeyStore [http://docs.oracle.com/javase/6/docs/api/java/security/KeyStore.html], TrustStore
[http://docs.oracle.com/javase/6/docs/api/java/security/TrustStore.html] or entire SslContext [http://
docs.oracle.com/javase/6/docs/api/javax/net/ssl/SslContext.html]. See the following example:

1 SSLContext ssl = ... your configured SSL context;
2 Client client = ClientBuilder.newBuilder().sslContext(ssl).build();
3 Response response = client.target("https://example.com/resource").request().get
The example above shows how to setup a custom SslContext to the ClientBuilder. Creating
a SslContext can be more difficult as you might need to init instance properly with the
protocol, KeyStore, TrustStore, etc. Jersey offers a utility SslConfigurator [https://jersey.github.io/
apidocs/2.28/jersey/org/glassfish/jersey/SslConfigurator.html] class that can be used to setup the
SslContext. The SslConfigurator can be configured based on standardized system properties
for SSL configuration, so for example you can configure the KeyStore file name using a environment
variable javax.net.ssl.keyStore and SslConfigurator will use such a variable to setup the
SslContext. See javadoc of SslConfigurator [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/
jersey/SslConfigurator.html] for more details. The following code shows how a SslConfigurator
can be used to create a custom SSL context.
1 SslConfigurator sslConfig = SslConfigurator.newInstance()
2
.trustStoreFile("./truststore_client")
3
.trustStorePassword("secret-password-for-truststore")
4
.keyStoreFile("./keystore_client")
5
.keyPassword("secret-password-for-keystore");
6
7 SSLContext sslContext = sslConfig.createSSLContext();
8 Client client = ClientBuilder.newBuilder().sslContext(sslContext).build();
Note that you can also setup KeyStore and TrustStore directly on a ClientBuilder instance
without wrapping them into the SslContext. However, if you setup a SslContext it will override
any previously defined KeyStore and TrustStore settings. ClientBuilder also offers a
method for defining a custom HostnameVerifier [http://docs.oracle.com/javase/6/docs/api/javax/net/ssl/
HostnameVerifier.html] implementation. HostnameVerifier implementations are invoked when
default host URL verification fails.

Important
A behaviour of HostnameVerifier [http://docs.oracle.com/javase/6/docs/api/javax/net/
ssl/HostnameVerifier.html] is dependent on an http client implementation.
HttpUrlConnectorProvider and ApacheConnectorProvider work properly, that
means that after the unsuccessful URL verification HostnameVerifier is called
and by means of it is possible to revalidate URL using a custom implementation of
HostnameVerifier and go on in a handskahe processing. JettyConnectorProvider
and GrizzlyConnectorProvider provide only host URL verification and throw a
CertificateException without any possibility to use custom HostnameVerifier.
Moreover, in case of JettyConnectorProvider there is a property
JettyClientProperties.ENABLE_SSL_HOSTNAME_VERIFICATION [https://jersey.github.io/
apidocs/2.28/jersey/org/glassfish/jersey/client/
JettyClientProperties.html#ENABLE_SSL_HOSTNAME_VERIFICATION] to disable an
entire host URL verification mechanism in a handshake.

Important
Note that to utilize HTTP with SSL it is necessary to utilize the “https” scheme.

87

Client API

Currently the default connector provider HttpUrlConnectorProvider [https://jersey.github.io/
apidocs/2.28/jersey/org/glassfish/jersey/client/HttpUrlConnector.html] provides connectors based on
HttpUrlConnection which implement support for SSL defined by JAX-RS configuration discussed
in this example.

5.9.1. Http Authentication Support
Jersey supports Basic and Digest HTTP Authentication.

Important
In
version
prior
to
Jersey
2.5
the
support
was
provided
by
org.glassfish.jersey.client.filter.HttpBasicAuthFilter
and
org.glassfish.jersey.client.filter.HttpDigestAuthFilter. Since Jersey
2.5 these filters are deprecated (and removed in 2.6) and both authentication methods are provided
by single Feature HttpAuthenticationFeature [https://jersey.github.io/apidocs/2.28/jersey/org/
glassfish/jersey/client/authentication/HttpAuthenticationFeature.html].
In
order
to
enable
http
authentication
support
in
Jersey
client
register
the HttpAuthenticationFeature [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/client/
authentication/HttpAuthenticationFeature.html]. This feature can provide both authentication methods,
digest and basic. Feature can work in the following modes:
• BASIC: Basic preemptive authentication. In preemptive mode the authentication information is send
always with each HTTP request. This mode is more usual than the following non-preemptive mode (if
you require BASIC authentication you will probably use this preemptive mode). This mode must be
combined with usage of SSL/TLS as the password is send only BASE64 encoded.
• BASIC NON-PREEMPTIVE:Basic non-preemptive authentication. In non-preemptive mode the
authentication information is added only when server refuses the request with 401 status code and
then the request is repeated with authentication information. This mode has negative impact on the
performance. The advantage is that it does not send credentials when they are not needed. This mode
must be combined with usage of SSL/TLS as the password is send only BASE64 encoded.
• DIGEST: Http digest authentication. Does not require usage of SSL/TLS.
• UNIVERSAL: Combination of basic and digest authentication. The feature works in non-preemptive
mode which means that it sends requests without authentication information. If 401 status code is
returned, the request is repeated and an appropriate authentication is used based on the authentication
requested in the response (defined in WWW-Authenticate HTTP header. The feature remembers
which authentication requests were successful for given URI and next time tries to preemptively
authenticate against this URI with latest successful authentication method.
To initialize the feature use static methods and builder of this feature. Example of building the feature in
Basic authentication mode:

1 HttpAuthenticationFeature feature = HttpAuthenticationFeature.basic("user", "su
Example of building the feature in basic non-preemptive mode:
1 HttpAuthenticationFeature feature = HttpAuthenticationFeature.basicBuilder()
2
.nonPreemptive().credentials("user", "superSecretPassword").build();
You can also build the feature without any default credentials:

1 HttpAuthenticationFeature feature = HttpAuthenticationFeature.basicBuilder().bu

88

Client API

In this case you need to supply username and password for each request using request properties:

1 Response response = client.target("http://localhost:8080/rest/homer/contact").r
2
.property(HTTP_AUTHENTICATION_BASIC_USERNAME, "homer")
3
.property(HTTP_AUTHENTICATION_BASIC_PASSWORD, "p1swd745").get();
This allows you to reuse the same client for authenticating with many different credentials.
See javadoc of the HttpAuthenticationFeature [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/
jersey/client/authentication/HttpAuthenticationFeature.html] for more details.

89

Chapter 6. Reactive JAX-RS Client API
Warning
Jersey 2.26 (JAX-RS 2.1 implementation) dropped Jersey-proprietary API in favor of JAX-RS
2.1 Reactive Client API.
Reactive client extension is quite a generic API allowing end users to utilize the popular reactive
programming model when using JAX-RS Client. The API is designed to be extensible, so any existing
reactive framework can integrate with it and there is build in support for CompletionStage. Along with
describing the API itself, this section also covers existing extension modules and provides hints to
implement a custom extension if needed.
If you are not familiar with the JAX-RS Client API, it is recommended that you see Chapter 5, Client API
where the basics of JAX-RS Client API along with some advanced techniques are described.

6.1. Motivation for Reactive Client Extension
The Problem
Imagine a travel agency whose information system consists of multiple basic services. These services
might be built using different technologies (JMS, EJB, WS, ...). For simplicity we presume that the services
can be consumed using REST interface via HTTP method calls (e.g. using a JAX-RS Client). We also
presume that the basic services we need to work with are:
• Customers service – provides information about customers of the travel agency.
• Destinations service – provides a list of visited and recommended destinations for an authenticated
customer.
• Weather service – provides weather forecast for a given destination.
• Quoting service – provides price calculation for a customer to travel to a recommended destination.
The task is to create a publicly available feature that would, for an authenticated user, display a list
of 10 last visited places and also display a list of 10 new recommended destinations including weather
forecast and price calculations for the user. Notice that some of the requests (to retrieve data) depend
on results of previous requests. E.g. getting recommended destinations depends on obtaining information
about the authenticated user first. Obtaining weather forecast depends on destination information, etc. This
relationship between some of the requests is an important part of the problem and an area where you can
take a real advantage of the reactive programming model.
One way how to obtain data is to make multiple HTTP method calls from the client (e.g. mobile device)
to all services involved and combine the retrieved data on the client. However, since the basic services are
available in the internal network only we'd rather create a public orchestration layer instead of exposing
all internal services to the outside world. The orchestration layer would expose only the desired operations
of the basic services to the public. To limit traffic and achieve lower latency we'd like to return all the
necessary information to the client in a single response.
The orchestration layer is illustrated in the Figure 6.1. The layer accepts requests from the outside and
is responsible of invoking multiple requests to the internal services. When responses from the internal

90

Reactive JAX-RS Client API

services are available in the orchestration layer they're combined into a single response that is sent back
to the client.

Figure 6.1. Travel Agency Orchestration Service

The next sections describe various approaches (using JAX-RS Client) how the orchestration layer can be
implemented.

A Naive Approach
The simplest way to implement the orchestration layer is to use synchronous approach. For this purpose
we can use JAX-RS Client Sync API (see Example 6.1, “Excerpt from a synchronous approach
while implementing the orchestration layer”). The implementation is simple to do, easy to read and
straightforward to debug.

Example 6.1. Excerpt from a synchronous approach while implementing the
orchestration layer
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

final WebTarget destination = ...;
final WebTarget forecast = ...;
// Obtain recommended destinations.
List recommended = Collections.emptyList();
try {
recommended = destination.path("recommended").request()
// Identify the user.
.header("Rx-User", "Sync")
// Return a list of destinations.
.get(new GenericType>() {});
} catch (final Throwable throwable) {
errors.offer("Recommended: " + throwable.getMessage());
}
// Forecasts. (depend on recommended destinations)
final Map forecasts = new HashMap<>();
for (final Destination dest : recommended) {
try {
forecasts.put(dest.getDestination(),

91

Reactive JAX-RS Client API

21
22
23
24
25 }

forecast.resolveTemplate("destination", dest.getDestination()).
} catch (final Throwable throwable) {
errors.offer("Forecast: " + throwable.getMessage());
}

The downside of this approach is it's slowness. You need to sequentially process all the independent
requests which means that you're wasting resources. You are needlessly blocking threads, that could be
otherwise used for some real work.
If you take a closer look at the example you can notice that at the moment when all the recommended
destinations are available for further processing we try to obtain forecasts for these destinations. Obtaining
a weather forecast can be done only for a single destination with a single request, so we need to make
10 requests to the Forecast service to get all the destinations covered. In a synchronous way this means
getting the forecasts one-by-one. When one response with a forecast arrives we can send another request
to obtain another one. This takes time. The whole process of constructing a response for the client can
be seen in Figure 6.2.
Let's try to quantify this with assigning an approximate time to every request we make to the internal
services. This way we can easily compute the time needed to complete a response for the client. For
example, obtaining
• Customer details takes 150 ms
• Recommended destinations takes 250 ms
• Price calculation for a customer and destination takes 170 ms (each)
• Weather forecast for a destination takes 330 ms (each)
When summed up, 5400 ms is approximately needed to construct a response for the client.

Figure 6.2. Time consumed to create a response for the client – synchronous way

Synchronous approach is better to use for lower number of requests (where the accumulated time doesn't
matter that much) or for a single request that depends on the result of previous operations.

Optimized Approach
The amount of time needed by the synchronous approach can be lowered by invoking independent requests
in parallel. We're going to use JAX-RS Client Async API to illustrate this approach. The implementation
in this case is slightly more difficult to get right because of the nested callbacks and the need to wait at
some points for the moment when all partial responses are ready to be processed. The implementation is
also a little bit harder to debug and maintain. The nested calls are causing a lot of complexity here. An

92

Reactive JAX-RS Client API

example of concrete Java code following the asynchronous approach can be seen in Example 6.2, “Excerpt
from an asynchronous approach while implementing the orchestration layer”.

Example 6.2. Excerpt from an asynchronous approach while implementing the
orchestration layer
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

final WebTarget destination = ...;
final WebTarget forecast = ...;

// Obtain recommended destinations. (does not depend on visited ones)
destination.path("recommended").request()
// Identify the user.
.header("Rx-User", "Async")
// Async invoker.
.async()
// Return a list of destinations.
.get(new InvocationCallback>() {
@Override
public void completed(final List recommended) {
final CountDownLatch innerLatch = new CountDownLatch(recommende

// Forecasts. (depend on recommended destinations)
final Map forecasts = Collections.synchronize
for (final Destination dest : recommended) {
forecast.resolveTemplate("destination", dest.getDestination
.async()
.get(new InvocationCallback() {
@Override
public void completed(final Forecast forecast)
forecasts.put(dest.getDestination(), foreca
innerLatch.countDown();
}

@Override
public void failed(final Throwable throwable) {
errors.offer("Forecast: " + throwable.getMe
innerLatch.countDown();
}
});
}

// Have to wait here for dependent requests ...
try {
if (!innerLatch.await(10, TimeUnit.SECONDS)) {
errors.offer("Inner: Waiting for requests to complete h
}
} catch (final InterruptedException e) {
errors.offer("Inner: Waiting for requests to complete has b
}
// Continue with processing.
}
@Override

93

Reactive JAX-RS Client API

49
50
51
52

public void failed(final Throwable throwable) {
errors.offer("Recommended: " + throwable.getMessage());
}
});

The example is a bit more complicated from the first glance. We provided an InvocationCallback
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/InvocationCallback.html] to async
get method. One of the callback methods (completed or failed) is called when the request
finishes. This is a pretty convenient way to handle async invocations when no nested calls are
present. Since we have some nested calls (obtaining weather forecasts) we needed to introduce a
CountDownLatch [http://docs.oracle.com/javase/6/docs/api/java/util/concurrent/CountDownLatch.html]
synchronization primitive as we use asynchronous approach in obtaining the weather forecasts as well.
The latch is decreased every time a request, to the Forecasts service, completes successfully or fails. This
indicates that the request actually finished and it is a signal for us that we can continue with processing
(otherwise we wouldn't have all required data to construct the response for the client). This additional
synchronization is something that was not present when taking the synchronous approach, but it is needed
here.
Also the error processing can not be written as it could be in an ideal case. The error handling is scattered in
too many places within the code, that it is quite difficult to create a comprehensive response for the client.
On the other hand taking asynchronous approach leads to code that is as fast as it gets. The resources are
used optimally (no waiting threads) to achieve quick response time. The whole process of constructing
the response for the client can be seen in Figure 6.3. It only took 730 ms instead of 5400 ms which we
encountered in the previous approach.

Figure 6.3. Time consumed to create a response for the client – asynchronous way

As you can guess, this approach, even with all it's benefits, is the one that is really hard to implement,
debug and maintain. It's a safe bet when you have many independent calls to make but it gets uglier with
an increasing number of nested calls.

Reactive Approach
Reactive approach is a way out of the so-called Callback Hell which you can encounter when dealing
with Java's Futures or invocation callbacks. Reactive approach is based on a data-flow concept and the
execution model propagate changes through the flow. An example of a single item in the data-flow chain
can be a JAX-RS Client HTTP method call. When the JAX-RS request finishes then the next item (or
the user code) in the data-flow chain is notified about the continuation, completion or error in the chain.
You're more describing what should be done next than how the next action in the chain should be triggered.

94

Reactive JAX-RS Client API

The other important part here is that the data-flows are composable. You can compose/transform multiple
flows into the resulting one and apply more operations on the result.
An example of this approach can be seen in Example 6.3, “Excerpt from a reactive approach while
implementing the orchestration layer”. The APIs would be described in more detail in the next sections.

Example 6.3. Excerpt from a reactive approach while implementing the
orchestration layer
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

final WebTarget destination = ...;
final WebTarget forecast = ...;
// Recommended places.
CompletionStage> recommended =
destination.path("recommended")
.request()
// Identify the user.
.header("Rx-User", "CompletionStage")
// Reactive invoker.
.rx()
// Return a list of destinations.
.get(new GenericType>() {})
.exceptionally(throwable -> {
errors.offer("Recommended: " + throwable.getMessage());
return Collections.emptyList();
});
// get Forecast for recommended destinations.
return recommended.thenCompose(destinations -> {

List> recommendations = destinations.stream
// For each destination, obtain a weather forecast ...
final CompletionStage forecastResult =
forecast.resolveTemplate("destination", destination.getDestination(
.request().rx().get(Forecast.class)
.exceptionally(throwable -> {
errors.offer("Forecast: " + throwable.getMessage());
return new Forecast(destination.getDestination(), "N/A"
});

//noinspection unchecked
return CompletableFuture.completedFuture(new Recommendation
// Set forecast for recommended des
.thenCombine(forecastResult, Recomm
}).collect(Collectors.toList());

// Transform List> to Compl
return sequence(recommendations);
});

As you can see the code achieves the same work as the previous two examples. It's more readable than
the pure asynchronous approach even though it's equally fast. It's as easy to read and implement as the
synchronous approach. The error processing is also better handled in this way than in the asynchronous
approach.

95

Reactive JAX-RS Client API

When dealing with a large amount of requests (that depend on each other) and when you need to compose/
combine the results of these requests, the reactive programming model is the right technique to use.

6.2. Usage and Extension Modules
Reactive Client API is part of the JAX-RS specification since version 2.1.
When you compare synchronous invocation of HTTP calls ( Example 6.4, “Synchronous invocation of
HTTP requests”)

Example 6.4. Synchronous invocation of HTTP requests
1 Response response = ClientBuilder.newClient()
2
.target("http://example.com/resource")
3
.request()
4
.get();
with asynchronous invocation (Example 6.5, “Asynchronous invocation of HTTP requests”)

Example 6.5. Asynchronous invocation of HTTP requests
1 Future response = ClientBuilder.newClient()
2
.target("http://example.com/resource")
3
.request()
4
.async()
5
.get();
it is apparent how to pretty conveniently modify the way how a request is invoked (from sync to async) only
by calling async method on an Invocation.Builder [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/
javax/ws/rs/client/Invocation.Builder.html].
Naturally, it'd be nice to copy the same pattern to allow invoking requests in a reactive way. Just instead
of async you'd call rx on an extension of Invocation.Builder, like in Example 6.6, “Reactive
invocation of HTTP requests”.

Example 6.6. Reactive invocation of HTTP requests
1 CompletionStage response = ClientBuilder.newClient()
2
.target("http://example.com/resource")
3
.request()
4
.rx()
5
.get();
The first reactive interface in the invocation chain is RxInvoker [https://jersey.github.io/apidocsjavax.jax-rs/2.1.5/javax/ws/rs/client/RxInvoker.html] which is very similar to SyncInvoker [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/SyncInvoker.html] and AsyncInvoker
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/AsyncInvoker.html]. It contains all
methods present in the two latter JAX-RS interfaces but the RxInvoker interface is more generic, so that
it can be extended and used in particular implementations taking advantage of various reactive libraries.
Extending this new interface in a particular implementation also preserves type safety which means that
you're not loosing type information when a HTTP method call returns an object that you want to process
further.
The method "rx()" in the example above is perfect example of that principle. It
returns CompletionStageRxInvoker [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/

96

Reactive JAX-RS Client API

CompletionStageRxInvoker.html], which extends RxInvoker [https://jersey.github.io/apidocs-javax.jaxrs/2.1.5/javax/ws/rs/client/RxInvoker.html].
As a user of the Reactive Client API you only need to keep in mind that you won't be working with
RxInvoker directly. You'd rather be working with an extension of this interface created for a particular
implementation and you don't need to be bothered much with why are things designed the way they are.

Note
To see how the RxInvoker should be extended, refer to Section 6.4, “Implementing Support
for Custom Reactive Libraries (SPI)”.
The important thing to notice here is that an extension of RxInvoker holds the type information and the
Reactive Client needs to know about this type to properly propagate it among the method calls you'll be
making. This is the reason why other interfaces (described bellow) are parametrized with this type.
In order to extend the API to be used with other reactive frameworks, RxInvokerProvider
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/RxInvokerProvider.html] needs to
be registered into the Client runtime:
1
2
3
4
5
6
7
8
9
10

Client client = ClientBuilder.newClient();
client.register(RxFlowableInvokerProvider.class);
Flowable responseFlowable =
client.target("http://jersey.java.net")
.request()
.rx(RxFlowableInvoker.class)
.get(String.class);
String responseString = responseFlowable.blockingFirst();

Dependencies
JAX-RS mandates support for CompletionStage, which doesn't required any other dependency and can
be used out of the box.
To add support for a particular library, see the Section 6.3, “Supported Reactive Libraries”.

Note
If you're not using Maven (or other dependency management tool) make sure to add also all
the transitive dependencies of Jersey client module and any other extensions (when used) on the
class-path.

6.3. Supported Reactive Libraries
There are already some available reactive (or reactive-like) libraries out there and Jersey brings support
for some of them out of the box. Jersey currently supports:
• RxJava (Observable)
• RxJava (Flowable)
• Guava (ListenableFuture and Futures)

97

Reactive JAX-RS Client API

6.3.1. RxJava – Observable
RxJava [https://github.com/ReactiveX/RxJava], contributed by Netflix, is probably the most advanced
reactive library for Java at the moment. It's used for composing asynchronous and event-based programs by
using observable sequences. It uses the observer pattern [http://en.wikipedia.org/wiki/Observer_pattern]
to support these sequences of data/events via it's Observable [http://reactivex.io/RxJava/javadoc//rx/
Observable.html] entry point class which implements the Reactive Pattern. Observable is actually the
parameter type in the RxJava's extension of RxInvoker [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/
javax/ws/rs/client/RxInvoker.html], called RxObservableInvoker [https://jersey.github.io/apidocs/2.28/
jersey/org/glassfish/jersey/client/rx/rxjava/RxObservableInvoker.html]. This means that the return type of
HTTP method calls is Observable in this case (accordingly parametrized).
Requests are by default invoked at the moment when a subscriber is subscribed to an observable (it's a cold
Observable). If not said otherwise a separate thread (JAX-RS Async Client requests) is used to obtain
data. This behavior can be overridden by providing an ExecutorService [http://docs.oracle.com/javase/6/
docs/api/java/util/concurrent/ExecutorService.html] when a reactive Client is created.

Usage
The extensibility is built-in JAX-RS Client API, so there are no special dependencies on Jersey Client API
other than the extension itself.

Example 6.7. Creating JAX-RS Client with RxJava reactive extension
1 // New Client
2 Client client = ClientBuilder.newClient();
3 client.register(RxObservableInvokerProvider.class);
An example of obtaining Observable with JAX-RS Response from a remote service can be seen in
Example 6.8, “Obtaining Observable from Jersey/RxJava Client”.

Example 6.8. Obtaining Observable from Jersey/RxJava Client

1 Observable observable = RxObservable.newClient()
2
.target("http://example.com
3
.request()
4
.rx(RxObservableInvoker.cla
5
.get();

Dependencies
The RxJava support is available as an extension module in Jersey. For Maven users, simply add the
following dependency to your pom.xml:

org.glassfish.jersey.ext.rx
jersey-rx-client-rxjava
2.28

After this step you can use the extended client right away. The dependency transitively adds the following
dependencies to your class-path as well: io.reactivex:rxjava.

98

Reactive JAX-RS Client API

Note
If you're not using Maven (or other dependency management tool) make sure
to add also all the transitive dependencies of this extension module (see jerseyrx-client-rxjava [https://jersey.github.io/project-info/2.28/jersey/project/project/jersey-rx-clientrxjava/dependencies.html]) on the class-path.

6.3.2. RxJava – Flowable
RxJava [https://github.com/ReactiveX/RxJava], contributed by Netflix, is probably the most advanced
reactive library for Java at the moment. It's used for composing asynchronous and event-based programs by
using observable sequences. It uses the observer pattern [http://en.wikipedia.org/wiki/Observer_pattern]
to support these sequences of data/events via it's Flowable [http://reactivex.io/RxJava/javadoc//rx/
Flowable.html] entry point class which implements the Reactive Pattern. Flowable is actually the
parameter type in the RxJava's extension of RxInvoker [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/
javax/ws/rs/client/RxInvoker.html], called RxFlowableInvoker [https://jersey.github.io/apidocs/2.28/
jersey/org/glassfish/jersey/client/rx/rxjava2/RxFlowableInvoker.html]. This means that the return type of
HTTP method calls is Flowable in this case (accordingly parametrized).
Requests are by default invoked at the moment when a subscriber is subscribed to a flowable (it's a cold
Flowable). If not said otherwise a separate thread (JAX-RS Async Client requests) is used to obtain
data. This behavior can be overridden by providing an ExecutorService [http://docs.oracle.com/javase/6/
docs/api/java/util/concurrent/ExecutorService.html] when a reactive Client is created.

Usage
The extensibility is built-in JAX-RS Client API, so there are no special dependencies on Jersey Client API
other than the extension itself.

Example 6.9. Creating JAX-RS Client with RxJava2 reactive extension
1 // New Client
2 Client client = ClientBuilder.newClient();
3 client.register(RxFlowableInvokerProvider.class);
An example of obtaining Flowable with JAX-RS Response from a remote service can be seen in
Example 6.8, “Obtaining Observable from Jersey/RxJava Client”.

Example 6.10. Obtaining Flowable from Jersey/RxJava Client
1 Flowable observable = RxObservable.newClient()
2
.target("http://example.com/resource")
3
.request()
4
.rx(RxFlowableInvoker.class)
5
.get();
6

Dependencies
The RxJava support is available as an extension module in Jersey. For Maven users, simply add the
following dependency to your pom.xml:


99

Reactive JAX-RS Client API

org.glassfish.jersey.ext.rx
jersey-rx-client-rxjava2
2.28

After this step you can use the extended client right away. The dependency transitively adds the following
dependencies to your class-path as well: io.reactivex:rxjava2.

Note
If you're not using Maven (or other dependency management tool) make sure to
add also all the transitive dependencies of this extension module (see jersey-rx-clientrxjava2 [https://jersey.github.io/project-info/2.28/jersey/project/project/jersey-rx-client-rxjava2/
dependencies.html]) on the class-path.

6.3.3. Guava – ListenableFuture and Futures
Guava [https://code.google.com/p/guava-libraries/], contributed by Google, also contains
a type, ListenableFuture [http://docs.guava-libraries.googlecode.com/git-history/v18.0/javadoc/com/
google/common/util/concurrent/ListenableFuture.html], which can be decorated with listeners that
are notified when the future completes. The ListenableFuture can be combined with
Futures [http://docs.guava-libraries.googlecode.com/git-history/v18.0/javadoc/com/google/common/util/
concurrent/Futures.html] to achieve asynchronous/event-based completion aware processing.
ListenableFuture is the parameter type in the Guava's extension of RxInvoker,
called RxListenableFutureInvoker [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/client/
rx/guava/RxListenableFutureInvoker.html]. This means that the return type of HTTP method calls is
ListenableFuture in this case (accordingly parametrized).
Requests
are
by
default
invoked
immediately.
If
not
said
otherwise
the Executors#newCachedThreadPool() [http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/
Executors.html#newCachedThreadPool--] pool is used to obtain a thread which processed the request.
This behavior can be overridden by providing a ExecutorService [http://docs.oracle.com/javase/6/docs/
api/java/util/concurrent/ExecutorService.html] when a Client is created.

Usage
The extensibility is built-in JAX-RS Client API, so there are no special dependencies on Jersey Client API
other than the extension itself.

Example 6.11. Creating Jersey/Guava Client
1 // New Client
2 Client client = ClientBuilder.newClient();
3 client.register(RxListenableFutureInvokerProvider.class);
An example of obtaining ListenableFuture with JAX-RS Response from a remote service can be
seen in Example 6.12, “Obtaining ListenableFuture from Jersey/Guava Client”.

Example 6.12. Obtaining ListenableFuture from Jersey/Guava Client
1
2 ListenableFuture response = client.target("http://jersey.java.net")
3
.request()

100

Reactive JAX-RS Client API

4
5
6

.rx(RxListenableFutureInvoker.class
.get();

Dependencies
The Reactive Jersey Client with Guava support is available as an extension module in Jersey. For Maven
users, simply add the following dependency to your pom.xml:

org.glassfish.jersey.ext.rx
jersey-rx-client-guava
2.28

After this step you can use the extended client right away. The dependency transitively adds the following
dependencies to your class-path as well: com.google.guava:guava.

Note
If you're not using Maven (or other dependency management tool) make sure
to add also all the transitive dependencies of this extension module (see jerseyrx-client-guava [https://jersey.github.io/project-info/2.28/jersey/project/project/jersey-rx-clientguava/dependencies.html]) on the class-path.

6.4. Implementing Support for Custom Reactive
Libraries (SPI)
In case you want to bring support for some other library providing Reactive Programming
Model into your application you can extend functionality of Reactive JAX-RS Client by
implementing RxInvokerProvider [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/
RxInvokerProvider.html], registering that implementation into the client runtime and then using
rx(Class) in your code.

Implement RxInvoker and RxInvokerProvider interfaces
The first step when implementing support for another reactive library is to implement
RxInvoker [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/RxInvoker.html]. JAXRS API itself contains one implementation, which will be used as an example: CompletionStageRxInvoker
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/CompletionStageRxInvoker.html].

Example 6.13. Extending RxIvoker
1 public interface CompletionStageRxInvoker extends RxInvoker {
2
@Override
3
public CompletionStage get();
4
5
@Override
6
public  CompletionStage get(Class responseType);
7
8
// ...
9 }

101

Reactive JAX-RS Client API

The important fact to notice is that the generic parameter of RxInvoker [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/RxInvoker.html] is CompletionStage [http://
docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletionStage.html] and also that the return
type is overriden to be always CompletionStage [http://docs.oracle.com/javase/8/docs/api/java/util/
concurrent/CompletionStage.html] with some generic param (Response [https://jersey.github.io/apidocsjavax.jax-rs/2.1.5/javax/ws/rs/core/Response.html]; or T).
After having the extended RxInvoker interface, the implementor has to provide RxInvokerProvider
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/RxInvokerProvider.html],
which
will be registered as an provider to a client instance.

Example 6.14. Extending RxInvokerProvider

1 public static class CompletionStageRxInvokerProvider implements RxInvokerProvid
2
@Override
3
public boolean isProviderFor(Class response =
client.target("http://jersey.java.net")
.request()
.rx(CompletionStageRxInvoker.class)
// Now we have an instance of CompletionStageRxInvoker returned f
// which is CompletionStageRxInvokerProvider in this particular s
.get();

102

Chapter 7. Representations and
Responses
7.1. Representations and Java Types
Previous sections on @Produces [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/
rs/Produces.html] and @Consumes [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
Consumes.html] annotations referred to media type of an entity representation. Examples above depicted
resource methods that could consume and/or produce String Java type for a number of different media
types. This approach is easy to understand and relatively straightforward when applied to simple use cases.
To cover also other cases, handling non-textual data for example or handling data stored in the file system,
etc., JAX-RS implementations are required to support also other kinds of media type conversions where
additional, non-String, Java types are being utilized. Following is a short listing of the Java types that are
supported out of the box with respect to supported media type:
• All media types (*/*)
• byte[]
• java.lang.String
• java.io.Reader (inbound only)
• java.io.File
• javax.activation.DataSource
• javax.ws.rs.core.StreamingOutput (outbound only)
• XML media types (text/xml, application/xml and application/...+xml)
• javax.xml.transform.Source
• javax.xml.bind.JAXBElement
• Application supplied JAXB classes (types annotated with @XmlRootElement [http://
docs.oracle.com/javase/6/docs/api/javax/xml/bind/annotation/XmlRootElement.html]
or@XmlType [http://docs.oracle.com/javase/6/docs/api/javax/xml/bind/annotation/XmlType.html])
• Form content (application/x-www-form-urlencoded)
• MultivaluedMap
• Plain text (text/plain)
• java.lang.Boolean
• java.lang.Character
• java.lang.Number
Unlike method parameters that are associated with the extraction of request parameters, the method
parameter associated with the representation being consumed does not require annotating. In other words

103

Representations and Responses

the representation (entity) parameter does not require a specific 'entity' annotation. A method parameter
without a annotation is an entity. A maximum of one such unannotated method parameter may exist since
there may only be a maximum of one such representation sent in a request.
The representation being produced corresponds to what is returned by the resource method. For example
JAX-RS makes it simple to produce images that are instance of File as follows:

Example 7.1. Using File with a specific media type to produce a response
1
2
3
4
5
6
7
8
9
10
11
12
13

@GET
@Path("/images/{image}")
@Produces("image/*")
public Response getImage(@PathParam("image") String image) {
File f = new File(image);
if (!f.exists()) {
throw new WebApplicationException(404);
}
String mt = new MimetypesFileTypeMap().getContentType(f);
return Response.ok(f, mt).build();
}

The File type can also be used when consuming a representation (request entity). In that case a temporary
file will be created from the incoming request entity and passed as a parameter to the resource method.
The Content-Type response header (if not set programmatically as described in the next section)
will be automatically set based on the media types declared by @Produces [https://jersey.github.io/
apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Produces.html] annotation. Given the following method, the most
acceptable media type is used when multiple output media types are allowed:
1
2
3
4
5

@GET
@Produces({"application/xml", "application/json"})
public String doGetAsXmlOrJson() {
...
}

If application/xml is the most acceptable media type defined by the request (e.g. by header
Accept:
application/xml), then the Content-Type response header will be set to
application/xml.

7.2. Building Responses
Sometimes it is necessary to return additional information in response to a HTTP request. Such information
may be built and returned using Response [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
core/Response.html] and Response.ResponseBuilder [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/
javax/ws/rs/core/Response.ResponseBuilder.html]. For example, a common RESTful pattern for the
creation of a new resource is to support a POST request that returns a 201 (Created) status code and a
Location header whose value is the URI to the newly created resource. This may be achieved as follows:

Example 7.2. Returning 201 status code and adding Location header in response
to POST request
1 @POST

104

Representations and Responses

2 @Consumes("application/xml")
3 public Response post(String content) {
4
URI createdUri = ...
5
create(content);
6
return Response.created(createdUri).build();
7 }
In the above no representation produced is returned, this can be achieved by building an entity as part of
the response as follows:

Example 7.3. Adding an entity body to a custom response
1
2
3
4
5
6
7

@POST
@Consumes("application/xml")
public Response post(String content) {
URI createdUri = ...
String createdContent = create(content);
return Response.created(createdUri).entity(Entity.text(createdContent)).build
}

Response building provides other functionality such as setting the entity tag and last modified date of the
representation.

7.3. WebApplicationException and Mapping
Exceptions to Responses
Previous section shows how to return HTTP responses, that are built up programmatically. It is possible
to use the very same mechanism to return HTTP errors directly, e.g. when handling exceptions in a trycatch block. However, to better align with the Java programming model, JAX-RS allows to define direct
mapping of Java exceptions to HTTP error responses.
The following example shows throwing CustomNotFoundException from a resource method in
order to return an error HTTP response to the client:

Example 7.4. Throwing exceptions to control response
1 @Path("items/{itemid}/")
2 public Item getItem(@PathParam("itemid") String itemid) {
3
Item i = getItems().get(itemid);
4
if (i == null) {
5
throw new CustomNotFoundException("Item, " + itemid + ", is not found");
6
}
7
8
return i;
9 }
This exception is an application specific exception that extends WebApplicationException [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/WebApplicationException.html] and builds a
HTTP response with the 404 status code and an optional message as the body of the response:

Example 7.5. Application specific exception implementation
1 public class CustomNotFoundException extends WebApplicationException {

105

Representations and Responses

2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 }

/**
* Create a HTTP 404 (Not Found) exception.
*/
public CustomNotFoundException() {
super(Responses.notFound().build());
}
/**
* Create a HTTP 404 (Not Found) exception.
* @param message the String that is the entity of the 404 response.
*/
public CustomNotFoundException(String message) {
super(Response.status(Responses.NOT_FOUND).
entity(message).type("text/plain").build());
}

In other cases it may not be appropriate to throw instances of WebApplicationException [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/WebApplicationException.html],
or
classes
that extend WebApplicationException [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
WebApplicationException.html], and instead it may be preferable to map an existing
exception to a response. For such cases it is possible to use a custom exception
mapping provider. The provider must implement the ExceptionMapper
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/ext/ExceptionMapper.html] interface. For
example, the following maps the EntityNotFoundException [http://docs.oracle.com/javaee/5/api/javax/
persistence/EntityNotFoundException.html] to a HTTP 404 (Not Found) response:

Example 7.6. Mapping generic exceptions to responses

1 @Provider
2 public class EntityNotFoundMapper implements ExceptionMapper [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
ext/MessageBodyReader.html] and the other one for handling the outbound entity Java-to-representation
serialization - MessageBodyWriter [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
ext/MessageBodyWriter.html]. A MessageBodyReader, as the name suggests, is an extension
that supports reading the message body representation from an input stream and converting the data into
an instance of a specific Java type. A MessageBodyWriter is then responsible for converting a
message payload from an instance of a specific Java type into a specific representation format that is sent
over the wire to the other party as part of an HTTP message exchange. Both of these providers can be used
to provide message payload serialization and de-serialization support on the server as well as the client
side. A message body reader or writer is always used whenever a HTTP request or response contains an
entity and the entity is either requested by the application code (e.g. injected as a parameter of JAX-RS
resource method or a response entity read on the client from a Response [https://jersey.github.io/apidocsjavax.jax-rs/2.1.5/javax/ws/rs/core/Response.html]) or has to be serialized and sent to the other party (e.g.
an instance returned from a JAX-RS resource method or a request entity sent by a JAX-RS client).

8.2. How to Write Custom Entity Providers
A best way how to learn about entity providers is to walk through an example
of writing one. Therefore we will describe here the process of implementing
a custom MessageBodyWriter [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/ext/
MessageBodyWriter.html] and MessageBodyReader [https://jersey.github.io/apidocs-javax.jaxrs/2.1.5/javax/ws/rs/ext/MessageBodyReader.html] using a practical example. Let's first setup the stage
by defining a JAX-RS resource class for the server side story of our application.

Example 8.1. Example resource class
1 @Path("resource")

109

JAX-RS Entity Providers

2 public class MyResource {
3
@GET
4
@Produces("application/xml")
5
public MyBean getMyBean() {
6
return new MyBean("Hello World!", 42);
7
}
8
9
@POST
10
@Consumes("application/xml")
11
public String postMyBean(MyBean myBean) {
12
return myBean.anyString;
13
}
14 }
The resource class defines GET and POST resource methods. Both methods work with an entity that is
an instance of MyBean.
The MyBean class is defined in the next example:

Example 8.2. MyBean entity class
1 @XmlRootElement
2 public class MyBean {
3
@XmlElement
4
public String anyString;
5
@XmlElement
6
public int anyNumber;
7
8
public MyBean(String anyString, int anyNumber) {
9
this.anyString = anyString;
10
this.anyNumber = anyNumber;
11
}
12
13
// empty constructor needed for deserialization by JAXB
14
public MyBean() {
15
}
16
17
@Override
18
public String toString() {
19
return "MyBean{" +
20
"anyString='" + anyString + '\'' +
21
", anyNumber=" + anyNumber +
22
'}';
23
}
24 }

8.2.1. MessageBodyWriter
The MyBean is a JAXB-annotated POJO. In GET resource method we return the instance of MyBean and
we would like Jersey runtime to serialize it into XML and write it as an entity body to the response output
stream. We design a custom MessageBodyWriter that can serialize this POJO into XML. See
the following code sample:

110

JAX-RS Entity Providers

Note
Please note, that this is only a demonstration of how to write a custom entity provider. Jersey
already contains default support for entity providers that can serialize JAXB beans into XML.

Example 8.3. MessageBodyWriter example

1 @Produces("application/xml")
2 public class MyBeanMessageBodyWriter implements MessageBodyWriter {
3
4
@Override
5
public boolean isWriteable(Class type, Type genericType,
6
Annotation[] annotations, MediaType mediaType) {
7
return type == MyBean.class;
8
}
9
10
@Override
11
public long getSize(MyBean myBean, Class type, Type genericType,
12
Annotation[] annotations, MediaType mediaType) {
13
// deprecated by JAX-RS 2.0 and ignored by Jersey runtime
14
return -1;
15
}
16
17
@Override
18
public void writeTo(MyBean myBean,
19
Class type,
20
Type genericType,
21
Annotation[] annotations,
22
MediaType mediaType,
23
MultivaluedMap httpHeaders,
24
OutputStream entityStream)
25
throws IOException, WebApplicationException {
26
27
try {
28
JAXBContext jaxbContext = JAXBContext.newInstance(MyBean.class);
29
30
// serialize the entity myBean to the entity output stream
31
jaxbContext.createMarshaller().marshal(myBean, entityStream);
32
} catch (JAXBException jaxbException) {
33
throw new ProcessingException(
34
"Error serializing a MyBean to the output stream", jaxbExceptio
35
}
36
}
37 }
The MyBeanMessageBodyWriter implements the MessageBodyWriter interface that
contains three methods. In the next sections we'll explore these methods more closely.

8.2.1.1. MessageBodyWriter.isWriteable
A method isWriteable should return true if the MessageBodyWriter is able to write the given
type. Method does not decide only based on the Java type of the entity but also on annotations attached
to the entity and the requested representation media type.

111

JAX-RS Entity Providers

Parameters type and genericType both define the entity, where type is a raw Java type (for example,
a java.util.List class) and genericType is a ParameterizedType [http://docs.oracle.com/
javase/6/docs/api/java/lang/reflect/ParameterizedType.html] including generic information (for example
List).
Parameter annotations contains annotations that are either attached to the resource method and/or
annotations that are attached to the entity by building response like in the following piece of code:

Example 8.4. Example of assignment of annotations to a response entity
1 @Path("resource")
2 public static class AnnotatedResource {
3
4
@GET
5
public Response get() {
6
Annotation annotation = AnnotatedResource.class
7
.getAnnotation(Path.class);
8
return Response.ok()
9
.entity("Entity", new Annotation[] {annotation}).build();
10
}
11 }
In the example above, the MessageBodyWriter would get annotations parameter containing
a JAX-RS @GET annotation as it annotates the resource method and also a @Path annotation as it is
passed in the response (but not because it annotates the resource; only resource method annotations
are included). In the case of MyResource and method getMyBean the annotations would contain
the @GET [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/GET.html] and the @Produces
[https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/Produces.html] annotation.
The last parameter of the isWriteable method is the mediaType which is the media type attached
to the response entity by annotating the resource method with a @Produces annotation or the request
media type specified in the JAX-RS Client API. In our example, the media type passed to providers for
the resource MyResource and method getMyBean would be "application/xml".
In our implementation of the isWriteable method, we just check that the type is MyBean. Please note,
that this method might be executed multiple times by Jersey runtime as Jersey needs to check whether this
provider can be used for a particular combination of entity Java type, media type, and attached annotations,
which may be potentially a performance hog. You can limit the number of execution by properly defining
the @Produces annotation on the MessageBodyWriter. In our case thanks to @Produces
annotation, the provider will be considered as writeable (and the method isWriteable might be
executed) only if the media type of the outbound message is "application/xml". Additionally, the
provider will only be considered as possible candidate and its isWriteable method will be executed,
if the generic type of the provider is either a sub class or super class of type parameter.

8.2.1.2. MessageBodyWriter.writeTo
Once a message body writer is selected as the most appropriate (see the Section 8.3, “Entity Provider
Selection” for more details on entity provider selection), its writeTo method is invoked. This method
receives parameters with the same meaning as in isWriteable as well as a few additional ones.
In addition to the parameters already introduced, the writeTo method defies also httpHeaders
parameter, that contains HTTP headers associated with the outbound message.

112

JAX-RS Entity Providers

Note
When a MessageBodyWriter is invoked, the headers still can be modified in this
point and any modification will be reflected in the outbound HTTP message being sent. The
modification of headers must however happen before a first byte is written to the supplied output
stream.
Another new parameter, myBean, contains the entity instance to be serialized (the type of entity
corresponds to generic type of MessageBodyWriter). Related parameter entityStream
contains the entity output stream to which the method should serialize the entity. In our case we use JAXB
to marshall the entity into the entityStream. Note, that the entityStream is not closed at the end
of method; the stream will be closed by Jersey.

Important
Do not close the entity output stream
MessageBodyWriter implementation.

in

the

writeTo

method

of

your

8.2.1.3. MessageBodyWriter.getSize
The method is deprecated since JAX-RS 2.0 and Jersey 2 ignores the return value. In JAX-RS 1.0
the method could return the size of the entity that would be then used for "Content-Length" response
header. In Jersey 2.0 the "Content-Length" parameter is computed automatically using an internal
outbound entity buffering. For details about configuration options of outbound entity buffering see the
javadoc of MessageProperties [https://jersey.github.io/apidocs/2.28/jersey/org/glassfish/jersey/message/
MessageProperties.html], property OUTBOUND_CONTENT_LENGTH_BUFFER which configures the
size of the buffer.

Note
You can disable the Jersey outbound entity buffering by setting the buffer size to 0.

8.2.1.4. Testing a MessageBodyWriter
Before testing the MyBeanMessageBodyWriter, the writer must be registered as a custom JAX-RS
extension provider. It should either be added to your application ResourceConfig [https://jersey.github.io/
apidocs/2.28/jersey/org/glassfish/jersey/server/ResourceConfig.html], or returned from your custom
Application [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/core/Application.html] subclass, or annotated with @Provider [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/ext/
Provider.html] annotation to leverage JAX-RS provider auto-discovery feature.
After registering the MyBeanMessageBodyWriter and MyResource class in our application, the
request can be initiated (in this example from Client API).

Example 8.5. Client code testing MyBeanMessageBodyWriter
1
2
3
4
5
6
7

WebTarget webTarget = // initialize web target to the context root
// of example application
Response response = webTarget.path("resource")
.request(MediaType.APPLICATION_XML).get();
System.out.println(response.getStatus());
String myBeanXml = response.readEntity(String.class);
System.out.println(myBeanXml);

113

JAX-RS Entity Providers

The client code initiates the GET which will be matched to the resource
MyResource.getMyBean(). The response entity is de-serialized as a String.

method

The result of console output is:

Example 8.6. Result of MyBeanMessageBodyWriter test
200

Hello World!42
The returned status is 200 and the entity is stored in the response in a XML format. Next, we will look at
how the Jersey de-serializes this XML document into a MyBean consumed by our POST resource method.

8.2.2. MessageBodyReader
In order to de-serialize the entity of MyBean on the server or the client, we need to implement
a custom MessageBodyReader [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/ext/
MessageBodyReader.html].

Note
Please note, that this is only a demonstration of how to write a custom entity provider. Jersey
already contains default support for entity providers that can serialize JAXB beans into XML.
Our MessageBodyReader implementation is listed in Example 8.7, “MessageBodyReader
example”.

Example 8.7. MessageBodyReader example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

public static class MyBeanMessageBodyReader
implements MessageBodyReader {
@Override
public boolean isReadable(Class type, Type genericType,
Annotation[] annotations, MediaType mediaType) {
return type == MyBean.class;
}
@Override
public MyBean readFrom(Class type,
Type genericType,
Annotation[] annotations, MediaType mediaType,
MultivaluedMap httpHeaders,
InputStream entityStream)
throws IOException, WebApplicationException {
try {
JAXBContext jaxbContext = JAXBContext.newInstance(MyBean.class);
MyBean myBean = (MyBean) jaxbContext.createUnmarshaller()
.unmarshal(entityStream);
return myBean;
} catch (JAXBException jaxbException) {
throw new ProcessingException("Error deserializing a MyBean.",
jaxbException);

114

JAX-RS Entity Providers

26
27 }
28 }

}

It is obvious that the MessageBodyReader interface is similar to MessageBodyWriter.
In the next couple of sections we will explore it's API methods.

8.2.2.1. MessageBodyReader.isReadable
It defines the method isReadable() which has a very simliar meaning as method isWriteable()
in MessageBodyWriter. The method returns true if it is able to de-serialize the given type. The
annotations parameter contains annotations that are attached to the entity parameter in the resource
method. In our POST resource method postMyBean the entity parameter myBean is not annotated,
therefore no annotation will be passed to the isReadable. The mediaType parameter contains the entity
media type. The media type, in our case, must be consumable by the POST resource method, which
is specified by placing a JAX-RS @Consumes [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/
ws/rs/Consumes.html] annotation to the method. The resource method postMyBean() is annotated
with @Consumes("application/xml"), therefore for purpose of de-serialization of entity for the
postMyBean() method, only requests with entities represented as "application/xml" media type
will match the method. However, this method might be executed for for entity types that are sub classes
or super classes of the declared generic type on the MessageBodyReader will be also considered.
It is a responsibility of the isReadable method to decide whether it is able to de-serialize the entity and
type comparison is one of the basic decision steps.

Tip
In order to reduce number of isReadable executions, always define correctly the consumable
media type(s) with the @Consumes annotation on your custom MessageBodyReader.

8.2.2.2. MessageBodyReader.readFrom
The readForm() method gets the parameters with the same meaning as in isReadable(). The
additional entityStream parameter provides a handle to the entity input stream from which the entity
bytes should be read and de-serialized into a Java entity which is then returned from the method. Our
MyBeanMessageBodyReader de-serializes the incoming XML data into an instance of MyBean using
JAXB.

Important
Do not close the entity input stream in your MessageBodyReader implementation. The
stream will be automatically closed by Jersey runtime.

8.2.2.3. Testing a MessageBodyWriter
Now let's send a test request using the JAX-RS Client API.

Example 8.8. Testing MyBeanMessageBodyReader
1
2
3
4
5
6

final MyBean myBean = new MyBean("posted MyBean", 11);
Response response = webTarget.path("resource").request("application/xml")
.post(Entity.entity(myBean, "application/xml"));
System.out.println(response.getStatus());
final String responseEntity = response.readEntity(String.class);

115

JAX-RS Entity Providers

7 System.out.println(responseEntity);
8
The console output is:

Example 8.9. Result of testing MyBeanMessageBodyReader
200
posted MyBean

8.2.2.4. Using Entity Providers with JAX-RS Client API
Both, MessageBodyReader and MessageBodyWriter can be registered in a
configuration of JAX-RS Client API components typically without any need to change their code. The
example Example 8.10, “MessageBodyReader registered on a JAX-RS client” is a variation on the
Example 8.5, “Client code testing MyBeanMessageBodyWriter” listed in one of the previous sections.

Example 8.10. MessageBodyReader registered on a JAX-RS client
1
2
3
4
5
6
7
8

Client client = ClientBuilder.newBuilder()
.register(MyBeanMessageBodyReader.class).build();
Response response = client.target("http://example/comm/resource")
.request(MediaType.APPLICATION_XML).get();
System.out.println(response.getStatus());
MyBean myBean = response.readEntity(MyBean.class);
System.out.println(myBean);

The code above registers MyBeanMessageBodyReader to the Client [https://jersey.github.io/
apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/Client.html] configuration using a ClientBuilder [https://
jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/client/ClientBuilder.html] which means that the
provider will be used for any WebTarget [https://jersey.github.io/apidocs-javax.jax-rs/2.1.5/javax/ws/rs/
client/WebTarget.html] produced by the client instance.

Note
You could also register the JAX-RS entity (and any other) providers to individual WebTarget
instances produced by the client.
Then, using the fluent chain of method invocations, a resource target pointing to our MyResource
is defined, a HTTP GET request is invoked. The response entity is then read as an instance of a
MyBean type by invoking the response.readEntity method, that internally locates the registered
MyBeanMessageBodyReader and uses it for entity de-serialization.
The console output for the example is:

Example 8.11. Result of client code execution
200
MyBean{anyString='Hello World!', anyNumber=42}

8.3. Entity Provider Selection
Usually there are many entity providers registered on the server or client side (be default there must
be at least providers mandated by the JAX-RS specification, such as providers for primitive types, byte

116

JAX-RS Entity Providers

array, JAXB beans, etc.). JAX-RS defines an algorithm for selecting the most suitable provider for entity
processing. This algorithm works with information such as entity Java type and on-the-wire media type
representation of entity, and searches for the most suitable entity provider from the list of available
providers based on the supported media type declared on each provider (defined by @Produces or
@Consumes on the provider class) as well as based on the generic type declaration of the available
providers. When a list of suitable candidate entity providers is selected and sorted based on the rules
defined in JAX-RS specification, a JAX-RS runtime then it invokes isReadable or isWriteable
method respectively on each provider in the list until a first provider is found that returns true. This
provider is then used to process the entity.
The following steps describe the algorithm for selecting a MessageBodyWriter (extracted from
JAX-RS with little modifications). The steps refer to the previously discussed example application. The
MessageBodyWriter is searched for purpose of deserialization of MyBean entity returned from
the method getMyBean. So, type is MyBean and media type "application/xml". Let's assume the
runtime contains also registered providers, namely:
A: @Produces("application/*") with generic type