M1 spec changes1 (#1192)

* Initial M1 Spec Changes

* Review comment corrections

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.
 |===============================================

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[]

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
+
+* <<context-injection>>: Removal of `@Context`
+injection to better align with Jakarta CDI.
+* <<entity_parameters>>: 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.

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!");
     }

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 <<reqpreproc>>.
 [[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

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 <<servlet_container>>, injection of
-Servlet-defined types is possible using the `@Context` annotation.
+Servlet-defined types is possible using the `@Inject` annotation.
 Additionally, web application’s `<context-param>` and servlet’s
 `<init-param>` can be used to define application properties passed to
 server-side features or injected into server-side JAX-RS components. See

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`.

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.

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
 <<provider_class_constructor>>) is called, then any requested dependencies
-are injected (see Chapter <<context>>), then the appropriate provider
-methods may be called multiple times (simultaneously), and finally the
-object is made available for garbage collection.
-<<providercontext>> 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. <<providercontext>> 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 <<context>> 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

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

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 <<context>>
-  and <<environment>> 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 <<sub_resources>>) 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