Jersey 3.0.17 User Guide
   Next
Links: Table of Contents | Single HTML

Jersey 3.0.17 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.1.1. Virtual Threads and Thread Factories
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 way
4.7.2. Servlet 5.x Container
4.7.3. Jersey Servlet container modules
4.8. Jakarta 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. Jakarta 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.3.7. Setting ExecutorService and ScheduledExecutorService
5.4. Java instances and types for representations
5.4.1. Adding support for new representations
5.5. Client Transport Connectors
5.5.1. The default HttpUrlConnector
5.5.2. Client Connectors Properties
5.5.3. Applying additional settings to 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
5.9.2. Server Name Indication (SNI) Support
5.10. InvocationInterceptors
5.10.1. PreInvocationInterceptor
5.10.2. PostInvocationInterceptor
5.11. InvocationBuilderListener
5.12. Header Expect:100-continue support
6. Reactive JAX-RS Client API
6.1. Motivation for Reactive Client Extension
6.2. Usage and Extension Modules
6.3. Supported Reactive Libraries
6.3.1. RxJava (Observable)
6.3.2. RxJava (Flowable)
6.3.3. Guava (ListenableFuture and Futures)
6.4. Implementing Support for Custom Reactive Libraries (SPI)
7. Representations and Responses
7.1. Representations and Java Types
7.2. Building Responses
7.3. WebApplicationException and Mapping Exceptions to Responses
7.4. Conditional GETs and Returning 304 (Not Modified) Responses
8. JAX-RS Entity Providers
8.1. Introduction
8.2. How to Write Custom Entity Providers
8.2.1. MessageBodyWriter
8.2.2. MessageBodyReader
8.3. Entity Provider Selection
8.4. Jersey MessageBodyWorkers API
8.5. Default Jersey Entity Providers
9. Support for Common Media Type Representations
9.1. JSON
9.1.1. Approaches to JSON Support
9.1.2. MOXy
9.1.3. Java API for JSON Processing (JSON-P)
9.1.4. Jackson (2.x)
9.1.5. Jettison
9.1.6. @JSONP - JSON with Padding Support
9.1.7. Java API for JSON Binding (JSON-B)
9.1.8. Properties for configuring JSON providers
9.2. XML
9.2.1. Low level XML support
9.2.2. Getting started with JAXB
9.2.3. POJOs
9.2.4. Using custom JAXBContext
9.2.5. MOXy
9.2.6. Properties for configuring XML providers
9.3. Multipart
9.3.1. Overview
9.3.2. Client
9.3.3. Server
9.3.4. Properties for configuring the Multipart
10. Filters and Interceptors
10.1. Introduction
10.2. Filters
10.2.1. Server filters
10.2.2. Client filters
10.3. Interceptors
10.4. Filter and interceptor execution order
10.5. Name binding
10.6. Dynamic binding
10.7. Priorities
11. Asynchronous Services and Clients
11.1. Asynchronous Server API
11.1.1. Asynchronous Server-side Callbacks
11.1.2. Chunked Output
11.2. Client API
11.2.1. Asynchronous Client Callbacks
11.2.2. Chunked input
12. URIs and Links
12.1. Building URIs
12.2. Resolve and Relativize
12.3. Link
13. Declarative Hyperlinking
13.1. Dependency
13.2. Links in Representations
13.3. List of Link Injection
13.4. Links from Resources
13.5. Binding Template Parameters
13.6. Conditional Link Injection
13.7. Link Headers
13.8. Prevent Recursive Injection
13.9. Meta-annotation support
13.10. Configure and register
14. Programmatic API for Building Resources
14.1. Introduction
14.2. Programmatic Hello World example
14.2.1. Deployment of programmatic resources
14.3. Additional examples
14.4. Model processors
15. Jersey configuration
15.1. Jersey default configuration provider
15.2. Micro profile configuration provider
16. Micrometer - application observability facade
16.1. Integration into Jersey
17. Server-Sent Events (SSE) Support
17.1. What are Server-Sent Events
17.2. When to use Server-Sent Events
17.3. Server-Sent Events API
17.4. Implementing SSE support in a JAX-RS resource (with JAX-RS SSE API)
17.4.1. Simple SSE resource method
17.4.2. Broadcasting with Jersey SSE
17.5. Consuming SSE events within Jersey clients
17.5.1. SseEventSource reconnect support
17.6. Jersey-specific Server-Sent Events API
17.6.1. Implementing SSE support in a JAX-RS resource
17.6.2. Consuming SSE events with Jersey clients
18. Security
18.1. Securing server
18.1.1. SecurityContext
18.1.2. Authorization - securing resources
18.2. Client Security
18.3. OAuth Support
18.3.1. OAuth 1
18.3.2. OAuth 2 Support
19. WADL Support
19.1. WADL introduction
19.2. Configuration
19.3. Extended WADL support
20. Bean Validation Support
20.1. Bean Validation Dependencies
20.2. Enabling Bean Validation in Jersey
20.3. Configuring Bean Validation Support
20.4. Validating JAX-RS resources and methods
20.4.1. Constraint Annotations
20.4.2. Annotation constraints and Validators
20.4.3. Entity Validation
20.4.4. Annotation Inheritance
20.5. @ValidateOnExecution
20.6. Injecting
20.7. Error Reporting
20.7.1. ValidationError
20.8. Example
21. Entity Data Filtering
21.1. Enabling and configuring Entity Filtering in your application
21.2. Components used to describe Entity Filtering concepts
21.3. Using custom annotations to filter entities
21.3.1. Server-side Entity Filtering
21.3.2. Client-side Entity Filtering
21.4. Role-based Entity Filtering using (jakarta.annotation.security) annotations
21.5. Entity Filtering based on dynamic and configurable query parameters
21.6. Defining custom handling for entity-filtering annotations
21.7. Supporting Entity Data Filtering in custom entity providers or frameworks
21.8. Modules with support for Entity Data Filtering
21.9. Examples
22. MVC Templates
22.1. Viewable
22.2. @Template
22.2.1. Annotating Resource methods
22.2.2. Annotating Resource classes
22.3. Absolute vs. Relative template reference
22.3.1. Relative template reference
22.3.2. Absolute template reference
22.4. Handling errors with MVC
22.4.1. MVC & Bean Validation
22.5. Registration and Configuration
22.6. Supported templating engines
22.6.1. Mustache
22.6.2. Freemarker
22.6.3. JSP
22.7. Writing Custom Templating Engines
22.8. Other Examples
23. Logging
23.1. Logging traffic
23.1.1. Introduction
23.1.2. Configuration and registering
24. Monitoring and Diagnostics
24.1. Monitoring Jersey Applications
24.1.1. Introduction
24.1.2. Event Listeners
24.2. Tracing Support
24.2.1. Configuration options
24.2.2. Tracing Log
24.2.3. Configuring tracing support via HTTP request headers
24.2.4. Format of the HTTP response headers
24.2.5. Tracing Examples
25. Custom Injection and Lifecycle Management
25.1. InjectionManager
25.2. Implementing Custom Injection Provider
25.2.1. Using HK2 classes
25.2.2. Injection Provider Using Jersey API
25.3. Defining Custom Injection Annotation
25.3.1. Custom Injection Annotation using HK2
25.3.2. Custom Injection Annotation using Jersey InjectionResolver
25.4. Custom Life Cycle Management
26. Jersey CDI Container Agnostic Support
26.1. Introduction
26.2. Containers Known to Work With Jersey CDI Support
26.3. Request Scope Binding
26.4. Jersey Weld SE Support
27. GraalVM native-image generation
27.1. Modules with GraalVM native image support
27.2. HelloWorld native image generation
27.3. What's under the cover
28. Jersey Test Framework
28.1. Basics
28.2. Supported Containers
28.3. Running TestNG Tests
28.4. Advanced features
28.4.1. JerseyTest Features
28.4.2. External container
28.4.3. Test Client configuration
28.4.4. Accessing the logged test records programmatically
28.5. Parallel Testing with Jersey Test Framework
29. Building and Testing Jersey
29.1. Checking Out the Source
29.2. Building the Source
29.3. Testing
29.4. Using NetBeans
30. Migration Guide
30.1. Migrating from Jersey 3.0.11 to 3.0.12
30.1.1. Changes in Jackson
30.2. Migrating from Jersey 2.32+ to 3.0.x.
30.2.1. Breaking Changes
30.2.2. Removed deprecated APIs
30.2.3. Application servers for Jersey
30.3. Migrating from Jersey 3.0.x to 3.0.17.
30.3.1. Breaking Changes
A. Configuration Properties
A.1. Common (client/server) configuration properties
A.2. Server configuration properties
A.3. Servlet configuration properties
A.4. Client configuration properties
A.5. Jersey configuration properties for message & entity processing
A.6. The default HttpUrlConnector properties
A.7. Apache HTTP client configuration properties
A.8. Apache 5 HTTP client configuration properties
A.9. Helidon HTTP client configuration properties
A.10. JDK HTTP client configuration properties
A.11. Jetty HTTP client configuration properties
A.12. Netty HTTP client configuration properties
A.13. Multipart configuration properties

