Merge pull request #1189 from WhiteCat22/1183_update_entity_to_body

[1183] - rename Entity annotation to Body

examples/src/main/java/jaxrs/examples/resource/SampleResource.java

@@ -5,6 +5,7 @@
 
 import jakarta.enterprise.context.RequestScoped;
 import jakarta.inject.Inject;
+import jakarta.ws.rs.Body;
 import jakarta.ws.rs.Consumes;
 import jakarta.ws.rs.GET;
 import jakarta.ws.rs.HeaderParam;
@@ -13,7 +14,6 @@
 import jakarta.ws.rs.Produces;
 import jakarta.ws.rs.QueryParam;
 import jakarta.ws.rs.container.AsyncResponse;
-import jakarta.ws.rs.Entity;
 import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.UriInfo;
 import jakarta.ws.rs.sse.Sse;
@@ -49,10 +49,10 @@ public String getMessage() {
         return bean.getMessage(lang) + " " + who;
     }
 
-    // Use of @Entity is required
+    // Use of @Body is required
     @POST
     @Consumes(MediaType.TEXT_PLAIN)
-    public void putMessage(@QueryParam("override") boolean override, @Entity String message) {
+    public void putMessage(@QueryParam("override") boolean override, @Body String message) {
         if (bean.getMessage(lang).isEmpty() || override) {
             bean.setMessage(message);
         }
@@ -62,7 +62,7 @@ public void putMessage(@QueryParam("override") boolean override, @Entity String
     @POST
     @Path("async")
     @Consumes(MediaType.TEXT_PLAIN)
-    public void putMessageAsync(@QueryParam("override") boolean override, @Entity String message, AsyncResponse ar) {
+    public void putMessageAsync(@QueryParam("override") boolean override, @Body String message, AsyncResponse ar) {
         Executors.newSingleThreadExecutor().submit(() -> {
             if (bean.getMessage(lang).isEmpty() || override) {
                 bean.setMessage(message);

jaxrs-api/src/main/java/jakarta/ws/rs/BeanParam.java

@@ -30,7 +30,7 @@
  * <p>
  * The JAX-RS runtime will instantiate the object and inject all it's fields and properties annotated with either one of
  * the {@code @XxxParam} annotation ({@link PathParam &#64;PathParam}, {@link FormParam &#64;FormParam} ...) or the
- * {@link Entity &#64;Entity} annotation. For the POJO classes same instantiation and injection rules
+ * {@link Body &#64;Body} annotation. For the POJO classes same instantiation and injection rules
  * apply as in case of instantiation and injection of request-scoped root resource classes.
  * </p>
  * For example:

jaxrs-api/src/main/java/jakarta/ws/rs/Entity.java → jaxrs-api/src/main/java/jakarta/ws/rs/Body.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2021, 2023 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0, which is available at
@@ -23,13 +23,13 @@
 import java.lang.annotation.Target;
 
 /**
- * <p>Annotation that identifies the entity parameter.</p>
+ * <p>Annotation that identifies the body parameter.</p>
  *
  * @author Santiago Pericas-Geertsen
  * @since 4.0
  */
 @Target({ ElementType.PARAMETER })
 @Retention(RetentionPolicy.RUNTIME)
 @Documented
-public @interface Entity {
+public @interface Body {
 }

jaxrs-spec/src/main/asciidoc/chapters/asynchronous_processing/_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
@@ -30,7 +30,7 @@ Let us illustrate these concepts via an example:
 public class MyResource {
 
     @GET
-    public void longRunningOp(@Suspended final AsyncResponse ar) {
+    public void longRunningOp(final AsyncResponse ar) {
         executor.submit(
             new Runnable() {
                 public void run() {
@@ -44,14 +44,14 @@ public class MyResource {
 ----
 
 A resource method that elects to produce a response asynchronously must
-inject as a method parameter an instance of the class `AsyncResponse`
-using the special annotation `@Suspended`. In the example above, the
-method `longRunningOp` is called upon receiving a `GET` request. Rather
-than producing a response immediately, this method forks a (non-request)
-thread to execute a long running operation and returns immediately. Once
-the execution of the long running operation is complete, the connection
-is resumed and the response returned by calling `resume` on the injected
-instance of `AsyncResponse`.
+have an instance of the class `AsyncResponse` as a method parameter.
+
+In the example above, the method `longRunningOp` is called upon receiving
+a `GET` request. Rather than producing a response immediately, this method
+forks a (non-request) thread to execute a long running operation and returns
+immediately. Once the execution of the long running operation is complete,
+the connection is resumed and the response returned by calling `resume` on
+the injected instance of `AsyncResponse`.
 
 For more information on executors, concurrency and thread management in
 a Jakarta EE environment, the reader is referred to Jakarta Concurrency
@@ -71,7 +71,7 @@ is resumed.
 [source,java]
 ----
 @GET
-public void longRunningOp(@Suspended final AsyncResponse ar) {
+public void longRunningOp(final AsyncResponse ar) {
     // Register handler and set timeout
     ar.setTimeoutHandler(new TimeoutHandler() {
         public void handleTimeout(AsyncResponse ar) {

jaxrs-spec/src/main/asciidoc/chapters/resources/_resource_method.adoc

@@ -55,7 +55,8 @@ parameters. See <<consuming_multipart_formdata>> for more details.
 
 The value of a parameter not annotated with `@FormParam` or any of the
 annotations listed in in <<resource_field>>, called the entity
-parameter, is mapped from the request entity body. Conversion between an
+parameter, is mapped from the request entity body. This parameter MUST
+be annotated with the `@Body` annotation. Conversion between an
 entity body and a Java type is the responsibility of an entity provider,
 see <<entity_providers>>. Resource methods MUST have at most one
 entity parameter.