From a08cab18a6caf11865203de4d0b6f6343510c3ec Mon Sep 17 00:00:00 2001 From: Georgios Andrianakis Date: Thu, 3 Jun 2021 12:26:58 +0300 Subject: [PATCH] Add documentation for @Cache and @NoCache MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follows up on #17644 Co-authored-by: Stéphane Épardaud --- docs/src/main/asciidoc/resteasy-reactive.adoc | 12 +++++++++++- .../main/java/org/jboss/resteasy/reactive/Cache.java | 3 +++ .../java/org/jboss/resteasy/reactive/NoCache.java | 3 +++ 3 files changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/src/main/asciidoc/resteasy-reactive.adoc b/docs/src/main/asciidoc/resteasy-reactive.adoc index 849f6c7469aab..54369c2262aed 100644 --- a/docs/src/main/asciidoc/resteasy-reactive.adoc +++ b/docs/src/main/asciidoc/resteasy-reactive.adoc @@ -656,6 +656,17 @@ public class Endpoint { } ---- +=== Controlling HTTP Caching features + +RESTEasy Reactive provides the `@org.jboss.resteasy.reactive.Cache` and `@org.jboss.resteasy.reactive.NoCache` annotations to facilitate handling HTTP caching semantics, i.e. setting the 'Cache-Control' HTTP header. + +These annotations can be placed either on a Resource Method or a Resource Class (in which case it applies to all Resource Methods of the class that do *not* contain the same annotation) and allow users +to return domain objects and not have to deal with building up the `Cache-Control` HTTP header explicitly. + +While `@Cache` builds a complex `Cache-Control` header, `@NoCache` is a simplified notation to say that you don't want anything cached; i.e. `Cache-Control: nocache`. + +NOTE: More information on the `Cache-Control` header and be found in link:https://datatracker.ietf.org/doc/html/rfc7234[RFC 7234] + === Accessing context objects [[context-objects]] @@ -1861,4 +1872,3 @@ In addition to the Server side, RESTEasy Reactive comes with a new MicroProfile Please note that the `quarkus-rest-client` extension may not work properly with RESTEasy Reactive. See link:rest-client-reactive.adoc[REST Client Reactive Guide] for more information about the reactive client. - diff --git a/independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/Cache.java b/independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/Cache.java index e2d1cdbda9cde..2bab7931be29d 100644 --- a/independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/Cache.java +++ b/independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/Cache.java @@ -5,6 +5,9 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Allows setting the {@code Cache-Control} header automatically. + */ @Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) public @interface Cache { diff --git a/independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/NoCache.java b/independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/NoCache.java index dd589afd21b75..156fd6e4500f0 100644 --- a/independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/NoCache.java +++ b/independent-projects/resteasy-reactive/common/runtime/src/main/java/org/jboss/resteasy/reactive/NoCache.java @@ -5,6 +5,9 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Allows setting the {@code Cache-Control} response header to {@code nocache} + */ @Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) public @interface NoCache {