Polish Javadoc for AopUtils, Advised, & related classes

spring-aop/src/main/java/org/springframework/aop/TargetClassAware.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 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.
@@ -20,7 +20,7 @@ package org.springframework.aop;
  * Minimal interface for exposing the target class behind a proxy.
  *
  * <p>Implemented by AOP proxy objects and proxy factories
- * (via {@link org.springframework.aop.framework.Advised}}
+ * (via {@link org.springframework.aop.framework.Advised})
  * as well as by {@link TargetSource TargetSources}.
  *
  * @author Juergen Hoeller

spring-aop/src/main/java/org/springframework/aop/framework/Advised.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 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.
@@ -25,7 +25,7 @@ import org.springframework.aop.TargetSource;
 /**
  * Interface to be implemented by classes that hold the configuration
  * of a factory of AOP proxies. This configuration includes the
- * Interceptors and other advice, and Advisors, and the proxied interfaces.
+ * Interceptors and other advice, Advisors, and the proxied interfaces.
  *
  * <p>Any AOP proxy obtained from Spring can be cast to this interface to
  * allow manipulation of its AOP advice.
@@ -49,8 +49,8 @@ public interface Advised extends TargetClassAware {
 	boolean isProxyTargetClass();
 
 	/**
-	 * Return the interfaces proxied by the AOP proxy. Will not
-	 * include the target class, which may also be proxied.
+	 * Return the interfaces proxied by the AOP proxy.
+	 * <p>Will not include the target class, which may also be proxied.
 	 */
 	Class<?>[] getProxiedInterfaces();
 
