Merged HEAD (5.1) to 5.1.N (5.1.1)

119697 bhorje: ACE-4744 javadoc and cleanup


git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/BRANCHES/DEV/5.1.N/root@120076 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261

source/java/org/alfresco/traitextender/RouteExtensions.java

@@ -16,6 +16,7 @@
  * You should have received a copy of the GNU Lesser General Public License
  * along with Alfresco. If not, see http://www.gnu.org/licenses/.
  */
+
 package org.alfresco.traitextender;
 
 import java.lang.reflect.Method;
@@ -28,13 +29,29 @@ import org.aspectj.lang.annotation.Around;
 import org.aspectj.lang.annotation.Aspect;
 import org.aspectj.lang.reflect.MethodSignature;
 
+/**
+ * An method override extension routing aspect.<br>
+ * Overrides calls to methods marked by an {@link Extend} annotation with calls
+ * to methods having the same signature in extensions registered for the
+ * {@link ExtensionPoint} referred by the {@link Extend} method annotation.<br>
+ * Overriding methods can call the overridden method using its correspondent
+ * {@link Trait} representation (i.e. a method having the same signature).<br>
+ * If no extension is defined the call proceeds with the original method.<br>
+ * The aspect uses the {@link AJExtender} static utility to for extension
+ * invocation and for maintaining thread-local extension-bypass contexts as not all
+ * calls must be overridden and calls from within the extension must be aware of
+ * this context (see {@link AJProxyTrait}).
+ *
+ * @author Bogdan Horje
+ */
 @Aspect
 public class RouteExtensions
 {
     private static Log logger = LogFactory.getLog(RouteExtensions.class);
-    
+
     @Around("execution(@org.alfresco.traitextender.Extend * *(..)) && (@annotation(extendAnnotation))")
-    public Object intercept(ProceedingJoinPoint pjp, Extend extendAnnotation) throws Throwable {
+    public Object intercept(ProceedingJoinPoint pjp, Extend extendAnnotation) throws Throwable
+    {
         boolean ajPointsEnabled = AJExtender.areAJPointsEnabled();
         try
         {
@@ -57,7 +74,7 @@ public class RouteExtensions
                                                                        point);
                 if (extension != null)
                 {
-                    
+
                     return AJExtender.extendAroundAdvice(pjp,
                                                          extensible,
                                                          extendAnnotation,