Polish Javadoc for caching annotations

spring-context/src/main/java/org/springframework/cache/annotation/CacheConfig.java

@@ -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.
+	 * Names of the default caches to consider for caching operations defined
-	 * <p>If none is set at the operation level, these ones are used instead of the default.
+	 * 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 "";
+
 }
-
-

spring-context/src/main/java/org/springframework/cache/annotation/CacheEvict.java

@@ -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.
+	 * Names of the caches to use for the cache eviction operation.
-	 * <p>May be used to determine the target cache (or caches), matching the qualifier
+	 * <p>Names may be used to determine the target cache (or caches), matching
-	 * value (or the bean name(s)) of (a) specific bean definition.
+	 * the qualifier value or bean name of a specific bean definition.
 	 */
 	String[] value() default {};
 
 	/**
-	 * Spring Expression Language (SpEL) attribute for computing the key dynamically.
+	 * Spring Expression Language (SpEL) expression for computing the key dynamically.
-	 * <p>Default is "", meaning all method parameters are considered as a key, unless
+	 * <p>Default is {@code ""}, meaning all method parameters are considered as a key, unless
-	 * a custom {@link #keyGenerator()} has been set.
+	 * 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
+	 * Whether all the entries inside the cache(s) are removed.
-	 * default, only the value under the associated key is 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()}
+	 * <p>Note that setting this parameter to {@code true} and specifying a
-	 * is not allowed.
+	 * {@link #key} is not allowed.
 	 */
 	boolean allEntries() default false;
 
 	/**
-	 * Whether the eviction should occur after the method is successfully invoked (default)
+	 * Whether the eviction should occur before the method is invoked.
-	 * or before. The latter causes the eviction to occur irrespective of the method outcome (whether
+	 * <p>Setting this attribute to {@code true}, causes the eviction to
-	 * it threw an exception or not) while the former does not.
+	 * 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;
+
 }

spring-context/src/main/java/org/springframework/cache/annotation/CachePut.java

@@ -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)
+ * Annotation indicating that a method (or all methods on a class) triggers
- * a {@link Cache#put(Object, Object)} operation. As opposed to {@link Cacheable} annotation,
+ * a {@linkplain Cache#put(Object, Object) cache put} operation.
- * 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.
+ * <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.
+	 * Names of the caches to use for the cache put operation.
-	 * <p>May be used to determine the target cache (or caches), matching the
+	 * <p>Names may be used to determine the target cache (or caches), matching
-	 * qualifier value (or the bean name(s)) of (a) specific bean definition.
+	 * the qualifier value or bean name of a specific bean definition.
 	 */
 	String[] value() default {};
 
 	/**
-	 * Spring Expression Language (SpEL) attribute for computing the key dynamically.
+	 * Spring Expression Language (SpEL) expression for computing the key dynamically.
-	 * <p>Default is "", meaning all method parameters are considered as a key, unless
+	 * <p>Default is {@code ""}, meaning all method parameters are considered as a key, unless
-	 * a custom {@link #keyGenerator()} has been set.
+	 * 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.
+	 * Spring Expression Language (SpEL) expression used to veto the cache put operation.
-	 * <p>Unlike {@link #condition()}, this expression is evaluated after the method
+	 * <p>Unlike {@link #condition}, this expression is evaluated after the method
-	 * has been called and can therefore refer to the {@code result}. Default is "",
+	 * has been called and can therefore refer to the {@code result}.
-	 * meaning that caching is never vetoed.
+	 * <p>Default is {@code ""}, meaning that caching is never vetoed.
 	 * @since 3.2
 	 */
 	String unless() default "";
+
 }

spring-context/src/main/java/org/springframework/cache/annotation/Cacheable.java

@@ -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,
+ * <p>Each time an advised method is invoked, caching behavior will be applied,
- * checking whether the method has been already executed for the given arguments. A
+ * 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
+ * sensible default simply uses the method parameters to compute the key, but a SpEL
- * expression can be provided ({@link #key()}) or a custom
+ * 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.
+	 * Names of the caches in which method invocation results are stored.
-	 * <p>May be used to determine the target cache (or caches), matching the
+	 * <p>Names may be used to determine the target cache (or caches), matching
-	 * qualifier value (or the bean name(s)) of (a) specific bean definition.
+	 * the qualifier value or bean name of a specific bean definition.
 	 */
 	String[] value() default {};
 
 	/**
-	 * Spring Expression Language (SpEL) attribute for computing the key dynamically.
+	 * Spring Expression Language (SpEL) expression for computing the key dynamically.
-	 * <p>Default is "", meaning all method parameters are considered as a key, unless
+	 * <p>Default is {@code ""}, meaning all method parameters are considered as a key,
-	 * a custom {@link #keyGenerator()} has been set.
+	 * 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.
+	 * Spring Expression Language (SpEL) expression used to veto method caching.
-	 * <p>Unlike {@link #condition()}, this expression is evaluated after the method
+	 * <p>Unlike {@link #condition}, this expression is evaluated after the method
-	 * has been called and can therefore refer to the {@code result}. Default is "",
+	 * has been called and can therefore refer to the {@code result}.
-	 * meaning that caching is never vetoed.
+	 * <p>Default is {@code ""}, meaning that caching is never vetoed.
 	 * @since 3.2
 	 */
 	String unless() default "";
+
 }