Restore support for Jersey

Restore support for Jersey now that it supports JAX-RS 4.

Closes gh-47967

Co-authored-by: Andy Wilkinson <andy.wilkinson@broadcom.com>

Author: philwebb

configuration-metadata/spring-boot-configuration-metadata-changelog-generator/build.gradle

@@ -92,6 +92,7 @@ def dependenciesOf(String version) {
 			"spring-boot-jackson2",
 			"spring-boot-jdbc",
 			"spring-boot-jdbc-test",
+			"spring-boot-jersey",
 			"spring-boot-jetty",
 			"spring-boot-jms",
 			"spring-boot-jooq",

documentation/spring-boot-docs/build.gradle

@@ -165,6 +165,8 @@ dependencies {
 	implementation("org.assertj:assertj-core")
 	implementation("org.cache2k:cache2k-spring")
 	implementation("org.apache.groovy:groovy")
+	implementation("org.glassfish.jersey.containers:jersey-container-servlet")
+	implementation("org.glassfish.jersey.core:jersey-server")
 	implementation("org.hibernate.orm:hibernate-jcache") {
 		exclude group: "javax.activation", module: "javax.activation-api"
 		exclude group: "javax.persistence", module: "javax.persistence-api"

documentation/spring-boot-docs/src/docs/antora/modules/ROOT/pages/documentation.adoc

@@ -64,7 +64,7 @@ xref:reference:features/index.adoc[The following content is for you]:
 
 If you develop Spring Boot web applications, take a look at the following content:
 
-* *Servlet Web Applications:* xref:reference:web/servlet.adoc[Spring MVC, Embedded Servlet Containers]
+* *Servlet Web Applications:* xref:reference:web/servlet.adoc[Spring MVC, Jersey, Embedded Servlet Containers]
 * *Reactive Web Applications:* xref:reference:web/reactive.adoc[Spring Webflux, Embedded Servlet Containers]
 * *Graceful Shutdown:* xref:reference:web/graceful-shutdown.adoc[Graceful Shutdown]
 * *Spring Security:* xref:reference:web/spring-security.adoc[Default Security Configuration, Auto-configuration for OAuth2, SAML]

documentation/spring-boot-docs/src/docs/antora/modules/ROOT/pages/redirect.adoc

@@ -550,6 +550,12 @@
 * xref:how-to:index.adoc#howto[#howto]
 * xref:how-to:index.adoc[#howto]
 * xref:how-to:index.adoc[howto]
+* xref:how-to:jersey.adoc#howto.jersey.alongside-another-web-framework[#howto-jersey-alongside-another-web-framework]
+* xref:how-to:jersey.adoc#howto.jersey.alongside-another-web-framework[#howto.jersey.alongside-another-web-framework]
+* xref:how-to:jersey.adoc#howto.jersey.spring-security[#howto-jersey-spring-security]
+* xref:how-to:jersey.adoc#howto.jersey.spring-security[#howto.jersey.spring-security]
+* xref:how-to:jersey.adoc#howto.jersey[#howto-jersey]
+* xref:how-to:jersey.adoc#howto.jersey[#howto.jersey]
 * xref:how-to:logging.adoc#howto.logging.log4j.composite-configuration[#howto.logging.log4j.composite-configuration]
 * xref:how-to:logging.adoc#howto.logging.log4j.yaml-or-json-config[#howto-configure-log4j-for-logging-yaml-or-json-config]
 * xref:how-to:logging.adoc#howto.logging.log4j.yaml-or-json-config[#howto.logging.log4j.yaml-or-json-config]
@@ -1124,6 +1130,8 @@
 * xref:reference:actuator/metrics.adoc#actuator.metrics.supported.http-clients[#production-ready-metrics-http-clients]
 * xref:reference:actuator/metrics.adoc#actuator.metrics.supported.jdbc[#actuator.metrics.supported.jdbc]
 * xref:reference:actuator/metrics.adoc#actuator.metrics.supported.jdbc[#production-ready-metrics-jdbc]
+* xref:reference:actuator/metrics.adoc#actuator.metrics.supported.jersey[#actuator.metrics.supported.jersey]
+* xref:reference:actuator/metrics.adoc#actuator.metrics.supported.jersey[#production-ready-metrics-jersey-server]
 * xref:reference:actuator/metrics.adoc#actuator.metrics.supported.jetty[#actuator.metrics.supported.jetty]
 * xref:reference:actuator/metrics.adoc#actuator.metrics.supported.jms[#actuator.metrics.supported.jms]
 * xref:reference:actuator/metrics.adoc#actuator.metrics.supported.jvm[#actuator.metrics.supported.jvm]
@@ -2097,6 +2105,9 @@
 * xref:reference:web/servlet.adoc#web.servlet.embedded-container[#boot-features-embedded-container]
 * xref:reference:web/servlet.adoc#web.servlet.embedded-container[#features.developing-web-applications.embedded-container]
 * xref:reference:web/servlet.adoc#web.servlet.embedded-container[#web.servlet.embedded-container]
+* xref:reference:web/servlet.adoc#web.servlet.jersey[#boot-features-jersey]
+* xref:reference:web/servlet.adoc#web.servlet.jersey[#features.developing-web-applications.jersey]
+* xref:reference:web/servlet.adoc#web.servlet.jersey[#web.servlet.jersey]
 * xref:reference:web/servlet.adoc#web.servlet.spring-mvc.auto-configuration[#boot-features-spring-mvc-auto-configuration]
 * xref:reference:web/servlet.adoc#web.servlet.spring-mvc.auto-configuration[#features.developing-web-applications.spring-mvc.auto-configuration]
 * xref:reference:web/servlet.adoc#web.servlet.spring-mvc.auto-configuration[#web.servlet.spring-mvc.auto-configuration]

documentation/spring-boot-docs/src/docs/antora/modules/how-to/pages/jersey.adoc

@@ -0,0 +1,26 @@
+[[howto.jersey]]
+= Jersey
+
+
+
+[[howto.jersey.spring-security]]
+== Secure Jersey Endpoints with Spring Security
+
+Spring Security can be used to secure a Jersey-based web application in much the same way as it can be used to secure a Spring MVC-based web application.
+However, if you want to use Spring Security's method-level security with Jersey, you must configure Jersey to use `setStatus(int)` rather `sendError(int)`.
+This prevents Jersey from committing the response before Spring Security has had an opportunity to report an authentication or authorization failure to the client.
+
+The `jersey.config.server.response.setStatusOverSendError` property must be set to `true` on the application's javadoc:org.glassfish.jersey.server.ResourceConfig[] bean, as shown in the following example:
+
+include-code::JerseySetStatusOverSendErrorConfig[]
+
+
+
+[[howto.jersey.alongside-another-web-framework]]
+== Use Jersey Alongside Another Web Framework
+
+To use Jersey alongside another web framework, such as Spring MVC, it should be configured so that it will allow the other framework to handle requests that it cannot handle.
+First, configure Jersey to use a filter rather than a servlet by configuring the configprop:spring.jersey.type[] application property with a value of `filter`.
+Second, configure your javadoc:org.glassfish.jersey.server.ResourceConfig[] to forward requests that would have resulted in a 404, as shown in the following example.
+
+include-code::JerseyConfig[]

documentation/spring-boot-docs/src/docs/antora/modules/how-to/partials/nav-how-to.adoc

@@ -4,6 +4,7 @@
 ** xref:how-to:properties-and-configuration.adoc[]
 ** xref:how-to:webserver.adoc[]
 ** xref:how-to:spring-mvc.adoc[]
+** xref:how-to:jersey.adoc[]
 ** xref:how-to:http-clients.adoc[]
 ** xref:how-to:logging.adoc[]
 ** xref:how-to:data-access.adoc[]

documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/endpoints.adoc

@@ -95,7 +95,7 @@ Subject to xref:actuator/endpoints.adoc#actuator.endpoints.sanitization[sanitiza
 | Performs a thread dump.
 |===
 
-If your application is a web application (Spring MVC or Spring WebFlux), you can use the following additional endpoints:
+If your application is a web application (Spring MVC, Spring WebFlux, or Jersey), you can use the following additional endpoints:
 
 [cols="2,5"]
 |===
@@ -388,7 +388,8 @@ TIP: See javadoc:org.springframework.boot.actuate.autoconfigure.endpoint.web.Cor
 == Implementing Custom Endpoints
 
 If you add a javadoc:org.springframework.context.annotation.Bean[format=annotation] annotated with javadoc:org.springframework.boot.actuate.endpoint.annotation.Endpoint[format=annotation], any methods annotated with javadoc:org.springframework.boot.actuate.endpoint.annotation.ReadOperation[format=annotation], javadoc:org.springframework.boot.actuate.endpoint.annotation.WriteOperation[format=annotation], or javadoc:org.springframework.boot.actuate.endpoint.annotation.DeleteOperation[format=annotation] are automatically exposed over JMX and, in a web application, over HTTP as well.
-Endpoints can be exposed over HTTP by using Spring MVC or Spring WebFlux.
+Endpoints can be exposed over HTTP by using Jersey, Spring MVC, or Spring WebFlux.
+If both Jersey and Spring MVC are available, Spring MVC is used.
 
 The following example exposes a read operation that returns a custom object:
 
@@ -451,7 +452,8 @@ Before calling an operation method, the input received over JMX or HTTP is conve
 [[actuator.endpoints.implementing-custom.web]]
 === Custom Web Endpoints
 
-Operations on an javadoc:org.springframework.boot.actuate.endpoint.annotation.Endpoint[format=annotation], javadoc:org.springframework.boot.actuate.endpoint.web.annotation.WebEndpoint[format=annotation], or javadoc:org.springframework.boot.actuate.endpoint.web.annotation.EndpointWebExtension[format=annotation] are automatically exposed over HTTP using Spring MVC or Spring WebFlux.
+Operations on an javadoc:org.springframework.boot.actuate.endpoint.annotation.Endpoint[format=annotation], javadoc:org.springframework.boot.actuate.endpoint.web.annotation.WebEndpoint[format=annotation], or javadoc:org.springframework.boot.actuate.endpoint.web.annotation.EndpointWebExtension[format=annotation] are automatically exposed over HTTP using Jersey, Spring MVC, or Spring WebFlux.
+If both Jersey and Spring MVC are available, Spring MVC is used.
 
 
 
@@ -539,6 +541,8 @@ If an operation is invoked without a required parameter or with a parameter that
 You can use an HTTP range request to request part of an HTTP resource.
 When using Spring MVC or Spring Web Flux, operations that return a javadoc:org.springframework.core.io.Resource[] automatically support range requests.
 
+NOTE: Range requests are not supported when using Jersey.
+
 
 
 [[actuator.endpoints.implementing-custom.web.security]]

documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/metrics.adoc

@@ -765,6 +765,39 @@ Applications can opt in and record exceptions by xref:web/reactive.adoc#web.reac
 
 
 
+[[actuator.metrics.supported.jersey]]
+=== Jersey Server Metrics
+
+Auto-configuration enables the instrumentation of all requests handled by the Jersey JAX-RS implementation.
+By default, metrics are generated with the name, `http.server.requests`.
+You can customize the name by setting the configprop:management.observations.http.server.requests.name[] property.
+
+By default, Jersey server metrics are tagged with the following information:
+
+|===
+| Tag | Description
+
+| `exception`
+| The simple class name of any exception that was thrown while handling the request.
+
+| `method`
+| The request's method (for example, `GET` or `POST`)
+
+| `outcome`
+| The request's outcome, based on the status code of the response.
+  1xx is `INFORMATIONAL`, 2xx is `SUCCESS`, 3xx is `REDIRECTION`, 4xx is `CLIENT_ERROR`, and 5xx is `SERVER_ERROR`
+
+| `status`
+| The response's HTTP status code (for example, `200` or `500`)
+
+| `uri`
+| The request's URI template prior to variable substitution, if possible (for example, `/api/person/\{id}`)
+|===
+
+To customize the tags, provide a javadoc:org.springframework.context.annotation.Bean[format=annotation] that implements javadoc:io.micrometer.core.instrument.binder.jersey.server.JerseyObservationConvention[].
+
+
+
 [[actuator.metrics.supported.ssl]]
 === SSL Bundle Metrics
 

documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/monitoring.adoc

@@ -5,9 +5,12 @@ If you are developing a web application, Spring Boot Actuator auto-configures al
 The default convention is to use the `id` of the endpoint with a prefix of `/actuator` as the URL path.
 For example, `health` is exposed as `/actuator/health`.
 
-TIP: Actuator is supported natively with Spring MVC and Spring WebFlux.
+TIP: Actuator is supported natively with Spring MVC, Spring WebFlux, and Jersey.
+If both Jersey and Spring MVC are available, Spring MVC is used.
 
 NOTE: Jackson is a required dependency in order to get the correct JSON responses as documented in the xref:api:rest/actuator/index.adoc[API documentation].
+Jackson 3 should be used for Spring MVC and Spring WebFlux.
+Jersey does not yet have a Jackson 3 module, so you will need to use Jackson 2.
 
 
 

documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/web/servlet.adoc

@@ -1,7 +1,7 @@
 [[web.servlet]]
 = Servlet Web Applications
 
-If you want to build servlet-based web applications, you can take advantage of Spring Boot's auto-configuration for Spring MVC.
+If you want to build servlet-based web applications, you can take advantage of Spring Boot's auto-configuration for Spring MVC or Jersey.
 
 
 
@@ -495,6 +495,43 @@ See xref:io/rest-client.adoc#io.rest-client.apiversioning[] for details.
 
 
 
+[[web.servlet.jersey]]
+== JAX-RS and Jersey
+
+If you prefer the JAX-RS programming model for REST endpoints, you can use one of the available implementations instead of Spring MVC.
+https://jersey.github.io/[Jersey] and https://cxf.apache.org/[Apache CXF] work quite well out of the box.
+CXF requires you to register its javadoc:jakarta.servlet.Servlet[] or javadoc:jakarta.servlet.Filter[] as a javadoc:org.springframework.context.annotation.Bean[format=annotation] in your application context.
+Jersey has some native Spring support, so we also provide auto-configuration support for it in Spring Boot, together with a starter.
+
+To get started with Jersey, include the `spring-boot-starter-jersey` as a dependency and then you need one javadoc:org.springframework.context.annotation.Bean[format=annotation] of type javadoc:org.glassfish.jersey.server.ResourceConfig[] in which you register all the endpoints, as shown in the following example:
+
+include-code::MyJerseyConfig[]
+
+WARNING: Jersey's support for scanning executable archives is rather limited.
+For example, it cannot scan for endpoints in a package found in a xref:how-to:deployment/installing.adoc[fully executable jar file] or in `WEB-INF/classes` when running an executable war file.
+To avoid this limitation, the `packages` method should not be used, and endpoints should be registered individually by using the `register` method, as shown in the preceding example.
+
+For more advanced customizations, you can also register an arbitrary number of beans that implement javadoc:org.springframework.boot.autoconfigure.jersey.ResourceConfigCustomizer[].
+
+All the registered endpoints should be a javadoc:org.springframework.stereotype.Component[format=annotation] with HTTP resource annotations (`@GET` and others), as shown in the following example:
+
+include-code::MyEndpoint[]
+
+Since the javadoc:org.springframework.boot.actuate.endpoint.annotation.Endpoint[format=annotation] is a Spring javadoc:org.springframework.stereotype.Component[format=annotation], its lifecycle is managed by Spring and you can use the javadoc:org.springframework.beans.factory.annotation.Autowired[format=annotation] annotation to inject dependencies and use the javadoc:org.springframework.beans.factory.annotation.Value[format=annotation] annotation to inject external configuration.
+By default, the Jersey servlet is registered and mapped to `/*`.
+You can change the mapping by adding javadoc:jakarta.ws.rs.ApplicationPath[format=annotation] to your javadoc:org.glassfish.jersey.server.ResourceConfig[].
+
+By default, Jersey is set up as a servlet in a javadoc:org.springframework.context.annotation.Bean[format=annotation] of type javadoc:org.springframework.boot.web.servlet.ServletRegistrationBean[] named `jerseyServletRegistration`.
+By default, the servlet is initialized lazily, but you can customize that behavior by setting `spring.jersey.servlet.load-on-startup`.
+You can disable or override that bean by creating one of your own with the same name.
+You can also use a filter instead of a servlet by setting `spring.jersey.type=filter` (in which case, the javadoc:org.springframework.context.annotation.Bean[format=annotation] to replace or override is `jerseyFilterRegistration`).
+The filter has an javadoc:org.springframework.core.annotation.Order[format=annotation], which you can set with `spring.jersey.filter.order`.
+When using Jersey as a filter, a servlet that will handle any requests that are not intercepted by Jersey must be present.
+If your application does not contain such a servlet, you may want to enable the default servlet by setting configprop:server.servlet.register-default-servlet[] to `true`.
+Both the servlet and the filter registrations can be given init parameters by using `spring.jersey.init.*` to specify a map of properties.
+
+
+
 [[web.servlet.embedded-container]]
 == Embedded Servlet Container Support