Links: Table of Contents | Single HTML

Jersey 2.13 User Guide


Table of Contents

Preface
1. Getting Started
1.1. Creating a New Project from Maven Archetype
1.2. Exploring the Newly Created Project
1.3. Running the Project
1.4. Creating a JavaEE Web Application
1.5. Creating a Web Application that can be deployed on Heroku
1.5.1. Deploy it on Heroku
1.6. Exploring Other Jersey Examples
2. Modules and dependencies
2.1. Java SE Compatibility
2.2. Introduction to Jersey dependencies
2.3. Common Jersey Use Cases
2.3.1. Servlet based application on Glassfish
2.3.2. Servlet based server-side application
2.3.3. Client application on JDK
2.3.4. Server-side application on supported containers
2.4. List of modules
3. JAX-RS Application, Resources and Sub-Resources
3.1. Root Resource Classes
3.1.1. @Path
3.1.2. @GET, @PUT, @POST, @DELETE, ... (HTTP Methods)
3.1.3. @Produces
3.1.4. @Consumes
3.2. Parameter Annotations (@*Param)
3.3. Sub-resources
3.4. Life-cycle of Root Resource Classes
3.5. Rules of Injection
3.6. Use of @Context
3.7. Programmatic resource model
4. Application Deployment and Runtime Environments
4.1. Introduction
4.2. JAX-RS Application Model
4.3. Auto-Discoverable Features
4.3.1. Configuring Feature Auto-discovery Mechanism
4.4. Configuring the Classpath Scanning
4.5. Java SE Deployment Environments
4.5.1. HTTP servers
4.6. Creating programmatic JAX-RS endpoint
4.7. Servlet-based Deployment
4.7.1. Servlet 2.x Container
4.7.2. Servlet 3.x Container
4.7.3. Jersey Servlet container modules
4.8. Java EE Platform
4.8.1. Managed Beans
4.8.2. Context and Dependency Injection (CDI)
4.8.3. Enterprise Java Beans (EJB)
4.8.4. Java EE Servers
4.9. OSGi
4.9.1. Enabling the OSGi shell in Glassfish
4.9.2. WAB Example
4.9.3. HTTP Service Example
4.10. Other Environments
4.10.1. Oracle Java Cloud Service
5. Client API
5.1. Uniform Interface Constraint
5.2. Ease of use and reusing JAX-RS artifacts
5.3. Overview of the Client API
5.3.1. Getting started with the client API
5.3.2. Creating and configuring a Client instance
5.3.3. Targeting a web resource
5.3.4. Identifying resource on WebTarget
5.3.5. Invoking a HTTP request
5.3.6. Example summary
5.4. Java instances and types for representations
5.4.1. Adding support for new representations
5.5. Client Transport Connectors
5.6. Using client request and response filters
5.7. Closing connections
5.8. Injections into client providers
5.9. Securing a Client
5.9.1. Http Authentication Support
6. Representations and Responses
6.1. Representations and Java Types
6.2. Building Responses
6.3. WebApplicationException and Mapping Exceptions to Responses
6.4. Conditional GETs and Returning 304 (Not Modified) Responses
7. JAX-RS Entity Providers
7.1. Introduction
7.2. How to Write Custom Entity Providers
7.2.1. MessageBodyWriter
7.2.2. MessageBodyReader
7.3. Entity Provider Selection
7.4. Jersey MessageBodyWorkers API
7.5. Default Jersey Entity Providers
8. Support for Common Media Type Representations
8.1. JSON
8.1.1. Approaches to JSON Support
8.1.2. MOXy
8.1.3. Java API for JSON Processing (JSON-P)
8.1.4. Jackson (1.x and 2.x)
8.1.5. Jettison
8.1.6. @JSONP - JSON with Padding Support
8.2. XML
8.2.1. Low level XML support
8.2.2. Getting started with JAXB
8.2.3. POJOs
8.2.4. Using custom JAXBContext
8.2.5. MOXy
8.3. Multipart
8.3.1. Overview
8.3.2. Client
8.3.3. Server
9. Filters and Interceptors
9.1. Introduction
9.2. Filters
9.2.1. Server filters
9.2.2. Client filters
9.3. Interceptors
9.4. Filter and interceptor execution order
9.5. Name binding
9.6. Dynamic binding
9.7. Priorities
10. Asynchronous Services and Clients
10.1. Asynchronous Server API
10.1.1. Asynchronous Server-side Callbacks
10.1.2. Chunked Output
10.2. Client API
10.2.1. Asynchronous Client Callbacks
10.2.2. Chunked input
11. URIs and Links
11.1. Building URIs
11.2. Resolve and Relativize
11.3. Link
12. Declarative Hyperlinking
12.1. Dependency
12.2. Links in Representations
12.3. Binding Template Parameters
12.4. Conditional Link Injection
12.5. List of Link Injection
12.6. Link Headers
12.7. Configure and register
13. Programmatic API for Building Resources
13.1. Introduction
13.2. Programmatic Hello World example
13.2.1. Deployment of programmatic resources
13.3. Additional examples
13.4. Model processors
14. Server-Sent Events (SSE) Support
14.1. What are Server-Sent Events
14.2. When to use Server-Sent Events
14.3. Jersey Server-Sent Events API
14.4. Implementing SSE support in a JAX-RS resource
14.4.1. Simple SSE resource method
14.4.2. Broadcasting with Jersey SSE
14.5. Consuming SSE events with Jersey clients
14.5.1. Reading SSE events with EventInput
14.5.2. Asynchronous SSE processing with EventSource
15. Security
15.1. Securing server
15.1.1. SecurityContext
15.1.2. Authorization - securing resources
15.2. Client Security
15.3. OAuth Support
15.3.1. OAuth 1
15.3.2. OAuth 2 Support
16. WADL Support
16.1. WADL introduction
16.2. Configuration
16.3. Extended WADL support
17. Bean Validation Support
17.1. Bean Validation Dependencies
17.2. Enabling Bean Validation in Jersey
17.3. Configuring Bean Validation Support
17.4. Validating JAX-RS resources and methods
17.4.1. Constraint Annotations
17.4.2. Annotation constraints and Validators
17.4.3. Entity Validation
17.4.4. Annotation Inheritance
17.5. @ValidateOnExecution
17.6. Injecting
17.7. Error Reporting
17.7.1. ValidationError
17.8. Example
18. Entity Data Filtering
18.1. Enabling and configuring Entity Filtering in your application
18.2. Components used to describe Entity Filtering concepts
18.3. Using custom annotations to filter entities
18.3.1. Server-side Entity Filtering
18.3.2. Client-side Entity Filtering
18.4. Role-based Entity Filtering using (javax.annotation.security) annotations
18.5. Entity Filtering based on dynamic and configurable query parameters
18.6. Defining custom handling for entity-filtering annotations
18.7. Supporting Entity Data Filtering in custom entity providers or frameworks
18.8. Modules with support for Entity Data Filtering
18.9. Examples
19. MVC Templates
19.1. Viewable
19.2. @Template
19.2.1. Annotating Resource methods
19.2.2. Annotating Resource classes
19.3. Absolute vs. Relative template reference
19.3.1. Relative template reference
19.3.2. Absolute template reference
19.4. Handling errors with MVC
19.4.1. MVC & Bean Validation
19.5. Registration and Configuration
19.6. Supported templating engines
19.6.1. Mustache
19.6.2. Freemarker
19.6.3. JSP
19.7. Writing Custom Templating Engines
19.8. Other Examples
20. Monitoring and Diagnostics
20.1. Monitoring Jersey Applications
20.1.1. Introduction
20.1.2. Event Listeners
20.2. Tracing Support
20.2.1. Configuration options
20.2.2. Tracing Log
20.2.3. Configuring tracing support via HTTP request headers
20.2.4. Format of the HTTP response headers
20.2.5. Tracing Examples
21. Custom Injection and Lifecycle Management
21.1. Implementing Custom Injection Provider
21.2. Defining Custom Injection Annotation
21.3. Custom Life Cycle Management
22. Spring DI
22.1. Dependencies
22.2. Registration and Configuration
22.3. Example
23. Jersey Test Framework
23.1. Basics
23.2. Supported Containers
23.3. Running TestNG Tests
23.4. Advanced features
23.4.1. JerseyTest Features
23.4.2. External container
23.4.3. Test Client configuration
23.4.4. Accessing the logged test records programmatically
23.5. Parallel Testing with Jersey Test Framework
24. Building and Testing Jersey
24.1. Checking Out the Source
24.2. Building the Source
24.3. Testing
24.4. Using NetBeans
25. Migration Guide
25.1. Migrating from Jersey 2.11 to 2.12
25.1.1. Release 2.12 Highlights
25.1.2. Breaking Changes
25.2. Migrating from Jersey 2.10 to 2.11
25.2.1. Release 2.11 Highlights
25.3. Migrating from Jersey 2.9 to 2.10
25.3.1. Removed deprecated APIs
25.4. Migrating from Jersey 2.8 to 2.9
25.4.1. Release 2.9 Highlights
25.4.2. Changes
25.5. Migrating from Jersey 2.7 to 2.8
25.5.1. Changes
25.6. Migrating from Jersey 2.6 to 2.7
25.6.1. Changes
25.7. Migrating from Jersey 2.5.1 to 2.6
25.7.1. Guava and ASM have been embedded
25.7.2. New deprecated APIs / internal classes
25.7.3. Removed deprecated APIs
25.8. Migrating from Jersey 2.5 to 2.5.1
25.9. Migrating from Jersey 2.4.1 to 2.5
25.9.1. Client-side API and SPI changes
25.9.2. Other changes
25.10. Migrating from Jersey 2.4 to 2.4.1
25.11. Migrating from Jersey 2.3 to 2.4
25.12. Migrating from Jersey 2.0, 2.1 or 2.2 to 2.3
25.13. Migrating from Jersey 1.x to 2.0
25.13.1. Server API
25.13.2. Migrating Jersey Client API
25.13.3. JSON support changes
A. Configuration Properties
A.1. Common (client/server) configuration properties
A.2. Server configuration properties
A.3. Client configuration properties

