From 3a41a4dd349002b5c4703a4a5b891418266df3d8 Mon Sep 17 00:00:00 2001 From: Jim Krueger <31767744+jim-krueger@users.noreply.github.com> Date: Mon, 4 Dec 2023 14:29:53 -0600 Subject: [PATCH] M1 spec changes1 (#1192) * Initial M1 Spec Changes * Review comment corrections --- .../chapters/appendix/_annotation_table.adoc | 8 +- .../chapters/appendix/_change-log.adoc | 4 +- .../appendix/_changes-since-3.1-release.adoc | 19 +++++ .../asynchronous_processing/_async_ejbs.adoc | 4 +- .../chapters/context/_contexttypes.adoc | 76 ++++++++++--------- .../chapters/environment/_javaee.adoc | 4 +- .../environment/_servlet_container.adoc | 4 +- .../chapters/introduction/_status.adoc | 14 ++-- .../providers/_lifecycle_and_environment.adoc | 20 +++-- .../chapters/resources/_resource-classes.adoc | 8 +- .../chapters/resources/_resource_field.adoc | 9 +-- .../chapters/sse/_sse_broadcasting.adoc | 6 +- .../chapters/sse/_sse_server_api.adoc | 6 +- .../_validation_and_error_reporting.adoc | 11 ++- 14 files changed, 106 insertions(+), 87 deletions(-) create mode 100644 jaxrs-spec/src/main/asciidoc/chapters/appendix/_changes-since-3.1-release.adoc diff --git a/jaxrs-spec/src/main/asciidoc/chapters/appendix/_annotation_table.adoc b/jaxrs-spec/src/main/asciidoc/chapters/appendix/_annotation_table.adoc index 786bcd165..cdac0c538 100644 --- a/jaxrs-spec/src/main/asciidoc/chapters/appendix/_annotation_table.adoc +++ b/jaxrs-spec/src/main/asciidoc/chapters/appendix/_annotation_table.adoc @@ -1,6 +1,6 @@ //// ******************************************************************* -* Copyright (c) 2019 Eclipse Foundation +* Copyright (c) 2019, 2023 Eclipse Foundation * * This specification document is made available under the terms * of the Eclipse Foundation Specification License v1.0, which is @@ -85,9 +85,6 @@ interface. |`NameBinding` |Annotation |Meta-annotation to create annotations for binding filters or interceptors to resource methods and applications. Name binding is only supported as part of the Server API. -|`Suspended` |Parameter |Indicates that a resource method is asynchronous. I.e., that -it does not produce a response upon returning. JAX-RS implementations -will suspend the incoming connection until a response becomes available. |`PreMatching` |Type |Global binding annotation that can be applied to a container filter to indicate that it should be applied globally and before the resource method is matched. @@ -101,4 +98,7 @@ API. If omitted, a provider can be used in either context. |`ParamConverter.Lazy` |Type |Indicates that a conversion of a default value delegated to a `ParamConverter` SHOULD occur only when the value is actually requested. +3+|*Since JAX-RS 3.1* +|`Body` |Annotation |Indicates the entity parameter mapped from the +request entity body. |=============================================== diff --git a/jaxrs-spec/src/main/asciidoc/chapters/appendix/_change-log.adoc b/jaxrs-spec/src/main/asciidoc/chapters/appendix/_change-log.adoc index 75871f42c..316fd9126 100644 --- a/jaxrs-spec/src/main/asciidoc/chapters/appendix/_change-log.adoc +++ b/jaxrs-spec/src/main/asciidoc/chapters/appendix/_change-log.adoc @@ -1,6 +1,6 @@ //// ******************************************************************* -* Copyright (c) 2019 Eclipse Foundation +* Copyright (c) 2019, 2023 Eclipse Foundation * * This specification document is made available under the terms * of the Eclipse Foundation Specification License v1.0, which is @@ -12,6 +12,8 @@ [[change-log]] == Change Log +include::_changes-since-3.1-release.adoc[] + include::_changes-since-3.0-release.adoc[] include::_changes-since-2.1-release.adoc[] diff --git a/jaxrs-spec/src/main/asciidoc/chapters/appendix/_changes-since-3.1-release.adoc b/jaxrs-spec/src/main/asciidoc/chapters/appendix/_changes-since-3.1-release.adoc new file mode 100644 index 000000000..3b879904f --- /dev/null +++ b/jaxrs-spec/src/main/asciidoc/chapters/appendix/_changes-since-3.1-release.adoc @@ -0,0 +1,19 @@ +//// +******************************************************************* +* Copyright (c) 2023 Eclipse Foundation +* +* This specification document is made available under the terms +* of the Eclipse Foundation Specification License v1.0, which is +* available at https://www.eclipse.org/legal/efsl.php. +******************************************************************* +//// + +[[changes-since-3.1-release]] +=== Changes Since 3.1 Release + +* <>: Removal of `@Context` +injection to better align with Jakarta CDI. +* <>: Added `@Body` to indicates the entity parameter mapped from the +request entity body. +* Removed `@Suspended` annotation due to Jakarata CDI alignment. +* Removed `Link.JaxbLink` and `Link.JaxbAdapter` inner classes. diff --git a/jaxrs-spec/src/main/asciidoc/chapters/asynchronous_processing/_async_ejbs.adoc b/jaxrs-spec/src/main/asciidoc/chapters/asynchronous_processing/_async_ejbs.adoc index cbafbb035..fca95c6bf 100644 --- a/jaxrs-spec/src/main/asciidoc/chapters/asynchronous_processing/_async_ejbs.adoc +++ b/jaxrs-spec/src/main/asciidoc/chapters/asynchronous_processing/_async_ejbs.adoc @@ -1,6 +1,6 @@ //// ******************************************************************* -* Copyright (c) 2019 Eclipse Foundation +* Copyright (c) 2019, 2023 Eclipse Foundation * * This specification document is made available under the terms * of the Eclipse Foundation Specification License v1.0, which is @@ -27,7 +27,7 @@ Consider the following example: class EJBResource { @GET @Asynchronous - public void longRunningOp(@Suspended AsyncResponse ar) { + public void longRunningOp(AsyncResponse ar) { executeLongRunningOp(); ar.resume("Hello async world!"); } diff --git a/jaxrs-spec/src/main/asciidoc/chapters/context/_contexttypes.adoc b/jaxrs-spec/src/main/asciidoc/chapters/context/_contexttypes.adoc index 13a1a0577..b89cddefd 100644 --- a/jaxrs-spec/src/main/asciidoc/chapters/context/_contexttypes.adoc +++ b/jaxrs-spec/src/main/asciidoc/chapters/context/_contexttypes.adoc @@ -1,6 +1,6 @@ //// ******************************************************************* -* Copyright (c) 2019 Eclipse Foundation +* Copyright (c) 2019, 2023 Eclipse Foundation * * This specification document is made available under the terms * of the Eclipse Foundation Specification License v1.0, which is @@ -21,26 +21,26 @@ other types are server-side only. ==== Application The instance of the application-supplied `Application` subclass can be -injected into a class field or method parameter using the -`@Context` annotation. Access to the `Application` subclass instance -allows configuration information to be centralized in that class. Note -that this cannot be injected into the `Application` subclass itself -since this would create a circular dependency. +injected into a resource method parameter, since it is a CDI bean, or injected into +a class field using the`@Inject` annotation. Access to the +`Application` subclass instance allows configuration information to be +centralized in that class. Note that this cannot be injected into the +`Application` subclass itself since this would create a circular dependency. [[uris-and-uri-templates]] ==== URIs and URI Templates -An instance of `UriInfo` can be injected into a class field or method -parameter using the `@Context` annotation. `UriInfo` provides both -static and dynamic, per-request information, about the components of a -request URI. E.g. the following would return the names of any query -parameters in a request: +An instance of `UriInfo` can be injected into a resource method parameter, since it +is a CDI bean, or injected into a class field using the `@Inject` annotation. +`UriInfo` provides both static and dynamic, per-request information, about +the components of a request URI. E.g. the following would return the names of +any query parameters in a request: [source,java] ---- @GET @Produces("text/plain") -public String listQueryParamNames(@Context UriInfo info) { +public String listQueryParamNames(UriInfo info) { StringBuilder buf = new StringBuilder(); for (String param: info.getQueryParameters().keySet()) { buf.append(param); @@ -56,17 +56,17 @@ information following the pre-processing described in <>. [[httpheaders]] ==== Headers -An instance of `HttpHeaders` can be injected into a class field or -method parameter using the `@Context` annotation. `HttpHeaders` provides -access to request header information either in map form or via strongly -typed convenience methods. E.g. the following would return the names of -all the headers in a request: +An instance of `HttpHeaders` can be injected into a resource method parameter, +since it is a CDI bean, or injected into a class field using the +`@Inject` annotation. `HttpHeaders` provides access to request header +information either in map form or via strongly typed convenience methods. +E.g. the following would return the names of all the headers in a request: [source,java] ---- @GET @Produces("text/plain") -public String listHeaderNames(@Context HttpHeaders headers) { +public String listHeaderNames(HttpHeaders headers) { StringBuilder buf = new StringBuilder(); for (String header: headers.getRequestHeaders().keySet()) { buf.append(header); @@ -87,19 +87,20 @@ Response headers may be provided using the `Response` class, see JAX-RS simplifies support for content negotiation and preconditions using the `Request` interface. An instance of `Request` can be injected -into a class field or method parameter using the `@Context` annotation. -The methods of `Request` allow a caller to determine the best matching -representation variant and to evaluate whether the current state of the -resource matches any preconditions in the request. Precondition support -methods return a `ResponseBuilder` that can be returned to the client to -inform it that the request preconditions were not met. E.g. the -following checks if the current entity tag matches any preconditions in -the request before updating the resource: +into a method parameter, since it is a CDI bean, or injected into a +class field using the `@Inject` annotation. The methods of `Request` +allow a caller to determine the best matching representation variant +and to evaluate whether the current state of the resource matches any +preconditions in the request. Precondition support methods return a +`ResponseBuilder` that can be returned to the client to inform it that +the request preconditions were not met. E.g. the following checks if +the current entity tag matches any preconditions in the request before +updating the resource: [source,java] ---- @PUT -public Response updateFoo(@Context Request request, Foo foo) { +public Response updateFoo(Request request, Foo foo) { EntityTag tag = getCurrentTag(); ResponseBuilder responseBuilder = request.evaluatePreconditions(tag); if (responseBuilder != null) @@ -118,18 +119,19 @@ building the response. The `SecurityContext` interface provides access to information about the security context of the current request. An instance of -`SecurityContext` can be injected into a class field or method parameter -using the `@Context` annotation. The methods of -`SecurityContext` provide access to the current user principal, -information about roles assumed by the requester, whether the request -arrived over a secure channel and the authentication scheme used. +`SecurityContext` can be injected into a method parameter, since it is a +CDI bean, or injected into a class field using the `@Inject` annotation. +The methods of `SecurityContext` provide access to the current user +principal, information about roles assumed by the requester, whether +the request arrived over a secure channel and the authentication scheme used. [[providercontext]] ==== Providers The `Providers` interface allows for lookup of provider instances based on a set of search criteria. An instance of `Providers` can be injected -into a class field or method parameter using the `@Context` annotation. +into a method parameter, since it is a CDI bean, or injected into a +class field using the `@Inject` annotation. This interface is expected to be primarily of interest to provider authors wishing to use other providers functionality. It is injectable @@ -151,7 +153,7 @@ modifications: ---- @Path("widgets") public class WidgetsResource { - @Context + @Inject private ResourceContext rc; @Path("{id}") @@ -161,7 +163,7 @@ public class WidgetsResource { } public class WidgetResource { - @Context + @Inject private HttpHeaders headers; public WidgetResource(String id) {...} @@ -180,7 +182,7 @@ before it is returned. Without this step, the `headers` field in ==== Configuration Both the client and the server runtime configurations are available for -injection via `@Context`. These configurations are available for +injection via `@Inject`. These configurations are available for injection in providers (client or server) and resource classes (server only). @@ -192,7 +194,7 @@ enabled during the processing of a request: ---- public class LoggingFilter implements ClientRequestFilter { - @Context + @Inject private Configuration config; @Override diff --git a/jaxrs-spec/src/main/asciidoc/chapters/environment/_javaee.adoc b/jaxrs-spec/src/main/asciidoc/chapters/environment/_javaee.adoc index 3c8992df7..ec4bac3cf 100644 --- a/jaxrs-spec/src/main/asciidoc/chapters/environment/_javaee.adoc +++ b/jaxrs-spec/src/main/asciidoc/chapters/environment/_javaee.adoc @@ -1,6 +1,6 @@ //// ******************************************************************* -* Copyright (c) 2019, 2020 Eclipse Foundation +* Copyright (c) 2019, 2023 Eclipse Foundation * * This specification document is made available under the terms * of the Eclipse Foundation Specification License v1.0, which is @@ -31,7 +31,7 @@ JAX-RS implementation to support asynchronous processing when running on a Servlet container whose version is prior to 3. As explained in <>, injection of -Servlet-defined types is possible using the `@Context` annotation. +Servlet-defined types is possible using the `@Inject` annotation. Additionally, web application’s `` and servlet’s `` can be used to define application properties passed to server-side features or injected into server-side JAX-RS components. See diff --git a/jaxrs-spec/src/main/asciidoc/chapters/environment/_servlet_container.adoc b/jaxrs-spec/src/main/asciidoc/chapters/environment/_servlet_container.adoc index e6a19142c..45690c6ab 100644 --- a/jaxrs-spec/src/main/asciidoc/chapters/environment/_servlet_container.adoc +++ b/jaxrs-spec/src/main/asciidoc/chapters/environment/_servlet_container.adoc @@ -1,6 +1,6 @@ //// ******************************************************************* -* Copyright (c) 2019 Eclipse Foundation +* Copyright (c) 2019, 2023 Eclipse Foundation * * This specification document is made available under the terms * of the Eclipse Foundation Specification License v1.0, which is @@ -11,7 +11,7 @@ [[servlet_container]] === Servlet Container -The `@Context` annotation can be used to indicate a dependency on a +The `@Inject` annotation can be used to indicate a dependency on a Servlet-defined resource. A Servlet-based implementation MUST support injection of the following Servlet-defined types: `ServletConfig`, `ServletContext`, `HttpServletRequest` and `HttpServletResponse`. diff --git a/jaxrs-spec/src/main/asciidoc/chapters/introduction/_status.adoc b/jaxrs-spec/src/main/asciidoc/chapters/introduction/_status.adoc index f5eb9be8d..7915ce474 100644 --- a/jaxrs-spec/src/main/asciidoc/chapters/introduction/_status.adoc +++ b/jaxrs-spec/src/main/asciidoc/chapters/introduction/_status.adoc @@ -1,6 +1,6 @@ //// ******************************************************************* -* Copyright (c) 2019, 2021 Eclipse Foundation +* Copyright (c) 2019, 2023 Eclipse Foundation * * This specification document is made available under the terms * of the Eclipse Foundation Specification License v1.0, which is @@ -11,14 +11,14 @@ [[status]] === Status -This is the final release of version 3.1. The issue tracking system for +This is the M1 release of version 4.0. The issue tracking system for this release can be found at: https://github.com/jakartaee/rest/issues The corresponding Javadocs can be found online at: -https://jakarta.ee/specifications/restful-ws/3.1/apidocs/ +https://jakarta.ee/specifications/restful-ws/4.0/apidocs/ A compatible implementation can be obtained from: @@ -30,9 +30,9 @@ specification, please send comments to: jaxrs-dev@eclipse.org [[context-injection]] -==== Support for @Context Injection +==== @Context Injection Removed As part of an effort to better align with https://jakarta.ee/specifications/cdi/[Jakarta CDI], -future versions of this API will no longer support `@Context` injection and related types such as -`ContextResolver`. As much as possible, all injection tasks will be delegated to -Jakarta CDI for a better integration into the https://jakarta.ee/[Jakarta EE] ecosystem. +support for `@Context` injection and related types such as `ContextResolver` have been removed. +All injection tasks have been delegated to Jakarta CDI for a better integration into the +https://jakarta.ee/[Jakarta EE] ecosystem. diff --git a/jaxrs-spec/src/main/asciidoc/chapters/providers/_lifecycle_and_environment.adoc b/jaxrs-spec/src/main/asciidoc/chapters/providers/_lifecycle_and_environment.adoc index 122159cac..aefba51d3 100644 --- a/jaxrs-spec/src/main/asciidoc/chapters/providers/_lifecycle_and_environment.adoc +++ b/jaxrs-spec/src/main/asciidoc/chapters/providers/_lifecycle_and_environment.adoc @@ -1,6 +1,6 @@ //// ******************************************************************* -* Copyright (c) 2019 Eclipse Foundation +* Copyright (c) 2019, 2023 Eclipse Foundation * * This specification document is made available under the terms * of the Eclipse Foundation Specification License v1.0, which is @@ -14,11 +14,10 @@ By default a single instance of each provider class is instantiated for each JAX-RS application. First the constructor (see <>) is called, then any requested dependencies -are injected (see Chapter <>), then the appropriate provider -methods may be called multiple times (simultaneously), and finally the -object is made available for garbage collection. -<> describes how a provider obtains access to other -providers via dependency injection. +are injected, then the appropriate provider methods may be called multiple +times (simultaneously), and finally the object is made available for +garbage collection. <> describes how a provider obtains +access to other providers via dependency injection. An implementation MAY offer other provider lifecycles, mechanisms for specifying these are outside the scope of this specification. E.g. an @@ -63,11 +62,10 @@ have a public constructor for which the JAX-RS runtime can provide all parameter values. Note that a zero argument constructor is permissible under this rule. -A public constructor MAY include parameters annotated with -`@Context`—Chapter <> defines the parameter types permitted for -this annotation. Since providers may be created outside the scope of a -particular request, only deployment-specific properties may be available -from injected interfaces at construction time; request-specific +A public constructor MAY include injected parameters, provided the +parameter type is a CDI bean. Since providers may be created outside the +scope of a particular request, only deployment-specific properties may +be available from injected interfaces at construction time; request-specific properties are available when a provider method is called. If more than one public constructor can be used then an implementation MUST use the one with the most parameters. Choosing amongst constructors with the diff --git a/jaxrs-spec/src/main/asciidoc/chapters/resources/_resource-classes.adoc b/jaxrs-spec/src/main/asciidoc/chapters/resources/_resource-classes.adoc index 27ac1954c..15f67de7e 100644 --- a/jaxrs-spec/src/main/asciidoc/chapters/resources/_resource-classes.adoc +++ b/jaxrs-spec/src/main/asciidoc/chapters/resources/_resource-classes.adoc @@ -40,10 +40,10 @@ parameter values. Note that a zero argument constructor is permissible under this rule. A public constructor MAY include parameters annotated with one of the -following: `@Context`, `@HeaderParam`, `@CookieParam`, `@MatrixParam`, -`@QueryParam` or `@PathParam`. However, depending on the resource class -lifecycle and concurrency, per-request information may not make sense in -a constructor. If more than one public constructor is suitable then an +following: `@HeaderParam`, `@CookieParam`, `@MatrixParam`, `@QueryParam` or +`@PathParam`. However, depending on the resource class lifecycle and +concurrency, per-request information may not make sense in a +constructor. If more than one public constructor is suitable then an implementation MUST use the one with the most parameters. Choosing amongst suitable constructors with the same number of parameters is implementation specific, implementations SHOULD generate a warning about diff --git a/jaxrs-spec/src/main/asciidoc/chapters/resources/_resource_field.adoc b/jaxrs-spec/src/main/asciidoc/chapters/resources/_resource_field.adoc index ab07dc36b..838cc7ce1 100644 --- a/jaxrs-spec/src/main/asciidoc/chapters/resources/_resource_field.adoc +++ b/jaxrs-spec/src/main/asciidoc/chapters/resources/_resource_field.adoc @@ -25,12 +25,11 @@ according to the semantics of the annotation: Extracts the value of a cookie. `@HeaderParam`:: Extracts the value of a header. -`@Context`:: - Injects an instance of a supported resource, see chapters <> - and <> for more details. +`@Inject`:: + Injects an instance of a supported resource. Because injection occurs at object creation time, use of these -annotations (with the exception of `@Context`) on resource class fields +annotations (with the exception of `@Inject`) on resource class fields and bean properties is only supported for the default per-request resource class lifecycle. An implementation SHOULD warn if resource classes with other lifecycles use these annotations on resource class @@ -42,7 +41,7 @@ returned by sub-resource locators (see <>) are expected to be initialized by their creator. Valid parameter types for each of the above annotations are listed in -the corresponding Javadoc, however in general (excluding `@Context`) the +the corresponding Javadoc, however in general (excluding `@Inject`) the following types are supported: 1. Types for which a `ParamConverter` is available via diff --git a/jaxrs-spec/src/main/asciidoc/chapters/sse/_sse_broadcasting.adoc b/jaxrs-spec/src/main/asciidoc/chapters/sse/_sse_broadcasting.adoc index 9c43da1f0..ccb31b95a 100644 --- a/jaxrs-spec/src/main/asciidoc/chapters/sse/_sse_broadcasting.adoc +++ b/jaxrs-spec/src/main/asciidoc/chapters/sse/_sse_broadcasting.adoc @@ -1,6 +1,6 @@ //// ******************************************************************* -* Copyright (c) 2019 Eclipse Foundation +* Copyright (c) 2019, 2023 Eclipse Foundation * * This specification document is made available under the terms * of the Eclipse Foundation Specification License v1.0, which is @@ -27,7 +27,7 @@ note the `@Singleton` annotation on the resource class: @Singleton public class SseResource { - @Context + @Inject private Sse sse; private volatile SseBroadcaster sseBroadcaster; @@ -40,7 +40,7 @@ public class SseResource { @GET @Path("register") @Produces(MediaType.SERVER_SENT_EVENTS) - public void register(@Context SseEventSink eventSink) { + public void register(SseEventSink eventSink) { eventSink.send(sse.newEvent("welcome!")); sseBroadcaster.register(eventSink); } diff --git a/jaxrs-spec/src/main/asciidoc/chapters/sse/_sse_server_api.adoc b/jaxrs-spec/src/main/asciidoc/chapters/sse/_sse_server_api.adoc index 341c95162..21a35f63f 100644 --- a/jaxrs-spec/src/main/asciidoc/chapters/sse/_sse_server_api.adoc +++ b/jaxrs-spec/src/main/asciidoc/chapters/sse/_sse_server_api.adoc @@ -1,6 +1,6 @@ //// ******************************************************************* -* Copyright (c) 2019 Eclipse Foundation +* Copyright (c) 2019, 2023 Eclipse Foundation * * This specification document is made available under the terms * of the Eclipse Foundation Specification License v1.0, which is @@ -24,8 +24,8 @@ thread to send 3 events before closing the connection: @GET @Path("eventStream") @Produces(MediaType.SERVER_SENT_EVENTS) -public void eventStream(@Context SseEventSink eventSink, - @Context Sse sse) { +public void eventStream(SseEventSink eventSink, + Sse sse) { executor.execute(() -> { try (SseEventSink sink = eventSink) { eventSink.send(sse.newEvent("event1")); diff --git a/jaxrs-spec/src/main/asciidoc/chapters/validation/_validation_and_error_reporting.adoc b/jaxrs-spec/src/main/asciidoc/chapters/validation/_validation_and_error_reporting.adoc index 9d3056800..399f2f676 100644 --- a/jaxrs-spec/src/main/asciidoc/chapters/validation/_validation_and_error_reporting.adoc +++ b/jaxrs-spec/src/main/asciidoc/chapters/validation/_validation_and_error_reporting.adoc @@ -1,6 +1,6 @@ //// ******************************************************************* -* Copyright (c) 2019 Eclipse Foundation +* Copyright (c) 2019, 2023 Eclipse Foundation * * This specification document is made available under the terms * of the Eclipse Foundation Specification License v1.0, which is @@ -13,11 +13,10 @@ Constraint annotations are allowed in the same locations as the following annotations: `@MatrixParam`, `@QueryParam`, `@PathParam`, -`@CookieParam`, `@HeaderParam` and `@Context`, _except_ in class -constructors and property setters. Specifically, they are allowed in -resource method parameters, fields and property getters as well as -resource classes, entity parameters and resource methods (return -values). +`@CookieParam`, and `@HeaderParam`, _except_ in class constructors and +property setters. Specifically, they are allowed in resource method +parameters, fields and property getters as well as resource classes, +entity parameters and resource methods (return values). The default resource class instance lifecycle is per-request in JAX-RS. Implementations MAY support other lifecycles; the same caveats related