From 34b596c6bfe343251aca3c0b6d7e1f9b2b5807ca Mon Sep 17 00:00:00 2001
From: Stephane Nicoll <snicoll@pivotal.io>
Date: Wed, 9 Dec 2015 11:24:53 +0100
Subject: [PATCH] Polish cache javadoc

Issue: SPR-13746
---
 .../cache/annotation/CacheEvict.java          | 26 +++++++++++++
 .../cache/annotation/CachePut.java            | 38 +++++++++++++++++++
 .../cache/annotation/Cacheable.java           | 37 ++++++++++++++++++
 src/asciidoc/core-beans.adoc                  |  4 +-
 src/asciidoc/integration.adoc                 |  4 +-
 5 files changed, 105 insertions(+), 4 deletions(-)

diff --git a/spring-context/src/main/java/org/springframework/cache/annotation/CacheEvict.java b/spring-context/src/main/java/org/springframework/cache/annotation/CacheEvict.java
index 520ddd6214..2a6f263d2f 100644
--- a/spring-context/src/main/java/org/springframework/cache/annotation/CacheEvict.java
+++ b/spring-context/src/main/java/org/springframework/cache/annotation/CacheEvict.java
@@ -62,6 +62,20 @@ public @interface CacheEvict {
 	 * Spring Expression Language (SpEL) expression for computing the key dynamically.
 	 * <p>Default is {@code ""}, meaning all method parameters are considered as a key, unless
 	 * a custom {@link #keyGenerator} has been set.
+	 * <p>The SpEL expression evaluates again a dedicated context that provides the
+	 * following meta-data:
+	 * <ul>
+	 * <li>{@code #result} for a reference to the result of the method invocation, which
+	 * can only be used if {@link #beforeInvocation()} is {@code false}.</li>
+	 * <li>{@code #root.method}, {@code #root.target} and {@code #root.caches} for a
+	 * reference to the {@link java.lang.reflect.Method method}, target object and
+	 * affected cache(s) respectively.</li>
+	 * <li>Shortcuts for the method name ({@code #root.methodName}) and target class
+	 * ({@code #root.targetClass}) are also available.
+	 * <li>Method arguments can be accessed by index. For instance the second argument
+	 * can be access via {@code #root.args[1]}, {@code #p1} or {@code #a1}. Arguments
+	 * can also be accessed by name if that information is available.</li>
+	 * </ul>
 	 */
 	String key() default "";
 
@@ -92,6 +106,18 @@ public @interface CacheEvict {
 	 * Spring Expression Language (SpEL) expression used for making the cache
 	 * eviction operation conditional.
 	 * <p>Default is {@code ""}, meaning the cache eviction is always performed.
+	 * <p>The SpEL expression evaluates again a dedicated context that provides the
+	 * following meta-data:
+	 * <ul>
+	 * <li>{@code #root.method}, {@code #root.target} and {@code #root.caches} for a
+	 * reference to the {@link java.lang.reflect.Method method}, target object and
+	 * affected cache(s) respectively.</li>
+	 * <li>Shortcuts for the method name ({@code #root.methodName}) and target class
+	 * ({@code #root.targetClass}) are also available.
+	 * <li>Method arguments can be accessed by index. For instance the second argument
+	 * can be access via {@code #root.args[1]}, {@code #p1} or {@code #a1}. Arguments
+	 * can also be accessed by name if that information is available.</li>
+	 * </ul>
 	 */
 	String condition() default "";
 
diff --git a/spring-context/src/main/java/org/springframework/cache/annotation/CachePut.java b/spring-context/src/main/java/org/springframework/cache/annotation/CachePut.java
index deac117aa8..e198a2731d 100644
--- a/spring-context/src/main/java/org/springframework/cache/annotation/CachePut.java
+++ b/spring-context/src/main/java/org/springframework/cache/annotation/CachePut.java
@@ -68,6 +68,19 @@ public @interface CachePut {
 	 * Spring Expression Language (SpEL) expression for computing the key dynamically.
 	 * <p>Default is {@code ""}, meaning all method parameters are considered as a key, unless
 	 * a custom {@link #keyGenerator} has been set.
+	 * <p>The SpEL expression evaluates again a dedicated context that provides the
+	 * following meta-data:
+	 * <ul>
+	 * <li>{@code #result} for a reference to the result of the method invocation.</li>
+	 * <li>{@code #root.method}, {@code #root.target} and {@code #root.caches} for a
+	 * reference to the {@link java.lang.reflect.Method method}, target object and
+	 * affected cache(s) respectively.</li>
+	 * <li>Shortcuts for the method name ({@code #root.methodName}) and target class
+	 * ({@code #root.targetClass}) are also available.
+	 * <li>Method arguments can be accessed by index. For instance the second argument
+	 * can be access via {@code #root.args[1]}, {@code #p1} or {@code #a1}. Arguments
+	 * can also be accessed by name if that information is available.</li>
+	 * </ul>
 	 */
 	String key() default "";
 
@@ -98,6 +111,18 @@ public @interface CachePut {
 	 * Spring Expression Language (SpEL) expression used for making the cache
 	 * put operation conditional.
 	 * <p>Default is {@code ""}, meaning the method result is always cached.
+	 * <p>The SpEL expression evaluates again a dedicated context that provides the
+	 * following meta-data:
+	 * <ul>
+	 * <li>{@code #root.method}, {@code #root.target} and {@code #root.caches} for a
+	 * reference to the {@link java.lang.reflect.Method method}, target object and
+	 * affected cache(s) respectively.</li>
+	 * <li>Shortcuts for the method name ({@code #root.methodName}) and target class
+	 * ({@code #root.targetClass}) are also available.
+	 * <li>Method arguments can be accessed by index. For instance the second argument
+	 * can be access via {@code #root.args[1]}, {@code #p1} or {@code #a1}. Arguments
+	 * can also be accessed by name if that information is available.</li>
+	 * </ul>
 	 */
 	String condition() default "";
 
@@ -106,6 +131,19 @@ public @interface CachePut {
 	 * <p>Unlike {@link #condition}, this expression is evaluated after the method
 	 * has been called and can therefore refer to the {@code result}.
 	 * <p>Default is {@code ""}, meaning that caching is never vetoed.
+	 * <p>The SpEL expression evaluates again a dedicated context that provides the
+	 * following meta-data:
+	 * <ul>
+	 * <li>{@code #result} for a reference to the result of the method invocation.</li>
+	 * <li>{@code #root.method}, {@code #root.target} and {@code #root.caches} for a
+	 * reference to the {@link java.lang.reflect.Method method}, target object and
+	 * affected cache(s) respectively.</li>
+	 * <li>Shortcuts for the method name ({@code #root.methodName}) and target class
+	 * ({@code #root.targetClass}) are also available.
+	 * <li>Method arguments can be accessed by index. For instance the second argument
+	 * can be access via {@code #root.args[1]}, {@code #p1} or {@code #a1}. Arguments
+	 * can also be accessed by name if that information is available.</li>
+	 * </ul>
 	 * @since 3.2
 	 */
 	String unless() default "";
diff --git a/spring-context/src/main/java/org/springframework/cache/annotation/Cacheable.java b/spring-context/src/main/java/org/springframework/cache/annotation/Cacheable.java
index 9e7697e9bc..d67f84572a 100644
--- a/spring-context/src/main/java/org/springframework/cache/annotation/Cacheable.java
+++ b/spring-context/src/main/java/org/springframework/cache/annotation/Cacheable.java
@@ -73,6 +73,18 @@ public @interface Cacheable {
 	 * Spring Expression Language (SpEL) expression for computing the key dynamically.
 	 * <p>Default is {@code ""}, meaning all method parameters are considered as a key,
 	 * unless a custom {@link #keyGenerator} has been configured.
+	 * <p>The SpEL expression evaluates again a dedicated context that provides the
+	 * following meta-data:
+	 * <ul>
+	 * <li>{@code #root.method}, {@code #root.target} and {@code #root.caches} for a
+	 * reference to the {@link java.lang.reflect.Method method}, target object and
+	 * affected cache(s) respectively.</li>
+	 * <li>Shortcuts for the method name ({@code #root.methodName}) and target class
+	 * ({@code #root.targetClass}) are also available.
+	 * <li>Method arguments can be accessed by index. For instance the second argument
+	 * can be access via {@code #root.args[1]}, {@code #p1} or {@code #a1}. Arguments
+	 * can also be accessed by name if that information is available.</li>
+	 * </ul>
 	 */
 	String key() default "";
 
@@ -103,6 +115,18 @@ public @interface Cacheable {
 	 * Spring Expression Language (SpEL) expression used for making the method
 	 * caching conditional.
 	 * <p>Default is {@code ""}, meaning the method result is always cached.
+	 * <p>The SpEL expression evaluates again a dedicated context that provides the
+	 * following meta-data:
+	 * <ul>
+	 * <li>{@code #root.method}, {@code #root.target} and {@code #root.caches} for a
+	 * reference to the {@link java.lang.reflect.Method method}, target object and
+	 * affected cache(s) respectively.</li>
+	 * <li>Shortcuts for the method name ({@code #root.methodName}) and target class
+	 * ({@code #root.targetClass}) are also available.
+	 * <li>Method arguments can be accessed by index. For instance the second argument
+	 * can be access via {@code #root.args[1]}, {@code #p1} or {@code #a1}. Arguments
+	 * can also be accessed by name if that information is available.</li>
+	 * </ul>
 	 */
 	String condition() default "";
 
@@ -111,6 +135,19 @@ public @interface Cacheable {
 	 * <p>Unlike {@link #condition}, this expression is evaluated after the method
 	 * has been called and can therefore refer to the {@code result}.
 	 * <p>Default is {@code ""}, meaning that caching is never vetoed.
+	 * <p>The SpEL expression evaluates again a dedicated context that provides the
+	 * following meta-data:
+	 * <ul>
+	 * <li>{@code #result} for a reference to the result of the method invocation.</li>
+	 * <li>{@code #root.method}, {@code #root.target} and {@code #root.caches} for a
+	 * reference to the {@link java.lang.reflect.Method method}, target object and
+	 * affected cache(s) respectively.</li>
+	 * <li>Shortcuts for the method name ({@code #root.methodName}) and target class
+	 * ({@code #root.targetClass}) are also available.
+	 * <li>Method arguments can be accessed by index. For instance the second argument
+	 * can be access via {@code #root.args[1]}, {@code #p1} or {@code #a1}. Arguments
+	 * can also be accessed by name if that information is available.</li>
+	 * </ul>
 	 * @since 3.2
 	 */
 	String unless() default "";
diff --git a/src/asciidoc/core-beans.adoc b/src/asciidoc/core-beans.adoc
index 6c2a61c157..b93738bec6 100644
--- a/src/asciidoc/core-beans.adoc
+++ b/src/asciidoc/core-beans.adoc
@@ -8139,9 +8139,9 @@ available to the context so one can use them for conditional event processing:
 | __argument name__
 | evaluation context
 | Name of any of the method argument. If for some reason the names are not available
-  (ex: no debug information), the argument names are also available under the `a<#arg>`
+  (ex: no debug information), the argument names are also available under the `#a<#arg>`
   where __#arg__ stands for the argument index (starting from 0).
-| `iban` or `a0` (one can also use `p0` or `p<#arg>` notation as an alias).
+| `#iban` or `#a0` (one can also use `#p0` or `#p<#arg>` notation as an alias).
 |===
 
 Note that `#root.event` allows you to access to the underlying event, even if your method
diff --git a/src/asciidoc/integration.adoc b/src/asciidoc/integration.adoc
index ec0a9fc2e5..24bbc39084 100644
--- a/src/asciidoc/integration.adoc
+++ b/src/asciidoc/integration.adoc
@@ -8463,9 +8463,9 @@ conditional computations:
 | __argument name__
 | evaluation context
 | Name of any of the method argument. If for some reason the names are not available
-  (ex: no debug information), the argument names are also available under the `a<#arg>`
+  (ex: no debug information), the argument names are also available under the `#a<#arg>`
   where __#arg__ stands for the argument index (starting from 0).
-| `iban` or `a0` (one can also use `p0` or `p<#arg>` notation as an alias).
+| `#iban` or `#a0` (one can also use `#p0` or `#p<#arg>` notation as an alias).
 
 | result
 | evaluation context