[1183] - rename Entity annotation to Body

Signed-off-by: Adam Anderson <[email protected]>

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
@@ -29,12 +29,13 @@ Let us illustrate these concepts via an example:
 @Path("/async/longRunning")
 public class MyResource {
 
-    @GET
-    public void longRunningOp(@Suspended final AsyncResponse ar) {
+    @POST
+    public void longRunningOp(final AsyncResponse ar, @Body String message) {
         executor.submit(
             new Runnable() {
                 public void run() {
                     executeLongRunningOp();
+                    ...
                     ar.resume("Hello async world!");
                 }
             });
@@ -44,14 +45,16 @@ 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
+addition, if the request contains a body, the method parameter associated
+with the body must be annotated with `@Body`.
+
+In the example above, the method `longRunningOp` is called upon receiving
+a `POST` 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