List of Figures

6.1. Travel Agency Orchestration Service
6.2. Time consumed to create a response for the client – synchronous way
6.3. Time consumed to create a response for the client – asynchronous way

List of Tables

2.1. Jersey 3.0.x JDK compatibility
2.2. Jersey Core
2.3. Jersey Containers
2.4. Jersey Connectors
2.5. Jersey Media
2.6. Jersey Extensions
2.7. Jersey Test Framework
2.8. Jersey Test Framework Providers
2.9. Jersey Glassfish Bundles
2.10. Security
2.11. Jersey Examples
3.1. Resource scopes
3.2. Overview of injection types
4.1. Servlet 3 Pluggability Overview
5.1. List of Jersey Connectors
9.1. Default property values for MOXy MessageBodyReader<T> / MessageBodyWriter<T>
A.1. List of common configuration properties
A.2. List of server configuration properties
A.3. List of servlet configuration properties
A.4. List of client configuration properties
A.5. List of Apache HTTP client configuration properties
A.6. List of the default HttpUrlConnectorProvider properites
A.7. List of Apache HTTP client configuration properties
A.8. List of Apache 5 HTTP client configuration properties
A.9. List of Helidon HTTP client configuration properties
A.10. List of Jdk HTTP client configuration properties
A.11. List of Jetty HTTP client configuration properties
A.12. List of Netty HTTP client configuration properties
A.13. List of multipart configuration properties settable in the MultiPartProperties.MULTI_PART_CONFIG_RESOURCE configuration file.

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. Using Jersey with Netty HTTP Server
4.10. Hooking up Jersey as a Servlet
4.11. Hooking up Jersey as a Servlet Filter
4.12. Configuring Jersey container Servlet or Filter to use custom Application subclass
4.13. Configuring Jersey container Servlet or Filter to use package scanning
4.14. Configuring Jersey container Servlet or Filter to use a list of classes
4.15. Deployment of a JAX-RS application using @ApplicationPath with Servlet 5.0
4.16. Configuration of maven-war-plugin to ignore missing web.xml
4.17. Deployment of a JAX-RS application using web.xml with Servlet 5.0
4.18. web.xml of a JAX-RS application without an Application subclass
4.19.
4.20.
5.1. POST request with form parameters
5.2. Using JAX-RS Client API
5.3. Using JAX-RS Client API fluently
5.4. Setting JAX-RS Client ExecutorService
5.5. Sending restricted headers with HttpUrlConnector
5.6. Closing connections
5.7. InjectionManagerClientProvider example
6.1. Excerpt from a synchronous approach while implementing the orchestration layer
6.2. Excerpt from an asynchronous approach while implementing the orchestration layer
6.3. Excerpt from a reactive approach while implementing the orchestration layer
6.4. Synchronous invocation of HTTP requests
6.5. Asynchronous invocation of HTTP requests
6.6. Reactive invocation of HTTP requests
6.7. Creating JAX-RS Client with RxJava reactive extension
6.8. Obtaining Observable<Response> from Jersey/RxJava Client
6.9. Creating JAX-RS Client with RxJava2 reactive extension
6.10. Obtaining Flowable<Response> from Jersey/RxJava Client
6.11. Creating Jersey/Guava Client
6.12. Obtaining ListenableFuture<Response> from Jersey/Guava Client
6.13. Extending RxIvoker
6.14. Extending RxInvokerProvider
7.1. Using File with a specific media type to produce a response
7.2. Returning 201 status code and adding Location header in response to POST request
7.3. Adding an entity body to a custom response
7.4. Throwing exceptions to control response
7.5. Application specific exception implementation
7.6. Mapping generic exceptions to responses
7.7. Conditional GET support
8.1. Example resource class
8.2. MyBean entity class
8.3. MessageBodyWriter example
8.4. Example of assignment of annotations to a response entity
8.5. Client code testing MyBeanMessageBodyWriter
8.6. Result of MyBeanMessageBodyWriter test
8.7. MessageBodyReader example
8.8. Testing MyBeanMessageBodyReader
8.9. Result of testing MyBeanMessageBodyReader
8.10. MessageBodyReader registered on a JAX-RS client
8.11. Result of client code execution
8.12. Usage of MessageBodyWorkers interface
9.1. Simple JAXB bean implementation
9.2. JAXB bean used to generate JSON representation
9.3. Tweaking JSON format using JAXB
9.4. JAXB bean creation
9.5. Constructing a JsonObject (JSON-Processing)
9.6. Constructing a JSONObject (Jettison)
9.7. MoxyJsonConfig - Setting properties.
9.8. Creating ContextResolver<MoxyJsonConfig>
9.9. Setting properties for MOXy providers into Configurable
9.10. Building client with MOXy JSON feature enabled.
9.11. Creating JAX-RS application with MOXy JSON feature enabled.
9.12. Building client with JSON-Processing JSON feature enabled.
9.13. Creating JAX-RS application with JSON-Processing JSON feature enabled.
9.14. ContextResolver<ObjectMapper>
9.15. Building client with Jackson JSON feature enabled.
9.16. Creating JAX-RS application with Jackson JSON feature enabled.
9.17. JAXB beans for JSON supported notations description, simple address bean
9.18. JAXB beans for JSON supported notations description, contact bean
9.19. JAXB beans for JSON supported notations description, initialization
9.20. XML namespace to JSON mapping configuration for Jettison based mapped notation
9.21. JSON expression with XML namespaces mapped into JSON
9.22. JSON Array configuration for Jettison based mapped notation
9.23. JSON expression with JSON arrays explicitly configured via Jersey
9.24. JSON expression produced using badgerfish notation
9.25. ContextResolver<ObjectMapper>
9.26. Building client with Jettison JSON feature enabled.
9.27. Creating JAX-RS application with Jettison JSON feature enabled.
9.28. Simplest case of using @JSONP
9.29. JaxbBean for @JSONP example
9.30. Example of @JSONP with configured parameters.
9.31. ContextResolver<Jsonb>
9.32. Register the feature and ContextResolver<Jsonb>
9.33. Low level XML test - methods added to HelloWorldResource.java
9.34. Planet class
9.35. Resource class
9.36. Method for consuming Planet
9.37. Resource class - JAXBElement
9.38. Client side - JAXBElement
9.39. PlanetJAXBContextProvider
9.40. Using Provider with JAX-RS client
9.41. Add jersey-media-moxy dependency.
9.42. Register the MoxyXmlFeature class.
9.43. Configure and register an MoxyXmlFeature instance.
9.44. Building client with MultiPart feature enabled.
9.45. Creating JAX-RS application with MultiPart feature enabled.
9.46. MultiPart entity
9.47. MultiPart entity in HTTP message.
9.48. FormDataMultiPart entity
9.49. FormDataMultiPart entity in HTTP message.
9.50. Multipart - sending files.
9.51. Resource method using MultiPart as input parameter / return value.
9.52. Use of @FormDataParam annotation
10.1. Container response filter
10.2. Container request filter
10.3. Pre-matching request filter
10.4. Client request filter
10.5. GZIP writer interceptor
10.6. GZIP reader interceptor
10.7. @NameBinding example
10.8. Dynamic binding example
10.9. Priorities example
11.1. Simple async resource
11.2. Simple async method with timeout
11.3. CompletionCallback example
11.4. ChunkedOutput example
11.5. Simple client async invocation
11.6. Simple client fluent async invocation
11.7. Client async callback
11.8. Client async callback for specific entity
11.9. ChunkedInput example
12.1. URI building
12.2. Building URIs using query parameters
13.1. Creating JAX-RS application with Declarative Linking feature enabled.
14.1. A standard resource class
14.2. A programmatic resource
14.3. A programmatic resource
14.4. A programmatic resource
14.5. A programmatic resource
14.6. A programmatic resource
16.1. Annotated Micrometer resource methods
17.1. Adding the SSE dependency
17.2. Simple SSE resource method
17.3. Broadcasting SSE messages (with JAX-RS 3.0 API)
17.4. Consuming SSE events with SseEventSource
17.5. SseEventSource subscribe() methods
17.6. Add jersey-media-sse dependency.
17.7. Simple SSE resource method
17.8. Broadcasting SSE messages
17.9. Registering EventListener with EventSource
17.10. Overriding EventSource.onEvent(InboundEvent) method
18.1. Using SecurityContext for a Resource Selection
18.2. Injecting SecurityContext into a singleton resource
18.3. Securing resources using web.xml
18.4. Registering RolesAllowedDynamicFeature using ResourceConfig
18.5. Registering RolesAllowedDynamicFeature by extending ResourceConfig
18.6. Applying jakarta.annotation.security to JAX-RS resource methods.
18.7. Build the authorization flow utility
18.8. Perform the OAuth Authorization Flow
18.9. Authenticated requests
18.10. Build feature from Access Token
18.11. Specifying Access Token on a Request.
18.12. Creating Public/Private RSA-SHA1 keys
18.13. Building OAuth 2 Authorization Flow.
19.1. A simple WADL example - JAX-RS resource definition
19.2. A simple WADL example - WADL content
19.3. OPTIONS method returning WADL
19.4. More complex WADL example - JAX-RS resource definition
19.5. More complex WADL example - WADL content
20.1. Configuring Jersey specific properties for Bean Validation.
20.2. Using ValidationConfig to configure Validator.
20.3. Constraint annotations on input parameters
20.4. Constraint annotations on fields
20.5. Constraint annotations on class
20.6. Definition of a constraint annotation
20.7. Validator implementation.
20.8. Entity validation
20.9. Entity validation 2
20.10. Response entity validation
20.11. Validate getter on execution
20.12. Injecting UriInfo into a ConstraintValidator
20.13. Support for injecting Jersey's resources/providers via ConstraintValidatorFactory.
20.14. ValidationError to text/plain
20.15. ValidationError to text/html
20.16. ValidationError to application/xml
20.17. ValidationError to application/json
21.1. Registering and configuring entity-filtering feature on server.
21.2. Registering and configuring entity-filtering feature with security annotations on server.
21.3. Registering and configuring entity-filtering feature based on dynamic and configurable query parameters.
21.4. Registering and configuring entity-filtering feature on client.
21.5. Project
21.6. User
21.7. Task
21.8. ProjectsResource
21.9. ProjectDetailedView
21.10. Annotated Project
21.11. Annotated User
21.12. Annotated Task
21.13. ProjectsResource - Response entity-filtering annotations
21.14. ProjectsResource - Entity-filtering annotations on methods
21.15. Client - Request entity-filtering annotations
21.16. Client - Request entity-filtering annotations
21.17. Sever - Query Parameter driven entity-filtering
21.18.
21.19. Entity-filtering annotation with custom meaning
21.20. Entity Data Filtering support in MOXy JSON binding provider
22.1. Using Viewable in a resource class
22.2. Using @Template on a resource method
22.3. Using @Template on a resource class
22.4. Using absolute path to template in Viewable
22.5. Using @ErrorTemplate on a resource method
22.6. Using @ErrorTemplate with Bean Validation
22.7. Iterating through ValidationError in JSP
22.8. Registering MvcFeature
22.9. Registering FreemarkerMvcFeature
22.10. Setting MvcFeature.TEMPLATE_BASE_PATH value in ResourceConfig
22.11. Setting FreemarkerMvcProperties.TEMPLATE_BASE_PATH value in web.xml
22.12. Including JSP page into JSP page
22.13. Custom TemplateProcessor
22.14. Registering custom TemplateProcessor
23.1. Logging on the client side
23.2. Register LoggingFeature via constructor
23.3. Register LoggingFeature class
24.1. Application event listener
24.2. Request event listener
24.3. Event listener test resource
24.4. Injecting MonitoringStatistics
24.5. Summary level messages
24.6. On demand request, snippet of MVC JSP forwarding
26.1. Bootstrapping Jersey application with Weld support on Grizzly
   Next
   Preface