Rename @CacheDefinitions => @Caching

Also eliminate all 'cache definition' language in favor of
'cache operation' in comments, method and parameter names (most
classes had already been refactored to this effect).

org.springframework.context/src/main/java/org/springframework/cache/annotation/AnnotationCacheOperationSource.java

@@ -30,13 +30,13 @@ import org.springframework.cache.interceptor.CacheOperation;
 import org.springframework.util.Assert;
 
 /**
+ * Implementation of the {@link org.springframework.cache.interceptor.CacheOperationSource
+ * CacheOperationSource} interface for working with caching metadata in annotation format.
  *
- * Implementation of the {@link org.springframework.cache.interceptor.CacheOperationSource}
+ * <p>This class reads Spring's {@link Cacheable}, {@link CachePut} and {@link CacheEvict}
- * interface for working with caching metadata in JDK 1.5+ annotation format.
+ * annotations and exposes corresponding caching operation definition to Spring's cache
- *
+ * infrastructure. This class may also serve as base class for a custom
- * <p>This class reads Spring's JDK 1.5+ {@link Cacheable}, {@link CachePut} and {@link CacheEvict} 
+ * {@code CacheOperationSource}.
- * annotations and exposes corresponding caching operation definition to Spring's cache infrastructure.
- * This class may also serve as base class for a custom CacheOperationSource.
  *
  * @author Costin Leau
  * @since 3.1
@@ -52,15 +52,15 @@ public class AnnotationCacheOperationSource extends AbstractFallbackCacheOperati
 
 	/**
 	 * Create a default AnnotationCacheOperationSource, supporting public methods
-	 * that carry the <code>Cacheable</code> and <code>CacheEvict</code> annotations.
+	 * that carry the {@code Cacheable} and {@code CacheEvict} annotations.
 	 */
 	public AnnotationCacheOperationSource() {
 		this(true);
 	}
 
 	/**
-	 * Create a default AnnotationCacheOperationSource, supporting public methods
+	 * Create a default {@code AnnotationCacheOperationSource}, supporting public methods
-	 * that carry the <code>Cacheable</code> and <code>CacheEvict</code> annotations.
+	 * that carry the {@code Cacheable} and {@code CacheEvict} annotations.
 	 * @param publicMethodsOnly whether to support only annotated public methods
 	 * typically for use with proxy-based AOP), or protected/private methods as well
 	 * (typically used with AspectJ class weaving)
@@ -95,15 +95,14 @@ public class AnnotationCacheOperationSource extends AbstractFallbackCacheOperati
 	}
 
 	/**
-	 * Determine the cache operation definition for the given method or class.
+	 * Determine the cache operation(s) for the given method or class.
 	 * <p>This implementation delegates to configured
-	 * {@link CacheAnnotationParser CacheAnnotationParsers}
+	 * {@link CacheAnnotationParser}s for parsing known annotations into
-	 * for parsing known annotations into Spring's metadata attribute class.
+	 * Spring's metadata attribute class.
-	 * Returns <code>null</code> if it's not cacheable.
+	 * <p>Can be overridden to support custom annotations that carry
-	 * <p>Can be overridden to support custom annotations that carry caching metadata.
+	 * caching metadata.
 	 * @param ae the annotated method or class
-	 * @return CacheOperation the configured caching operation,
+	 * @return the configured caching operations, or {@code null} if none found
-	 * or <code>null</code> if none was found
 	 */
 	protected Collection<CacheOperation> determineCacheOperations(AnnotatedElement ae) {
 		Collection<CacheOperation> ops = null;

org.springframework.context/src/main/java/org/springframework/cache/annotation/CacheAnnotationParser.java

@@ -23,7 +23,7 @@ import org.springframework.cache.interceptor.CacheOperation;
 
 /**
  * Strategy interface for parsing known caching annotation types.
- * {@link AnnotationCacheDefinitionSource} delegates to such
+ * {@link AnnotationCacheOperationSource} delegates to such
  * parsers for supporting specific annotation types such as Spring's own
  * {@link Cacheable}, {@link CachePut} or {@link CacheEvict}.
  *

org.springframework.context/src/main/java/org/springframework/cache/annotation/Caching.java

@@ -34,7 +34,7 @@ import java.lang.annotation.Target;
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
 @Documented
-public @interface CacheDefinitions {
+public @interface Caching {
 
 	Cacheable[] cacheable() default {};
 

org.springframework.context/src/main/java/org/springframework/cache/annotation/SpringCacheAnnotationParser.java

@@ -29,11 +29,12 @@ import org.springframework.core.annotation.AnnotationUtils;
 import org.springframework.util.ObjectUtils;
 
 /**
- * Strategy implementation for parsing Spring's {@link Cacheable},
+ * Strategy implementation for parsing Spring's {@link Caching}, {@link Cacheable},
  * {@link CacheEvict} and {@link CachePut} annotations.
  *
  * @author Costin Leau
  * @author Juergen Hoeller
+ * @author Chris Beams
  * @since 3.1
  */
 @SuppressWarnings("serial")
@@ -57,10 +58,10 @@ public class SpringCacheAnnotationParser implements CacheAnnotationParser, Seria
 			ops = lazyInit(ops);
 			ops.add(parseUpdateAnnotation(ae, update));
 		}
