[waffle-scm] [546] trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept: javadoc: added javadoc documentation for classes in action/intercept and action/annotation

Fri, 11 Jan 2008 07:20:17 -0800

Title: [waffle-scm] [546] trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept: javadoc: added javadoc documentation for classes in action/intercept and action/annotation

Diff

Modified: trunk/waffle-core/src/main/java/org/codehaus/waffle/action/annotation/ActionMethod.java (545 => 546)

--- trunk/waffle-core/src/main/java/org/codehaus/waffle/action/annotation/ActionMethod.java	2008-01-09 13:53:02 UTC (rev 545)
+++ trunk/waffle-core/src/main/java/org/codehaus/waffle/action/annotation/ActionMethod.java	2008-01-11 15:20:10 UTC (rev 546)
@@ -26,6 +26,13 @@
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ActionMethod {
+
+    /**
+     * Used to define the parameter names that should be used to resolve an action methods
+     * arguments (order is important).
+     *
+     * @return the parameter names to resolve with
+     */
     String[] parameters() default {};
 
     /**

Modified: trunk/waffle-core/src/main/java/org/codehaus/waffle/action/annotation/PRG.java (545 => 546)

--- trunk/waffle-core/src/main/java/org/codehaus/waffle/action/annotation/PRG.java	2008-01-09 13:53:02 UTC (rev 545)
+++ trunk/waffle-core/src/main/java/org/codehaus/waffle/action/annotation/PRG.java	2008-01-11 15:20:10 UTC (rev 546)
@@ -16,8 +16,8 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation to control the use of the PRG (Post/Redirect/Get) paradigm. 
- * See http://en.wikipedia.org/wiki/Post/Redirect/Get
+ * <p>Annotation to control the use of the PRG (Post/Redirect/Get) paradigm.
+ * See <a href=""
  * 
  * @author Mauro Talevi
  * @author Michael Ward

Modified: trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/DefaultInterceptorChain.java (545 => 546)

--- trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/DefaultInterceptorChain.java	2008-01-09 13:53:02 UTC (rev 545)
+++ trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/DefaultInterceptorChain.java	2008-01-11 15:20:10 UTC (rev 546)
@@ -10,14 +10,20 @@
  *****************************************************************************/
 package org.codehaus.waffle.action.intercept;
 
+import org.codehaus.waffle.controller.ControllerDefinition;
+import org.codehaus.waffle.monitor.ActionMonitor;
+
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 import java.util.Iterator;
 import java.util.List;
 
-import org.codehaus.waffle.controller.ControllerDefinition;
-import org.codehaus.waffle.monitor.ActionMonitor;
-
+/**
+ * <p>This is Waffle's default implementation of the [EMAIL PROTECTED] org.codehaus.waffle.action.intercept.InterceptorChain}
+ * which iterates over each [EMAIL PROTECTED] org.codehaus.waffle.action.intercept.MethodInterceptor} registered with Waffle.
+ * Each method interceptor will have an opportunity to intercept the ActionMethod o be invoked.
+ * </p>
+ */
 public class DefaultInterceptorChain implements InterceptorChain {
     private final Iterator<MethodInterceptor> iterator;
     private final ActionMonitor actionMonitor;
@@ -28,6 +34,9 @@
         this.actionMonitor = actionMonitor;
     }
 
+    /**
+     * [EMAIL PROTECTED]
+     */
     public Object proceed(ControllerDefinition controllerDefinition,
                           Method method,
                           Object... arguments) throws IllegalAccessException, InvocationTargetException {

Modified: trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/InterceptorChain.java (545 => 546)

--- trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/InterceptorChain.java	2008-01-09 13:53:02 UTC (rev 545)
+++ trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/InterceptorChain.java	2008-01-11 15:20:10 UTC (rev 546)
@@ -15,8 +15,21 @@
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 
+/**
+ * <p>Manages the collection of MethodInterceptors registered for use with Application</p>
+ */
 public interface InterceptorChain {
 
+    /**
+     * Continues on to the next MethodInterceptor or invokes the Controller's action method.
+     *
+     * @param controllerDefinition the controller definition instance which owns the action method being invoked
+     * @param method the actual action method to be invoked
+     * @param args are the argument values to satisfy the action method invocation
+     * @return the result from the action method's invocation, or result from this or another MethodInterceptor
+     * @throws IllegalAccessException
+     * @throws InvocationTargetException
+     */
     Object proceed(ControllerDefinition controllerDefinition,
                    Method method,
                    Object ... args) throws IllegalAccessException, InvocationTargetException ;

Modified: trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/MethodInterceptor.java (545 => 546)

--- trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/MethodInterceptor.java	2008-01-09 13:53:02 UTC (rev 545)
+++ trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/MethodInterceptor.java	2008-01-11 15:20:10 UTC (rev 546)
@@ -15,10 +15,33 @@
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 
+/**
+ * <p>A MethodInterceptor is a simple interface that allows you to intercept ActionMethods before and after
+ * they have been invoked. This before and after interception provides AOP type of functionality.</p>
+ */
 public interface MethodInterceptor {
 
+    /**
+     * Determines if the implementation should intercept the call to the Action Method.
+     *
+     * @param method is the action method that is to be invoked (or intercepted)
+     * @return true if this should intercept the invocation
+     */
     boolean accept(Method method);
 
+    /**
+     * This method allows an ActionMethod call to be intercepted.  To continue onto the next MethodInterceptor,
+     * or ActionMethod, the implementation should call
+     * [EMAIL PROTECTED] InterceptorChain#proceed(ControllerDefinition, Method, Object[])}.
+     * 
+     * @param controllerDefinition the controller definition instance which owns the action method being invoked
+     * @param method the actual action method to be invoked
+     * @param chain is the InterceptorChain managing the method interceptors
+     * @param arguments are the argument values to satisfy the action method invocation
+     * @return the result from the action method's invocation, or result from this or another MethodInterceptor
+     * @throws IllegalAccessException
+     * @throws InvocationTargetException
+     */
     Object intercept(ControllerDefinition controllerDefinition,
                      Method method,
                      InterceptorChain chain,

Modified: trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/MethodInterceptorComparator.java (545 => 546)

--- trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/MethodInterceptorComparator.java	2008-01-09 13:53:02 UTC (rev 545)
+++ trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/MethodInterceptorComparator.java	2008-01-11 15:20:10 UTC (rev 546)
@@ -13,9 +13,24 @@
 import java.util.Comparator;
 import java.io.Serializable;
 
+/**
+ * <p>Comparator implementation that is used by Waffle to ensure that MethodInterceptors are executed in
+ * the correct order.</p>
+ */
 @SuppressWarnings("serial")
 public class MethodInterceptorComparator implements Comparator<MethodInterceptor>, Serializable {
 
+    /**
+     * Will compare both MethodInterceptors being compared to determine the correct evaluation order.
+     *
+     * @see org.codehaus.waffle.action.intercept.Sortable
+     *
+     * @param first the first MethodInterceptor to be compared
+     * @param second the second MethodInterceptor to be compared
+     * @return a negative integer, zero, or a positive integer as the
+     *         first MethodInterceptor is less than, equal to, or greater than the
+     *         second. 
+     */
     public int compare(MethodInterceptor first, MethodInterceptor second) {
         if (first instanceof Sortable && second instanceof Sortable) {
             Sortable  first;

Modified: trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/SecurityMethodInterceptor.java (545 => 546)

--- trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/SecurityMethodInterceptor.java	2008-01-09 13:53:02 UTC (rev 545)
+++ trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/SecurityMethodInterceptor.java	2008-01-11 15:20:10 UTC (rev 546)
@@ -10,23 +10,34 @@
  *****************************************************************************/
 package org.codehaus.waffle.action.intercept;
 
-import java.lang.reflect.InvocationTargetException;
-import java.lang.reflect.Method;
-
 import org.codehaus.waffle.action.ActionMethodInvocationException;
 import org.codehaus.waffle.action.annotation.ActionMethod;
 import org.codehaus.waffle.controller.ControllerDefinition;
 
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+
 /**
- * This interceptor ensure that only annotated methods are invokable as <i>Actions</i>.  
+ * <p>This interceptor ensure that only [EMAIL PROTECTED] ActionMethod} annotated methods are invokable as [EMAIL PROTECTED] Actions}.
  * Usage of this will help protect your application against malicious attacks.
  */
 public class SecurityMethodInterceptor implements MethodInterceptor {
 
+    /**
+     * Will always return true (intercepts ALL action methods)
+     *
+     * [EMAIL PROTECTED]
+     */
     public boolean accept(Method actionMethod) {
         return true; // intercept all!!!!
     }
 
+    /**
+     * Ensure that the action method tobe invoked is annotated with the [EMAIL PROTECTED] ActionMethod} annotation.  If no annotation
+     * is present a [EMAIL PROTECTED] ActionMethodInvocationException} will be thrown.
+     *
+     * [EMAIL PROTECTED]
+     */
     public Object intercept(ControllerDefinition controllerDefinition,
                             Method method,
                             InterceptorChain chain,

Modified: trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/Sortable.java (545 => 546)

--- trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/Sortable.java	2008-01-09 13:53:02 UTC (rev 545)
+++ trunk/waffle-core/src/main/java/org/codehaus/waffle/action/intercept/Sortable.java	2008-01-11 15:20:10 UTC (rev 546)
@@ -10,7 +10,15 @@
  *****************************************************************************/
 package org.codehaus.waffle.action.intercept;
 
+/**
+ * <p>Identifies a [EMAIL PROTECTED] MethodInterceptor} so that it will be evaluated in the correct order</p>
+ */
 public interface Sortable {
 
+    /**
+     * Defines the order the implementing MethodInterceptor should be evaluated (in comparison to other MethodInterceptors).
+     *
+     * @return the value representing its place in line
+     */
     Integer getIndex();
 }

To unsubscribe from this list please visit:

http://xircles.codehaus.org/manage_email

Reply via email to