@@ -60,33 +60,34 @@ public interface Advised extends TargetClassAware {
 	 */
 	boolean isInterfaceProxied(Class<?> intf);
 
-
 	/**
-	 * Change the TargetSource used by this Advised object.
-	 * Only works if the configuration isn't frozen.
+	 * Change the {@code TargetSource} used by this {@code Advised} object.
+	 * <p>Only works if the configuration isn't {@linkplain #isFrozen frozen}.
 	 * @param targetSource new TargetSource to use
 	 */
 	void setTargetSource(TargetSource targetSource);
 
 	/**
-	 * Return the TargetSource used by this Advised object.
+	 * Return the {@code TargetSource} used by this {@code Advised} object.
 	 */
 	TargetSource getTargetSource();
 
 	/**
 	 * Set whether the proxy should be exposed by the AOP framework as a
-	 * ThreadLocal for retrieval via the AopContext class. This is useful
-	 * if an advised object needs to call another advised method on itself.
-	 * (If it uses {@code this}, the invocation will not be advised).
-	 * <p>Default is "false", for optimal performance.
+	 * {@link ThreadLocal} for retrieval via the {@link AopContext} class.
+	 * <p>It can be necessary to expose the proxy if an advised object needs
+	 * to invoke a method on itself with advice applied. Otherwise, if an
+	 * advised object invokes a method on {@code this}, no advice will be applied.
+	 * <p>Default is {@code false}, for optimal performance.
 	 */
 	void setExposeProxy(boolean exposeProxy);
 
 	/**
-	 * Return whether the factory should expose the proxy as a ThreadLocal.
-	 * This can be necessary if a target object needs to invoke a method on itself
-	 * benefitting from advice. (If it invokes a method on {@code this} no advice
-	 * will apply.) Getting the proxy is analogous to an EJB calling getEJBObject().
+	 * Return whether the factory should expose the proxy as a {@link ThreadLocal}.
+	 * <p>It can be necessary to expose the proxy if an advised object needs
+	 * to invoke a method on itself with advice applied. Otherwise, if an
+	 * advised object invokes a method on {@code this}, no advice will be applied.
+	 * <p>Getting the proxy is analogous to an EJB calling {@code getEJBObject()}.
 	 * @see AopContext
 	 */
 	boolean isExposeProxy();
@@ -107,7 +108,6 @@ public interface Advised extends TargetClassAware {
 	 */
 	boolean isPreFiltered();
 
-
 	/**
 	 * Return the advisors applying to this proxy.
 	 * @return a list of Advisors applying to this proxy (never {@code null})
@@ -170,7 +170,6 @@ public interface Advised extends TargetClassAware {
 	 */
 	boolean replaceAdvisor(Advisor a, Advisor b) throws AopConfigException;
 
-
 	/**
 	 * Add the given AOP Alliance advice to the tail of the advice (interceptor) chain.
 	 * <p>This will be wrapped in a DefaultPointcutAdvisor with a pointcut that always
@@ -217,7 +216,6 @@ public interface Advised extends TargetClassAware {
 	 */
 	int indexOf(Advice advice);
 
-
 	/**
 	 * As {@code toString()} will normally be delegated to the target,
 	 * this returns the equivalent for the AOP proxy.

spring-aop/src/main/java/org/springframework/aop/framework/AopProxyUtils.java

@@ -41,11 +41,11 @@ public abstract class AopProxyUtils {
 
 	/**
 	 * Determine the ultimate target class of the given bean instance, traversing
-	 * not only a top-level proxy but any number of nested proxies as well -
+	 * not only a top-level proxy but any number of nested proxies as well —
 	 * as long as possible without side effects, that is, just for singleton targets.
 	 * @param candidate the instance to check (might be an AOP proxy)
-	 * @return the target class (or the plain class of the given object as fallback;
-	 * never {@code null})
+	 * @return the ultimate target class (or the plain class of the given
+	 * object as fallback; never {@code null})
 	 * @see org.springframework.aop.TargetClassAware#getTargetClass()
 	 * @see Advised#getTargetSource()
 	 */

spring-aop/src/main/java/org/springframework/aop/support/AopUtils.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.
@@ -40,7 +40,8 @@ import org.springframework.util.ReflectionUtils;
 
 /**
  * Utility methods for AOP support code.
- * Mainly for internal use within Spring's AOP support.
+ *
+ * <p>Mainly for internal use within Spring's AOP support.
  *
  * <p>See {@link org.springframework.aop.framework.AopProxyUtils} for a
  * collection of framework-specific AOP utility methods which depend
@@ -55,6 +56,8 @@ public abstract class AopUtils {
 
 	/**
 	 * Check whether the given object is a JDK dynamic proxy or a CGLIB proxy.
+	 * <p>This method additionally checks if the given object is an instance
+	 * of {@link SpringProxy}.
 	 * @param object the object to check
 	 * @see #isJdkDynamicProxy
 	 * @see #isCglibProxy
@@ -66,6 +69,9 @@ public abstract class AopUtils {
 
 	/**
 	 * Check whether the given object is a JDK dynamic proxy.
+	 * <p>This method goes beyond the implementation of
+	 * {@link Proxy#isProxyClass(Class)} by additionally checking if the
+	 * given object is an instance of {@link SpringProxy}.
 	 * @param object the object to check
 	 * @see java.lang.reflect.Proxy#isProxyClass
 	 */
@@ -74,9 +80,10 @@ public abstract class AopUtils {
 	}
 
 	/**
-	 * Check whether the given object is a CGLIB proxy. Goes beyond the implementation
-	 * in {@link ClassUtils#isCglibProxy(Object)} by checking also to see if the given
-	 * object is an instance of {@link SpringProxy}.
+	 * Check whether the given object is a CGLIB proxy.
+	 * <p>This method goes beyond the implementation of
+	 * {@link ClassUtils#isCglibProxy(Object)} by additionally checking if
+	 * the given object is an instance of {@link SpringProxy}.
 	 * @param object the object to check
 	 * @see ClassUtils#isCglibProxy(Object)
 	 */
@@ -86,7 +93,7 @@ public abstract class AopUtils {
 
 	/**
 	 * Determine the target class of the given bean instance which might be an AOP proxy.
-	 * <p>Returns the target class for an AOP proxy and the plain class else.
+	 * <p>Returns the target class for an AOP proxy or the plain class otherwise.
 	 * @param candidate the instance to check (might be an AOP proxy)
 	 * @return the target class (or the plain class of the given object as fallback;
 	 * never {@code null})
@@ -160,7 +167,6 @@ public abstract class AopUtils {
 		return BridgeMethodResolver.findBridgedMethod(resolvedMethod);
 	}
 
-
 	/**
 	 * Can the given pointcut apply at all on the given class?
 	 * <p>This is an important test as it can be used to optimize
@@ -278,7 +284,6 @@ public abstract class AopUtils {
 		return eligibleAdvisors;
 	}
 
-
 	/**
 	 * Invoke the given target via reflection, as part of an AOP method invocation.
 	 * @param target the target object