-		CacheDefinitions definition = AnnotationUtils.getAnnotation(ae, CacheDefinitions.class);
+		Caching caching = AnnotationUtils.getAnnotation(ae, Caching.class);
-		if (definition != null) {
+		if (caching != null) {
 			ops = lazyInit(ops);
-			ops.addAll(parseDefinitionAnnotation(ae, definition));
+			ops.addAll(parseCachingAnnotation(ae, caching));
 		}
 		return ops;
 	}
@@ -69,52 +70,52 @@ public class SpringCacheAnnotationParser implements CacheAnnotationParser, Seria
 		return (ops != null ? ops : new ArrayList<CacheOperation>(2));
 	}
 
-	CacheableOperation parseCacheableAnnotation(AnnotatedElement ae, Cacheable ann) {
+	CacheableOperation parseCacheableAnnotation(AnnotatedElement ae, Cacheable caching) {
 		CacheableOperation cuo = new CacheableOperation();
-		cuo.setCacheNames(ann.value());
+		cuo.setCacheNames(caching.value());
-		cuo.setCondition(ann.condition());
+		cuo.setCondition(caching.condition());
-		cuo.setKey(ann.key());
+		cuo.setKey(caching.key());
 		cuo.setName(ae.toString());
 		return cuo;
 	}
 
-	CacheEvictOperation parseEvictAnnotation(AnnotatedElement ae, CacheEvict ann) {
+	CacheEvictOperation parseEvictAnnotation(AnnotatedElement ae, CacheEvict caching) {
 		CacheEvictOperation ceo = new CacheEvictOperation();
-		ceo.setCacheNames(ann.value());
+		ceo.setCacheNames(caching.value());
-		ceo.setCondition(ann.condition());
+		ceo.setCondition(caching.condition());
-		ceo.setKey(ann.key());
+		ceo.setKey(caching.key());
-		ceo.setCacheWide(ann.allEntries());
+		ceo.setCacheWide(caching.allEntries());
 		ceo.setName(ae.toString());
 		return ceo;
 	}
 
-	CacheOperation parseUpdateAnnotation(AnnotatedElement ae, CachePut ann) {
+	CacheOperation parseUpdateAnnotation(AnnotatedElement ae, CachePut caching) {
 		CachePutOperation cuo = new CachePutOperation();
-		cuo.setCacheNames(ann.value());
+		cuo.setCacheNames(caching.value());
-		cuo.setCondition(ann.condition());
+		cuo.setCondition(caching.condition());
-		cuo.setKey(ann.key());
+		cuo.setKey(caching.key());
 		cuo.setName(ae.toString());
 		return cuo;
 	}
 
-	Collection<CacheOperation> parseDefinitionAnnotation(AnnotatedElement ae, CacheDefinitions ann) {
+	Collection<CacheOperation> parseCachingAnnotation(AnnotatedElement ae, Caching caching) {
 		Collection<CacheOperation> ops = null;
 
-		Cacheable[] cacheables = ann.cacheable();
+		Cacheable[] cacheables = caching.cacheable();
 		if (!ObjectUtils.isEmpty(cacheables)) {
 			ops = lazyInit(ops);
 			for (Cacheable cacheable : cacheables) {
 				ops.add(parseCacheableAnnotation(ae, cacheable));
 			}
 		}
-		CacheEvict[] evicts = ann.evict();
+		CacheEvict[] evicts = caching.evict();
 		if (!ObjectUtils.isEmpty(evicts)) {
 			ops = lazyInit(ops);
 			for (CacheEvict evict : evicts) {
 				ops.add(parseEvictAnnotation(ae, evict));
 			}
 		}
-		CachePut[] updates = ann.put();
+		CachePut[] updates = caching.put();
 		if (!ObjectUtils.isEmpty(updates)) {
 			ops = lazyInit(ops);
 			for (CachePut update : updates) {

org.springframework.context/src/main/java/org/springframework/cache/interceptor/AbstractFallbackCacheOperationSource.java

@@ -66,7 +66,7 @@ public abstract class AbstractFallbackCacheOperationSource implements CacheOpera
 	protected final Log logger = LogFactory.getLog(getClass());
 
 	/**
-	 * Cache of CacheOperationDefinitions, keyed by DefaultCacheKey (Method + target Class).
+	 * Cache of CacheOperations, keyed by DefaultCacheKey (Method + target Class).
 	 * <p>As this base class is not marked Serializable, the cache will be recreated
 	 * after serialization - provided that the concrete subclass is Serializable.
 	 */
@@ -95,18 +95,18 @@ public abstract class AbstractFallbackCacheOperationSource implements CacheOpera
 		}
 		else {
 			// We need to work it out.
-			Collection<CacheOperation> cacheDefs = computeCacheOperationDefinition(method, targetClass);
+			Collection<CacheOperation> cacheOps = computeCacheOperations(method, targetClass);
 			// Put it in the cache.
-			if (cacheDefs == null) {
+			if (cacheOps == null) {
 				this.attributeCache.put(cacheKey, NULL_CACHING_ATTRIBUTE);
 			}
 			else {
 				if (logger.isDebugEnabled()) {
-					logger.debug("Adding cacheable method '" + method.getName() + "' with attribute: " + cacheDefs);
+					logger.debug("Adding cacheable method '" + method.getName() + "' with attribute: " + cacheOps);
 				}
-				this.attributeCache.put(cacheKey, cacheDefs);
+				this.attributeCache.put(cacheKey, cacheOps);
 			}
-			return cacheDefs;
+			return cacheOps;
 		}
 	}
 
@@ -122,7 +122,7 @@ public abstract class AbstractFallbackCacheOperationSource implements CacheOpera
 		return new DefaultCacheKey(method, targetClass);
 	}
 
-	private Collection<CacheOperation> computeCacheOperationDefinition(Method method, Class<?> targetClass) {
+	private Collection<CacheOperation> computeCacheOperations(Method method, Class<?> targetClass) {
 		// Don't allow no-public methods as required.
 		if (allowPublicMethodsOnly() && !Modifier.isPublic(method.getModifiers())) {
 			return null;

org.springframework.context/src/main/java/org/springframework/cache/interceptor/CacheAspectSupport.java

@@ -48,7 +48,7 @@ import org.springframework.util.StringUtils;
  * <p>Uses the <b>Strategy</b> design pattern. A {@link CacheManager}
  * implementation will perform the actual cache management, and a
  * {@link CacheOperationSource} is used for determining caching
- * operation definitions.
+ * operations.
  *
  * <p>A cache aspect is serializable if its {@code CacheManager} and
  * {@code CacheOperationSource} are serializable.
@@ -93,7 +93,7 @@ public abstract class CacheAspectSupport implements InitializingBean {
 	}
 
 	/**
-	 * Set one or more cache definition sources which are used to find the cache
+	 * Set one or more cache operation sources which are used to find the cache
 	 * attributes. If more than one source is provided, they will be aggregated using a
 	 * {@link CompositeCacheOperationSource}.
 	 * @param cacheOperationSources must not be {@code null}
@@ -133,7 +133,7 @@ public abstract class CacheAspectSupport implements InitializingBean {
 			throw new IllegalStateException("'cacheManager' is required");
 		}
 		if (this.cacheOperationSource == null) {
-			throw new IllegalStateException("Either 'cacheDefinitionSource' or 'cacheDefinitionSources' is required: "
+			throw new IllegalStateException("The 'cacheOperationSources' property is required: "
 					+ "If there are no cacheable methods, then don't use a cache aspect.");
 		}
 
@@ -242,7 +242,7 @@ public abstract class CacheAspectSupport implements InitializingBean {
 						if (evictOp.isCacheWide()) {
 							cache.clear();
 							if (log) {
-								logger.trace("Invalidating entire cache for definition " + evictOp + " on method " + context.method);
+								logger.trace("Invalidating entire cache for operation " + evictOp + " on method " + context.method);
 							}
 						} else {
 							// check key
@@ -250,7 +250,7 @@ public abstract class CacheAspectSupport implements InitializingBean {
 								key = context.generateKey();
 							}
 							if (log) {
-								logger.trace("Invalidating cache key " + key + " for definition " + evictOp + " on method " + context.method);
+								logger.trace("Invalidating cache key " + key + " for operation " + evictOp + " on method " + context.method);
 							}
 							cache.evict(key);
 						}
@@ -258,7 +258,7 @@ public abstract class CacheAspectSupport implements InitializingBean {
 				}
 				else {
 					if (log) {
-						logger.trace("Cache condition failed on method " + context.method + " for definition " + context.operation);
+						logger.trace("Cache condition failed on method " + context.method + " for operation " + context.operation);
 					}
 				}
 			}
@@ -282,11 +282,11 @@ public abstract class CacheAspectSupport implements InitializingBean {
 					Object key = context.generateKey();
 
 					if (log) {
-						logger.trace("Computed cache key " + key + " for definition " + context.operation);
+						logger.trace("Computed cache key " + key + " for operation " + context.operation);
 					}
 					if (key == null) {
 						throw new IllegalArgumentException(
-								"Null key returned for cache definition (maybe you are using named params on classes without debug info?) "
+								"Null key returned for cache operation (maybe you are using named params on classes without debug info?) "
 										+ context.operation);
 					}
 
@@ -313,7 +313,7 @@ public abstract class CacheAspectSupport implements InitializingBean {
 				}
 				else {
 					if (log) {
-						logger.trace("Cache condition failed on method " + context.method + " for definition " + context.operation);
+						logger.trace("Cache condition failed on method " + context.method + " for operation " + context.operation);
 					}
 				}
 			}
@@ -353,11 +353,11 @@ public abstract class CacheAspectSupport implements InitializingBean {
 					Object key = context.generateKey();
 
 					if (log) {
-						logger.trace("Computed cache key " + key + " for definition " + context.operation);
+						logger.trace("Computed cache key " + key + " for operation " + context.operation);
 					}
 					if (key == null) {
 						throw new IllegalArgumentException(
-								"Null key returned for cache definition (maybe you are using named params on classes without debug info?) "
+								"Null key returned for cache operation (maybe you are using named params on classes without debug info?) "
 										+ context.operation);
 					}
 
@@ -366,7 +366,7 @@ public abstract class CacheAspectSupport implements InitializingBean {
 				}
 				else {
 					if (log) {
-						logger.trace("Cache condition failed on method " + context.method + " for definition " + context.operation);
+						logger.trace("Cache condition failed on method " + context.method + " for operation " + context.operation);
 					}
 				}
 			}

org.springframework.context/src/main/java/org/springframework/cache/interceptor/CacheOperation.java

@@ -114,7 +114,7 @@ public abstract class CacheOperation {
 	 */
 	protected StringBuilder getOperationDescription() {
 		StringBuilder result = new StringBuilder();
-		result.append("CacheDefinition[");
+		result.append("CacheOperation[");
 		result.append(this.name);
 		result.append("] caches=");
 		result.append(this.cacheNames);

org.springframework.context/src/main/java/org/springframework/cache/interceptor/CacheOperationSource.java

@@ -30,13 +30,13 @@ import java.util.Collection;
 public interface CacheOperationSource {
 
 	/**
-	 * Return the cache operation definition for this method,
+	 * Return the collection of cache operations for this method,
 	 * or {@code null} if the method contains no "cacheable" annotations.
 	 * @param method the method to introspect
 	 * @param targetClass the target class (may be {@code null},
 	 * in which case the declaring class of the method must be used)
-	 * @return {@link CacheOperation} the matching cache operation,
+	 * @return all cache operations for this method, or {@code null} if
-	 * or {@code null} if none found
+	 * none found
 	 */
 	Collection<CacheOperation> getCacheOperations(Method method, Class<?> targetClass);
 

org.springframework.context/src/main/java/org/springframework/cache/interceptor/CacheOperationSourcePointcut.java

@@ -63,7 +63,7 @@ abstract class CacheOperationSourcePointcut extends StaticMethodMatcherPointcut
 
 
 	/**
-	 * Obtain the underlying CacheOperationDefinitionSource (may be {@code null}).
+	 * Obtain the underlying {@link CacheOperationSource} (may be {@code null}).
 	 * To be implemented by subclasses.
 	 */
 	protected abstract CacheOperationSource getCacheOperationSource();

org.springframework.context/src/main/java/org/springframework/cache/interceptor/CacheProxyFactoryBean.java

@@ -67,13 +67,10 @@ public class CacheProxyFactoryBean extends AbstractSingletonProxyFactoryBean {
 	}
 
 	/**
-	 * Set the caching attribute source which is used to find the cache operation
+	 * Set the sources used to find cache operations.
-	 * definition.
-	 * 
-	 * @param cacheDefinitionSources cache definition sources
 	 */
-	public void setCacheDefinitionSources(CacheOperationSource... cacheDefinitionSources) {
+	public void setCacheOperationSources(CacheOperationSource... cacheOperationSources) {
-		this.cachingInterceptor.setCacheOperationSources(cacheDefinitionSources);
+		this.cachingInterceptor.setCacheOperationSources(cacheOperationSources);
 	}
 
 }

org.springframework.context/src/main/java/org/springframework/cache/interceptor/CompositeCacheOperationSource.java

@@ -25,7 +25,7 @@ import org.springframework.util.Assert;
 
 /**
  * Composite {@link CacheOperationSource} implementation that iterates
- * over a given array of {@link CacheOperationSource} instances.
+ * over a given array of {@code CacheOperationSource} instances.
  *
  * @author Costin Leau
  * @since 3.1
@@ -45,7 +45,8 @@ public class CompositeCacheOperationSource implements CacheOperationSource, Seri
 	}
 
 	/**
-	 * Return the CacheOperationSource instances that this CompositeCachingDefinitionSource combines.
+	 * Return the {@code CacheOperationSource} instances that this
+	 * {@code CompositeCacheOperationSource} combines.
 	 */
 	public final CacheOperationSource[] getCacheOperationSources() {
 		return this.cacheOperationSources;

org.springframework.context/src/main/java/org/springframework/cache/interceptor/NameMatchCacheOperationSource.java

@@ -28,11 +28,12 @@ import org.springframework.util.ObjectUtils;
 import org.springframework.util.PatternMatchUtils;
 
 /**
- * Simple {@link CacheOperationSource} implementation that
+ * Simple {@link CacheOperationSource} implementation that allows attributes to be matched
- * allows attributes to be matched by registered name.
+ * by registered name.
  *
  * @author Costin Leau
  */
+@SuppressWarnings("serial")
 public class NameMatchCacheOperationSource implements CacheOperationSource, Serializable {
 
 	/**

org.springframework.context/src/test/java/org/springframework/cache/config/AnnotatedClassCacheableService.java

@@ -18,7 +18,7 @@ package org.springframework.cache.config;
 
 import java.util.concurrent.atomic.AtomicLong;
 
-import org.springframework.cache.annotation.CacheDefinitions;
+import org.springframework.cache.annotation.Caching;
 import org.springframework.cache.annotation.CacheEvict;
 import org.springframework.cache.annotation.CachePut;
 import org.springframework.cache.annotation.Cacheable;
@@ -92,27 +92,27 @@ public class AnnotatedClassCacheableService implements CacheableService<Object>
 
 	// multi annotations
 
-	@CacheDefinitions(cacheable = { @Cacheable("primary"), @Cacheable("secondary") })
+	@Caching(cacheable = { @Cacheable("primary"), @Cacheable("secondary") })
 	public Object multiCache(Object arg1) {
 		return counter.getAndIncrement();
 	}
 
-	@CacheDefinitions(evict = { @CacheEvict("primary"), @CacheEvict(value = "secondary", key = "#p0") })
+	@Caching(evict = { @CacheEvict("primary"), @CacheEvict(value = "secondary", key = "#p0") })
 	public Object multiEvict(Object arg1) {
 		return counter.getAndIncrement();
 	}
 
-	@CacheDefinitions(cacheable = { @Cacheable(value = "primary", key = "#root.methodName") }, evict = { @CacheEvict("secondary") })
+	@Caching(cacheable = { @Cacheable(value = "primary", key = "#root.methodName") }, evict = { @CacheEvict("secondary") })
 	public Object multiCacheAndEvict(Object arg1) {
 		return counter.getAndIncrement();
 	}
 
-	@CacheDefinitions(cacheable = { @Cacheable(value = "primary", condition = "#p0 == 3") }, evict = { @CacheEvict("secondary") })
+	@Caching(cacheable = { @Cacheable(value = "primary", condition = "#p0 == 3") }, evict = { @CacheEvict("secondary") })
 	public Object multiConditionalCacheAndEvict(Object arg1) {
 		return counter.getAndIncrement();
 	}
 
-	@CacheDefinitions(put = { @CachePut("primary"), @CachePut("secondary") })
+	@Caching(put = { @CachePut("primary"), @CachePut("secondary") })
 	public Object multiUpdate(Object arg1) {
 		return arg1;
 	}

org.springframework.context/src/test/java/org/springframework/cache/config/DefaultCacheableService.java

@@ -18,7 +18,7 @@ package org.springframework.cache.config;
 
 import java.util.concurrent.atomic.AtomicLong;
 
-import org.springframework.cache.annotation.CacheDefinitions;
+import org.springframework.cache.annotation.Caching;
 import org.springframework.cache.annotation.CacheEvict;
 import org.springframework.cache.annotation.CachePut;
 import org.springframework.cache.annotation.Cacheable;
@@ -98,27 +98,27 @@ public class DefaultCacheableService implements CacheableService<Long> {
 
 	// multi annotations
 
-	@CacheDefinitions(cacheable = { @Cacheable("primary"), @Cacheable("secondary") })
+	@Caching(cacheable = { @Cacheable("primary"), @Cacheable("secondary") })
 	public Long multiCache(Object arg1) {
 		return counter.getAndIncrement();
 	}
 
-	@CacheDefinitions(evict = { @CacheEvict("primary"), @CacheEvict(value = "secondary", key = "#p0") })
+	@Caching(evict = { @CacheEvict("primary"), @CacheEvict(value = "secondary", key = "#p0") })
 	public Long multiEvict(Object arg1) {
 		return counter.getAndIncrement();
 	}
 
-	@CacheDefinitions(cacheable = { @Cacheable(value = "primary", key = "#root.methodName") }, evict = { @CacheEvict("secondary") })
+	@Caching(cacheable = { @Cacheable(value = "primary", key = "#root.methodName") }, evict = { @CacheEvict("secondary") })
 	public Long multiCacheAndEvict(Object arg1) {
 		return counter.getAndIncrement();
 	}
 
-	@CacheDefinitions(cacheable = { @Cacheable(value = "primary", condition = "#p0 == 3") }, evict = { @CacheEvict("secondary") })
+	@Caching(cacheable = { @Cacheable(value = "primary", condition = "#p0 == 3") }, evict = { @CacheEvict("secondary") })
 	public Long multiConditionalCacheAndEvict(Object arg1) {
 		return counter.getAndIncrement();
 	}
 
-	@CacheDefinitions(put = { @CachePut("primary"), @CachePut("secondary") })
+	@Caching(put = { @CachePut("primary"), @CachePut("secondary") })
 	public Long multiUpdate(Object arg1) {
 		return Long.valueOf(arg1.toString());
 	}