List of Examples

3.1. Simple hello world root resource class
3.2. Specifying URI path parameter
3.3. PUT method
3.4. Specifying output MIME type
3.5. Using multiple output MIME types
3.6. Server-side content negotiation
3.7. Specifying input MIME type
3.8. Query parameters
3.9. Custom Java type for consuming request parameters
3.10. Processing POSTed HTML form
3.11. Obtaining general map of URI path and/or query parameters
3.12. Obtaining general map of header parameters
3.13. Obtaining general map of form parameters
3.14. Example of the bean which will be used as @BeanParam
3.15. Injection of MyBeanParam as a method parameter:
3.16. Injection of more beans into one resource methods:
3.17. Sub-resource methods
3.18. Sub-resource locators
3.19. Sub-resource locators with empty path
3.20. Sub-resource locators returning sub-type
3.21. Sub-resource locators created from classes
3.22. Sub-resource locators returning resource model
3.23. Injection
3.24. Wrong injection into a singleton scope
3.25. Injection of proxies into singleton
3.26. Example of possible injections
4.1. Deployment agnostic application model
4.2. Reusing Jersey implementation in your custom application model
4.3. Registering SPI implementations using ResourceConfig
4.4. Registering SPI implementations using ResourceConfig subclass
4.5. Using Jersey with JDK HTTP Server
4.6. Using Jersey with Grizzly HTTP Server
4.7. Using Jersey with the Simple framework
4.8. Using Jersey with Jetty HTTP Server
4.9. Hooking up Jersey as a Servlet
4.10. Hooking up Jersey as a Servlet Filter
4.11. Configuring Jersey container Servlet or Filter to use custom Application subclass
4.12. Configuring Jersey container Servlet or Filter to use package scanning
4.13. Configuring Jersey container Servlet or Filter to use a list of classes
4.14. Deployment of a JAX-RS application using @ApplicationPath with Servlet 3.0
4.15. Configuration of maven-war-plugin to ignore missing web.xml
4.16. Deployment of a JAX-RS application using web.xml with Servlet 3.0
4.17. web.xml of a JAX-RS application without an Application subclass
4.18.
4.19.
5.1. POST request with form parameters
5.2. Using JAX-RS Client API
5.3. Using JAX-RS Client API fluently
5.4. Sending restricted headers with HttpUrlConnector
5.5. Closing connections
5.6. ServiceLocatorClientProvider example
6.1. Using File with a specific media type to produce a response
6.2. Returning 201 status code and adding Location header in response to POST request
6.3. Adding an entity body to a custom response
6.4. Throwing exceptions to control response
6.5. Application specific exception implementation
6.6. Mapping generic exceptions to responses
6.7. Conditional GET support
7.1. Example resource class
7.2. MyBean entity class
7.3. MessageBodyWriter example
7.4. Example of assignment of annotations to a response entity
7.5. Client code testing MyBeanMessageBodyWriter
7.6. Result of MyBeanMessageBodyWriter test
7.7. MessageBodyReader example
7.8. Testing MyBeanMessageBodyReader
7.9. Result of testing MyBeanMessageBodyReader
7.10. MessageBodyReader registered on a JAX-RS client
7.11. Result of client code execution
7.12. Usage of MessageBodyWorkers interface
8.1. Simple JAXB bean implementation
8.2. JAXB bean used to generate JSON representation
8.3. Tweaking JSON format using JAXB
8.4. JAXB bean creation
8.5. Constructing a JsonObject (JSON-Processing)
8.6. Constructing a JSONObject (Jettison)
8.7. MoxyJsonConfig - Setting properties.
8.8. Creating ContextResolver<MoxyJsonConfig>
8.9. Setting properties for MOXy providers into Configurable
8.10. Building client with MOXy JSON feature enabled.
8.11. Creating JAX-RS application with MOXy JSON feature enabled.
8.12. Building client with JSON-Processing JSON feature enabled.
8.13. Creating JAX-RS application with JSON-Processing JSON feature enabled.
8.14. ContextResolver<ObjectMapper>
8.15. Building client with Jackson JSON feature enabled.
8.16. Creating JAX-RS application with Jackson JSON feature enabled.
8.17. JAXB beans for JSON supported notations description, simple address bean
8.18. JAXB beans for JSON supported notations description, contact bean
8.19. JAXB beans for JSON supported notations description, initialization
8.20. XML namespace to JSON mapping configuration for Jettison based mapped notation
8.21. JSON expression with XML namespaces mapped into JSON
8.22. JSON Array configuration for Jettison based mapped notation
8.23. JSON expression with JSON arrays explicitly configured via Jersey
8.24. JSON expression produced using badgerfish notation
8.25. ContextResolver<ObjectMapper>
8.26. Building client with Jettison JSON feature enabled.
8.27. Creating JAX-RS application with Jettison JSON feature enabled.
8.28. Simplest case of using @JSONP
8.29. JaxbBean for @JSONP example
8.30. Example of @JSONP with configured parameters.
8.31. Low level XML test - methods added to HelloWorldResource.java
8.32. Planet class
8.33. Resource class
8.34. Method for consuming Planet
8.35. Resource class - JAXBElement
8.36. Client side - JAXBElement
8.37. PlanetJAXBContextProvider
8.38. Using Provider with JAX-RS client
8.39. Add jersey-media-moxy dependency.
8.40. Register the MoxyXmlFeature class.
8.41. Configure and register an MoxyXmlFeature instance.
8.42. Building client with MultiPart feature enabled.
8.43. Creating JAX-RS application with MultiPart feature enabled.
8.44. MultiPart entity
8.45. MultiPart entity in HTTP message.
8.46. FormDataMultiPart entity
8.47. FormDataMultiPart entity in HTTP message.
8.48. Multipart - sending files.
8.49. Resource method using MultiPart as input parameter / return value.
8.50. Use of @FormDataParam annotation
9.1. Container response filter
9.2. Container request filter
9.3. Pre-matching request filter
9.4. Client request filter
9.5. GZIP writer interceptor
9.6. GZIP reader interceptor
9.7. @NameBinding example
9.8. Dynamic binding example
9.9. Priorities example
10.1. Simple async resource
10.2. Simple async method with timeout
10.3. CompletionCallback example
10.4. ChunkedOutput example
10.5. Simple client async invocation
10.6. Simple client fluent async invocation
10.7. Client async callback
10.8. Client async callback for specific entity
10.9. ChunkedInput example
11.1. URI building
11.2. Building URIs using query parameters
12.1. Creating JAX-RS application with Declarative Linking feature enabled.
13.1. A standard resource class
13.2. A programmatic resource
13.3. A programmatic resource
13.4. A programmatic resource
13.5. A programmatic resource
13.6. A programmatic resource
14.1. Add jersey-media-sse dependency.
14.2. Simple SSE resource method
14.3. Broadcasting SSE messages
14.4. Registering EventListener with EventSource
14.5. Overriding EventSource.onEvent(InboundEvent) method
15.1. Using SecurityContext for a Resource Selection
15.2. Injecting SecurityContext into a singleton resource
15.3. Securing resources using web.xml
15.4. Registering RolesAllowedDynamicFeature using ResourceConfig
15.5. Registering RolesAllowedDynamicFeature by extending ResourceConfig
15.6. Applying javax.annotation.security to JAX-RS resource methods.
15.7. Build the authorization flow utility
15.8. Perform the OAuth Authorization Flow
15.9. Authenticated requests
15.10. Build feature from Access Token
15.11. Specifying Access Token on a Request.
15.12. Creating Public/Private RSA-SHA1 keys
15.13. Building OAuth 2 Authorization Flow.
16.1. A simple WADL example - JAX-RS resource definition
16.2. A simple WADL example - WADL content
16.3. OPTIONS method returning WADL
16.4. More complex WADL example - JAX-RS resource definition
16.5. More complex WADL example - WADL content
17.1. Configuring Jersey specific properties for Bean Validation.
17.2. Using ValidationConfig to configure Validator.
17.3. Constraint annotations on input parameters
17.4. Constraint annotations on fields
17.5. Constraint annotations on class
17.6. Definition of a constraint annotation
17.7. Validator implementation.
17.8. Entity validation
17.9. Entity validation 2
17.10. Response entity validation
17.11. Validate getter on execution
17.12. Injecting UriInfo into a ConstraintValidator
17.13. Support for injecting Jersey's resources/providers via ConstraintValidatorFactory.
17.14. ValidationError to text/plain
17.15. ValidationError to text/html
17.16. ValidationError to application/xml
17.17. ValidationError to application/json
18.1. Registering and configuring entity-filtering feature on server.
18.2. Registering and configuring entity-filtering feature with security annotations on server.
18.3. Registering and configuring entity-filtering feature based on dynamic and configurable query parameters.
18.4. Registering and configuring entity-filtering feature on client.
18.5. Project
18.6. User
18.7. Task
18.8. ProjectsResource
18.9. ProjectDetailedView
18.10. Annotated Project
18.11. Annotated User
18.12. Annotated Task
18.13. ProjectsResource - Response entity-filtering annotations
18.14. ProjectsResource - Entity-filtering annotations on methods
18.15. Client - Request entity-filtering annotations
18.16. Client - Request entity-filtering annotations
18.17. Sever - Query Parameter driven entity-filtering
18.18.
18.19. Entity-filtering annotation with custom meaning
18.20. Entity Data Filtering support in MOXy JSON binding provider
19.1. Using Viewable in a resource class
19.2. Using @Template on a resource method
19.3. Using @Template on a resource class
19.4. Using absolute path to template in Viewable
19.5. Using @ErrorTemplate on a resource method
19.6. Using @ErrorTemplate with Bean Validation
19.7. Iterating through ValidationError in JSP
19.8. Registering MvcFeature
19.9. Registering FreemarkerMvcFeature
19.10. Setting MvcFeature.TEMPLATE_BASE_PATH value in ResourceConfig
19.11. Setting FreemarkerMvcProperties.TEMPLATE_BASE_PATH value in web.xml
19.12. Including JSP page into JSP page
19.13. Custom TemplateProcessor
19.14. Registering custom TemplateProcessor
20.1. Application event listener
20.2. Request event listener
20.3. Event listener test resource
20.4. Injecting MonitoringStatistics
20.5. Summary level messages
20.6. On demand request, snippet of MVC JSP forwarding
25.1. Jersey 1 reloader implementation
25.2. Jersey 1 reloader registration
25.3. Jersey 2 reloader implementation
25.4. Jersey 2 reloader registration
25.5. Initializing JAXB-based support with MOXy