Polish cache Javadoc

org.springframework.aspects/src/main/java/org/springframework/cache/aspectj/AbstractCacheAspect.aj

@@ -16,28 +16,23 @@
 
 package org.springframework.cache.aspectj;
 
-import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
-import java.util.concurrent.Callable;
 
 import org.aspectj.lang.annotation.SuppressAjWarnings;
 import org.aspectj.lang.reflect.MethodSignature;
 import org.springframework.cache.interceptor.CacheAspectSupport;
 import org.springframework.cache.interceptor.CacheOperationSource;
-import org.springframework.cache.interceptor.CacheAspectSupport.Invoker;
 
 /**
- * Abstract superaspect for AspectJ cache aspects. Concrete
+ * Abstract superaspect for AspectJ cache aspects. Concrete subaspects will implement the
- * subaspects will implement the <code>cacheMethodExecution()</code>
+ * {@link #cacheMethodExecution} pointcut using a strategy such as Java 5 annotations.
- * pointcut using a strategy such as Java 5 annotations.
  *
- * <p>Suitable for use inside or outside the Spring IoC container.
+ * <p>Suitable for use inside or outside the Spring IoC container. Set the
- * Set the "cacheManager" property appropriately, allowing
+ * {@link #setCacheManager cacheManager} property appropriately, allowing use of any cache
- * use of any cache implementation supported by Spring.
+ * implementation supported by Spring.
  *
- * <p><b>NB:</b> If a method implements an interface that is itself
+ * <p><b>NB:</b> If a method implements an interface that is itself cache annotated, the
- * cache annotated, the relevant Spring cache definition
+ * relevant Spring cache definition will <i>not</i> be resolved.
- * will <i>not</i> be resolved.
  *
  * @author Costin Leau
  * @since 3.1
@@ -49,8 +44,8 @@ public abstract aspect AbstractCacheAspect extends CacheAspectSupport {
 
 	/**
 	 * Construct object using the given caching metadata retrieval strategy.
-	 * @param cos {@link CacheOperationSource} implementation, retrieving Spring
+	 * @param cos {@link CacheOperationSource} implementation, retrieving Spring cache
-	 * cache metadata for each joinpoint.
+	 * metadata for each joinpoint.
 	 */
 	protected AbstractCacheAspect(CacheOperationSource... cos) {
 		setCacheOperationSources(cos);
@@ -71,9 +66,7 @@ public abstract aspect AbstractCacheAspect extends CacheAspectSupport {
 	}
 
 	/**
-	 * Concrete subaspects must implement this pointcut, to identify
+	 * Concrete subaspects must implement this pointcut, to identify cached methods.
-	 * cached methods. For each selected joinpoint, {@link CacheOperationDefinition}
-	 * will be retrieved using Spring's {@link CacheOperationSource} interface.
 	 */
 	protected abstract pointcut cacheMethodExecution(Object cachedObject);
 

org.springframework.aspects/src/main/java/org/springframework/cache/aspectj/AnnotationCacheAspect.aj

@@ -21,21 +21,20 @@ import org.springframework.cache.annotation.CacheEvict;
 import org.springframework.cache.annotation.Cacheable;
 
 /**
- * Concrete AspectJ cache aspect using Spring's {@link Cacheable} annotation.
+ * Concrete AspectJ cache aspect using Spring's @{@link Cacheable} annotation.
  *
- * <p>When using this aspect, you <i>must</i> annotate the implementation class
+ * <p>When using this aspect, you <i>must</i> annotate the implementation class (and/or
- * (and/or methods within that class), <i>not</i> the interface (if any) that
+ * methods within that class), <i>not</i> the interface (if any) that the class
- * the class implements. AspectJ follows Java's rule that annotations on 
+ * implements. AspectJ follows Java's rule that annotations on interfaces are <i>not</i>
- * interfaces are <i>not</i> inherited.
+ * inherited.
  *
- * <p>A {@link Cacheable} annotation on a class specifies the default caching
+ * <p>A {@code @Cacheable} annotation on a class specifies the default caching semantics
- * semantics for the execution of any <b>public</b> operation in the class.
+ * for the execution of any <b>public</b> operation in the class.
  *
- * <p>A {@link Cacheable} annotation on a method within the class overrides the
+ * <p>A {@code @Cacheable} annotation on a method within the class overrides the default
- * default caching semantics given by the class annotation (if present). 
+ * caching semantics given by the class annotation (if present). Any method may be
- * Any method may be annotated (regardless of visibility).
+ * annotated (regardless of visibility). Annotating non-public methods directly is the
- * Annotating non-public methods directly is the only way
+ * only way to get caching demarcation for the execution of such operations.
- * to get caching demarcation for the execution of such operations.
  *
  * @author Costin Leau
  * @since 3.1
@@ -47,41 +46,40 @@ public aspect AnnotationCacheAspect extends AbstractCacheAspect {
 	}
 
 	/**
-	 * Matches the execution of any public method in a type with the
+	 * Matches the execution of any public method in a type with the @{@link Cacheable}
-	 * {@link Cacheable} annotation, or any subtype of a type with the
+	 * annotation, or any subtype of a type with the {@code @Cacheable} annotation.
-	 * {@link Cacheable} annotation.
 	 */
 	private pointcut executionOfAnyPublicMethodInAtCacheableType() :
 		execution(public * ((@Cacheable *)+).*(..)) && @this(Cacheable);
 
 	/**
-	 * Matches the execution of any public method in a type with the
+	 * Matches the execution of any public method in a type with the @{@link CacheEvict}
-	 * {@link CacheEvict} annotation, or any subtype of a type with the
+	 * annotation, or any subtype of a type with the {@code CacheEvict} annotation.
-	 * {@link CacheEvict} annotation.
 	 */
 	private pointcut executionOfAnyPublicMethodInAtCacheEvictType() :
 		execution(public * ((@CacheEvict *)+).*(..)) && @this(CacheEvict);
 
 	/**
-	 * Matches the execution of any method with the 
+	 * Matches the execution of any method with the @{@link Cacheable} annotation.
-	 * Cacheable annotation.
 	 */
 	private pointcut executionOfCacheableMethod() :
 		execution(* *(..)) && @annotation(Cacheable);
 
 	/**
-	 * Matches the execution of any method with the {@link CacheEvict} annotation.
+	 * Matches the execution of any method with the @{@link CacheEvict} annotation.
 	 */
 	private pointcut executionOfCacheEvictMethod() :
 		execution(* *(..)) && @annotation(CacheEvict);
 
 	/**
-	 * Definition of pointcut from super aspect - matched join points
+	 * Definition of pointcut from super aspect - matched join points will have Spring
-	 * will have Spring cache management applied.
+	 * cache management applied.
 	 */
 	protected pointcut cacheMethodExecution(Object cachedObject) :
-		(executionOfAnyPublicMethodInAtCacheableType() || executionOfAnyPublicMethodInAtCacheEvictType()
+		(executionOfAnyPublicMethodInAtCacheableType()
-		 || executionOfCacheableMethod() || executionOfCacheEvictMethod())
+				|| executionOfAnyPublicMethodInAtCacheEvictType()
-		 && this(cachedObject);
+				|| executionOfCacheableMethod()
+				|| executionOfCacheEvictMethod())
+			&& this(cachedObject);
 
 }