mirror of
https://github.com/spring-projects/spring-framework
synced 2026-06-08 17:33:33 +00:00
Polish cache javadoc
Issue: SPR-13746
(cherry picked from commit 34b596c)
This commit is contained in:
Stephane Nicoll
committed by
Juergen Hoeller
Juergen Hoeller
parent
e4faaa3786
commit
f7492348ba
+60
-22
@@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright 2002-2014 the original author or authors.
|
||||
* Copyright 2002-2015 the original author or authors.
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
@@ -24,8 +24,8 @@ import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* Annotation indicating that a method (or all methods on a class) trigger(s)
|
||||
* a cache invalidate operation.
|
||||
* Annotation indicating that a method (or all methods on a class) triggers a
|
||||
* {@link org.springframework.cache.Cache#evict(Object) cache evict} operation.
|
||||
*
|
||||
* @author Costin Leau
|
||||
* @author Stephane Nicoll
|
||||
@@ -39,22 +39,39 @@ import java.lang.annotation.Target;
|
||||
public @interface CacheEvict {
|
||||
|
||||
/**
|
||||
* Qualifier value for the specified cached operation.
|
||||
* <p>May be used to determine the target cache (or caches), matching the qualifier
|
||||
* value (or the bean name(s)) of (a) specific bean definition.
|
||||
* Names of the caches to use for the cache eviction operation.
|
||||
* <p>Names may be used to determine the target cache (or caches), matching
|
||||
* the qualifier value or bean name of a specific bean definition.
|
||||
* @see CacheConfig#cacheNames
|
||||
*/
|
||||
String[] value() default {};
|
||||
|
||||
/**
|
||||
* Spring Expression Language (SpEL) attribute for computing the key dynamically.
|
||||
* <p>Default is "", meaning all method parameters are considered as a key, unless
|
||||
* a custom {@link #keyGenerator()} has been set.
|
||||
* 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 "";
|
||||
|
||||
/**
|
||||
* The bean name of the custom {@link org.springframework.cache.interceptor.KeyGenerator} to use.
|
||||
* <p>Mutually exclusive with the {@link #key()} attribute.
|
||||
* The bean name of the custom {@link org.springframework.cache.interceptor.KeyGenerator}
|
||||
* to use.
|
||||
* <p>Mutually exclusive with the {@link #key} attribute.
|
||||
* @see CacheConfig#keyGenerator
|
||||
*/
|
||||
String keyGenerator() default "";
|
||||
|
||||
@@ -62,34 +79,55 @@ public @interface CacheEvict {
|
||||
* The bean name of the custom {@link org.springframework.cache.CacheManager} to use to
|
||||
* create a default {@link org.springframework.cache.interceptor.CacheResolver} if none
|
||||
* is set already.
|
||||
* <p>Mutually exclusive with the {@link #cacheResolver()} attribute.
|
||||
* <p>Mutually exclusive with the {@link #cacheResolver} attribute.
|
||||
* @see org.springframework.cache.interceptor.SimpleCacheResolver
|
||||
* @see CacheConfig#cacheManager
|
||||
*/
|
||||
String cacheManager() default "";
|
||||
|
||||
/**
|
||||
* The bean name of the custom {@link org.springframework.cache.interceptor.CacheResolver} to use.
|
||||
* The bean name of the custom {@link org.springframework.cache.interceptor.CacheResolver}
|
||||
* to use.
|
||||
* @see CacheConfig#cacheResolver
|
||||
*/
|
||||
String cacheResolver() default "";
|
||||
|
||||
/**
|
||||
* Spring Expression Language (SpEL) attribute used for conditioning the method caching.
|
||||
* <p>Default is "", meaning the method is always cached.
|
||||
* 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 "";
|
||||
|
||||
/**
|
||||
* Whether or not all the entries inside the cache(s) are removed or not. By
|
||||
* default, only the value under the associated key is removed.
|
||||
* <p>Note that setting this parameter to {@code true} and specifying a {@link #key()}
|
||||
* is not allowed.
|
||||
* Whether all the entries inside the cache(s) are removed.
|
||||
* <p>By default, only the value under the associated key is removed.
|
||||
* <p>Note that setting this parameter to {@code true} and specifying a
|
||||
* {@link #key} is not allowed.
|
||||
*/
|
||||
boolean allEntries() default false;
|
||||
|
||||
/**
|
||||
* Whether the eviction should occur after the method is successfully invoked (default)
|
||||
* or before. The latter causes the eviction to occur irrespective of the method outcome (whether
|
||||
* it threw an exception or not) while the former does not.
|
||||
* Whether the eviction should occur before the method is invoked.
|
||||
* <p>Setting this attribute to {@code true}, causes the eviction to
|
||||
* occur irrespective of the method outcome (i.e., whether it threw an
|
||||
* exception or not).
|
||||
* <p>Defaults to {@code false}, meaning that the cache eviction operation
|
||||
* will occur <em>after</em> the advised method is invoked successfully (i.e.,
|
||||
* only if the invocation did not throw an exception).
|
||||
*/
|
||||
boolean beforeInvocation() default false;
|
||||
|
||||
}
|
||||
|
||||
+70
-24
@@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright 2002-2014 the original author or authors.
|
||||
* Copyright 2002-2015 the original author or authors.
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
@@ -23,13 +23,13 @@ import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
import org.springframework.cache.Cache;
|
||||
|
||||
/**
|
||||
* Annotation indicating that a method (or all methods on a class) trigger(s)
|
||||
* a {@link Cache#put(Object, Object)} operation. As opposed to {@link Cacheable} annotation,
|
||||
* this annotation does not cause the target method to be skipped - rather it
|
||||
* always causes the method to be invoked and its result to be placed into the cache.
|
||||
* Annotation indicating that a method (or all methods on a class) triggers a
|
||||
* {@link org.springframework.cache.Cache#put(Object, Object) cache put} operation.
|
||||
*
|
||||
* <p>In contrast to the {@link Cacheable @Cacheable} annotation, this annotation
|
||||
* does not cause the advised method to be skipped. Rather, it always causes the
|
||||
* method to be invoked and its result to be stored in the associated cache.
|
||||
*
|
||||
* @author Costin Leau
|
||||
* @author Phillip Webb
|
||||
@@ -37,29 +37,45 @@ import org.springframework.cache.Cache;
|
||||
* @since 3.1
|
||||
* @see CacheConfig
|
||||
*/
|
||||
@Target({ ElementType.METHOD, ElementType.TYPE })
|
||||
@Target({ElementType.METHOD, ElementType.TYPE})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@Inherited
|
||||
@Documented
|
||||
public @interface CachePut {
|
||||
|
||||
/**
|
||||
* Name of the caches in which the update takes place.
|
||||
* <p>May be used to determine the target cache (or caches), matching the
|
||||
* qualifier value (or the bean name(s)) of (a) specific bean definition.
|
||||
* Names of the caches to use for the cache put operation.
|
||||
* <p>Names may be used to determine the target cache (or caches), matching
|
||||
* the qualifier value or bean name of a specific bean definition.
|
||||
* @see CacheConfig#cacheNames
|
||||
*/
|
||||
String[] value() default {};
|
||||
|
||||
/**
|
||||
* Spring Expression Language (SpEL) attribute for computing the key dynamically.
|
||||
* <p>Default is "", meaning all method parameters are considered as a key, unless
|
||||
* a custom {@link #keyGenerator()} has been set.
|
||||
* 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 "";
|
||||
|
||||
/**
|
||||
* The bean name of the custom {@link org.springframework.cache.interceptor.KeyGenerator} to use.
|
||||
* <p>Mutually exclusive with the {@link #key()} attribute.
|
||||
* The bean name of the custom {@link org.springframework.cache.interceptor.KeyGenerator}
|
||||
* to use.
|
||||
* <p>Mutually exclusive with the {@link #key} attribute.
|
||||
* @see CacheConfig#keyGenerator
|
||||
*/
|
||||
String keyGenerator() default "";
|
||||
|
||||
@@ -67,28 +83,58 @@ public @interface CachePut {
|
||||
* The bean name of the custom {@link org.springframework.cache.CacheManager} to use to
|
||||
* create a default {@link org.springframework.cache.interceptor.CacheResolver} if none
|
||||
* is set already.
|
||||
* <p>Mutually exclusive with the {@link #cacheResolver()} attribute.
|
||||
* <p>Mutually exclusive with the {@link #cacheResolver} attribute.
|
||||
* @see org.springframework.cache.interceptor.SimpleCacheResolver
|
||||
* @see CacheConfig#cacheManager
|
||||
*/
|
||||
String cacheManager() default "";
|
||||
|
||||
/**
|
||||
* The bean name of the custom {@link org.springframework.cache.interceptor.CacheResolver} to use.
|
||||
* The bean name of the custom {@link org.springframework.cache.interceptor.CacheResolver}
|
||||
* to use.
|
||||
* @see CacheConfig#cacheResolver
|
||||
*/
|
||||
String cacheResolver() default "";
|
||||
|
||||
/**
|
||||
* Spring Expression Language (SpEL) attribute used for conditioning the cache update.
|
||||
* <p>Default is "", meaning the method result is always cached.
|
||||
* 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 "";
|
||||
|
||||
/**
|
||||
* Spring Expression Language (SpEL) attribute used to veto the cache update.
|
||||
* <p>Unlike {@link #condition()}, this expression is evaluated after the method
|
||||
* has been called and can therefore refer to the {@code result}. Default is "",
|
||||
* meaning that caching is never vetoed.
|
||||
* Spring Expression Language (SpEL) expression used to veto the cache put operation.
|
||||
* <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 "";
|
||||
|
||||
}
|
||||
|
||||
+72
-26
@@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright 2002-2014 the original author or authors.
|
||||
* Copyright 2002-2015 the original author or authors.
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
@@ -24,17 +24,18 @@ import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* Annotation indicating that a method (or all the methods on a class) can be cached.
|
||||
* Annotation indicating that the result of invoking a method (or all methods
|
||||
* in a class) can be cached.
|
||||
*
|
||||
* <p>Each time a targeted method is invoked, a caching behavior will be applied,
|
||||
* checking whether the method has been already executed for the given arguments. A
|
||||
* sensible default simply uses the method parameters to compute the key but a SpEL
|
||||
* expression can be provided ({@link #key()}) or a custom
|
||||
* {@link org.springframework.cache.interceptor.KeyGenerator KeyGenerator} implementation
|
||||
* can replace the default one ({@link #keyGenerator()}).
|
||||
* <p>Each time an advised method is invoked, caching behavior will be applied,
|
||||
* checking whether the method has been already invoked for the given arguments.
|
||||
* A sensible default simply uses the method parameters to compute the key, but
|
||||
* a SpEL expression can be provided via the {@link #key} attribute, or a custom
|
||||
* {@link org.springframework.cache.interceptor.KeyGenerator} implementation can
|
||||
* replace the default one (see {@link #keyGenerator}).
|
||||
*
|
||||
* <p>If no value is found in the cache for the computed key, the method is executed
|
||||
* and the returned instance is used as the cache value.
|
||||
* <p>If no value is found in the cache for the computed key, the target method
|
||||
* will be invoked and the returned value stored in the associated cache.
|
||||
*
|
||||
* @author Costin Leau
|
||||
* @author Phillip Webb
|
||||
@@ -49,22 +50,37 @@ import java.lang.annotation.Target;
|
||||
public @interface Cacheable {
|
||||
|
||||
/**
|
||||
* Name of the caches in which the update takes place.
|
||||
* <p>May be used to determine the target cache (or caches), matching the
|
||||
* qualifier value (or the bean name(s)) of (a) specific bean definition.
|
||||
* Names of the caches in which method invocation results are stored.
|
||||
* <p>Names may be used to determine the target cache (or caches), matching
|
||||
* the qualifier value or bean name of a specific bean definition.
|
||||
* @see CacheConfig#cacheNames
|
||||
*/
|
||||
String[] value() default {};
|
||||
|
||||
/**
|
||||
* Spring Expression Language (SpEL) attribute for computing the key dynamically.
|
||||
* <p>Default is "", meaning all method parameters are considered as a key, unless
|
||||
* a custom {@link #keyGenerator()} has been set.
|
||||
* 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 "";
|
||||
|
||||
/**
|
||||
* The bean name of the custom {@link org.springframework.cache.interceptor.KeyGenerator} to use.
|
||||
* <p>Mutually exclusive with the {@link #key()} attribute.
|
||||
* The bean name of the custom {@link org.springframework.cache.interceptor.KeyGenerator}
|
||||
* to use.
|
||||
* <p>Mutually exclusive with the {@link #key} attribute.
|
||||
* @see CacheConfig#keyGenerator
|
||||
*/
|
||||
String keyGenerator() default "";
|
||||
|
||||
@@ -72,28 +88,58 @@ public @interface Cacheable {
|
||||
* The bean name of the custom {@link org.springframework.cache.CacheManager} to use to
|
||||
* create a default {@link org.springframework.cache.interceptor.CacheResolver} if none
|
||||
* is set already.
|
||||
* <p>Mutually exclusive with the {@link #cacheResolver()} attribute.
|
||||
* <p>Mutually exclusive with the {@link #cacheResolver} attribute.
|
||||
* @see org.springframework.cache.interceptor.SimpleCacheResolver
|
||||
* @see CacheConfig#cacheManager
|
||||
*/
|
||||
String cacheManager() default "";
|
||||
|
||||
/**
|
||||
* The bean name of the custom {@link org.springframework.cache.interceptor.CacheResolver} to use.
|
||||
* The bean name of the custom {@link org.springframework.cache.interceptor.CacheResolver}
|
||||
* to use.
|
||||
* @see CacheConfig#cacheResolver
|
||||
*/
|
||||
String cacheResolver() default "";
|
||||
|
||||
/**
|
||||
* Spring Expression Language (SpEL) attribute used for conditioning the method caching.
|
||||
* <p>Default is "", meaning the method is always cached.
|
||||
* 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 "";
|
||||
|
||||
/**
|
||||
* Spring Expression Language (SpEL) attribute used to veto method caching.
|
||||
* <p>Unlike {@link #condition()}, this expression is evaluated after the method
|
||||
* has been called and can therefore refer to the {@code result}. Default is "",
|
||||
* meaning that caching is never vetoed.
|
||||
* Spring Expression Language (SpEL) expression used to veto method caching.
|
||||
* <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 "";
|
||||
|
||||
}
|
||||
|
||||
@@ -49634,10 +49634,10 @@ 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>`
|
||||
| Name of any of the method arguments. If for some reason the names are not available
|
||||
(e.g. 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
|
||||
|
||||
Reference in New Issue
Block a user