From 4195c75eadb7bcc0deeaf0a8b91b5119c6a760da Mon Sep 17 00:00:00 2001 From: Adam Anderson Date: Thu, 19 Oct 2023 15:05:10 -0500 Subject: [PATCH] [1183] - rename Entity annotation to Body Signed-off-by: Adam Anderson --- .../examples/resource/SampleResource.java | 8 +++--- .../main/java/jakarta/ws/rs/BeanParam.java | 2 +- .../jakarta/ws/rs/{Entity.java => Body.java} | 6 ++--- .../asynchronous_processing/_server_api.adoc | 25 +++++++++++-------- 4 files changed, 22 insertions(+), 19 deletions(-) rename jaxrs-api/src/main/java/jakarta/ws/rs/{Entity.java => Body.java} (86%) diff --git a/examples/src/main/java/jaxrs/examples/resource/SampleResource.java b/examples/src/main/java/jaxrs/examples/resource/SampleResource.java index 1f32a40ba..4ebeb1097 100644 --- a/examples/src/main/java/jaxrs/examples/resource/SampleResource.java +++ b/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); diff --git a/jaxrs-api/src/main/java/jakarta/ws/rs/BeanParam.java b/jaxrs-api/src/main/java/jakarta/ws/rs/BeanParam.java index 2b685f759..1f832280a 100644 --- a/jaxrs-api/src/main/java/jakarta/ws/rs/BeanParam.java +++ b/jaxrs-api/src/main/java/jakarta/ws/rs/BeanParam.java @@ -30,7 +30,7 @@ *

* 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 @PathParam}, {@link FormParam @FormParam} ...) or the - * {@link Entity @Entity} annotation. For the POJO classes same instantiation and injection rules + * {@link Body @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. *

* For example: diff --git a/jaxrs-api/src/main/java/jakarta/ws/rs/Entity.java b/jaxrs-api/src/main/java/jakarta/ws/rs/Body.java similarity index 86% rename from jaxrs-api/src/main/java/jakarta/ws/rs/Entity.java rename to jaxrs-api/src/main/java/jakarta/ws/rs/Body.java index c8858fe8e..4261f09d4 100644 --- a/jaxrs-api/src/main/java/jakarta/ws/rs/Entity.java +++ b/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,7 +23,7 @@ import java.lang.annotation.Target; /** - *

Annotation that identifies the entity parameter.

+ *

Annotation that identifies the body parameter.

* * @author Santiago Pericas-Geertsen * @since 4.0 @@ -31,5 +31,5 @@ @Target({ ElementType.PARAMETER }) @Retention(RetentionPolicy.RUNTIME) @Documented -public @interface Entity { +public @interface Body { } diff --git a/jaxrs-spec/src/main/asciidoc/chapters/asynchronous_processing/_server_api.adoc b/jaxrs-spec/src/main/asciidoc/chapters/asynchronous_processing/_server_api.adoc index ecdadc425..5ae9ff028 100644 --- a/jaxrs-spec/src/main/asciidoc/chapters/asynchronous_processing/_server_api.adoc +++ b/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