Polish cache javadoc

Issue: SPR-13746

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 "";
 

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 "";

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 "";

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

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