root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Polish Javadoc for caching annotations

This commit is contained in:
Sam Brannen 2015-05-31 21:54:49 +02:00
parent 485790dc0e
commit de06f422f3
4 changed files with 92 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
spring-context/src/main/java/org/springframework/cache/annotation/CacheConfig.java vendored
View File

@ -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,23 +23,27 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Provide a way to share common cache-related settings at class-level.
* {@code @CacheConfig} provides a mechanism for sharing common cache-related
* settings at the class level.
*
* <p>When this annotation is present on a given class, it provides a set
* of default settings for any cache operation defined on that class.
* of default settings for any cache operation defined in that class.
*
* @author Stephane Nicoll
* @author Sam Brannen
* @since 4.1
*/
@Target({ElementType.TYPE})
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface CacheConfig {
/**
* Name of the default caches to consider for a caching operation defined in the class.
* <p>If none is set at the operation level, these ones are used instead of the default.
* Names of the default caches to consider for caching operations defined
* in the annotated class.
* <p>If none is set at the operation level, these are used instead of the default.
* <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.
* qualifier value or the bean names of a specific bean definition.
*/
String[] cacheNames() default {};
@ -57,7 +61,7 @@ public @interface CacheConfig {
* create a default {@link org.springframework.cache.interceptor.CacheResolver} if none
* is set already.
* <p>If no resolver and no cache manager are set at the operation level, and no cache
* resolver is set on this instance, this one is used instead of the default.
* resolver is set via {@link #cacheResolver}, this one is used instead of the default.
* @see org.springframework.cache.interceptor.SimpleCacheResolver
*/
String cacheManager() default "";
@ -68,6 +72,5 @@ public @interface CacheConfig {
* instead of the default.
*/
String cacheResolver() default "";
}

45
spring-context/src/main/java/org/springframework/cache/annotation/CacheEvict.java vendored
View File

@ -24,11 +24,12 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Annotation indicating that a method (or all methods on a class) trigger(s)
* Annotation indicating that a method (or all methods on a class) triggers
* a cache eviction operation.
*
* @author Costin Leau
* @author Stephane Nicoll
* @author Sam Brannen
* @since 3.1
* @see CacheConfig
*/
@ -39,22 +40,23 @@ 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.
*/
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.
*/
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.
* <p>Mutually exclusive with the {@link #key} attribute.
* @see CacheConfig#keyGenerator
*/
String keyGenerator() default "";
@ -62,35 +64,42 @@ 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.
* @see CacheConfig#cacheResolver
*/
String cacheResolver() default "";
/**
* Spring Expression Language (SpEL) attribute used for making the cache
* Spring Expression Language (SpEL) expression used for making the cache
* eviction operation conditional.
* <p>Default is "", meaning the cache eviction is always performed.
* <p>Default is {@code ""}, meaning the cache eviction is always performed.
*/
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;
}

43
spring-context/src/main/java/org/springframework/cache/annotation/CachePut.java vendored
View File

@ -26,14 +26,17 @@ 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 {@linkplain 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 a cache.
*
* @author Costin Leau
* @author Phillip Webb
* @author Stephane Nicoll
* @author Sam Brannen
* @since 3.1
* @see CacheConfig
*/
@ -44,22 +47,23 @@ import org.springframework.cache.Cache;
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.
*/
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.
*/
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.
* <p>Mutually exclusive with the {@link #key} attribute.
* @see CacheConfig#keyGenerator
*/
String keyGenerator() default "";
@ -67,29 +71,32 @@ 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.
* @see CacheConfig#cacheResolver
*/
String cacheResolver() default "";
/**
* Spring Expression Language (SpEL) attribute used for making the cache
* Spring Expression Language (SpEL) expression used for making the cache
* put operation conditional.
* <p>Default is "", meaning the method result is always cached.
* <p>Default is {@code ""}, meaning the method result is always cached.
*/
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.
* @since 3.2
*/
String unless() default "";
}

48
spring-context/src/main/java/org/springframework/cache/annotation/Cacheable.java vendored
View File

@ -24,21 +24,23 @@ 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
* <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 KeyGenerator} implementation
* can replace the default one ({@link #keyGenerator()}).
* 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
* <p>If no value is found in the cache for the computed key, the method is invoked
* and the returned value is used as the cache value.
*
* @author Costin Leau
* @author Phillip Webb
* @author Stephane Nicoll
* @author Sam Brannen
* @since 3.1
* @see CacheConfig
*/
@ -49,22 +51,23 @@ 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.
*/
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.
*/
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.
* <p>Mutually exclusive with the {@link #key} attribute.
* @see CacheConfig#keyGenerator
*/
String keyGenerator() default "";
@ -72,29 +75,32 @@ 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.
* @see CacheConfig#cacheResolver
*/
String cacheResolver() default "";
/**
* Spring Expression Language (SpEL) attribute used for making the method
* Spring Expression Language (SpEL) expression used for making the method
* caching conditional.
* <p>Default is "", meaning the method result is always cached.
* <p>Default is {@code ""}, meaning the method result is always cached.
*/
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.
* @since 3.2
*/
String unless() default "";
}