Commits

Anonymous committed cd8c178

Adding JavaDoc for core XWork classes

git-svn-id: http://svn.opensymphony.com/svn/xwork/trunk@182e221344d-f017-0410-9bd5-d282ab1896d7

Comments (0)

Files changed (5)

src/java/com/opensymphony/xwork/ActionInvocation.java

 
 
 /**
- * ActionInvocation
+ * An ActionInvocation represents the execution state of an Action. It holds the Interceptors and the Action instance.
+ * By repeated re-entrant execution of the invoke() method, initially by the ActionProxy, then by the Interceptors, the
+ * Interceptors are all executed, and then the Action and the Result.
  * @author Jason Carreira
  * Created Jun 9, 2003 11:37:27 AM
+ * @see com.opensymphony.xwork.ActionProxy
  */
 public interface ActionInvocation extends Serializable {
     //~ Methods ////////////////////////////////////////////////////////////////
     */
     Action getAction();
 
+    /**
+     * @return whether this ActionInvocation has executed before. This will be set after the Action and the Result have
+     * executed.
+     */
     boolean isExecuted();
 
     /**
     */
     ActionContext getInvocationContext();
 
+    /**
+     * Get the ActionProxy holding this ActionInvocation
+     * @return
+     */
     ActionProxy getProxy();
 
     /**
     */
     String getResultCode();
 
+    /**
+     * @return the ValueStack associated with this ActionInvocation
+     */
     OgnlValueStack getStack();
 
     /**
-    * Register a com.opensymphony.xwork.interceptor.PreResultListener to be notified after the Action is executed and before the
-    * Result is executed. The ActionInvocation implementation must guarantee that listeners will be called in the order
-    * in which they are registered. Listener registration and execution does not need to be thread-safe.
+    * Register a com.opensymphony.xwork.interceptor.PreResultListener to be notified after the Action is executed and
+    * before the Result is executed. The ActionInvocation implementation must guarantee that listeners will be called in
+    * the order in which they are registered. Listener registration and execution does not need to be thread-safe.
     * @param listener
     */
     void addPreResultListener(PreResultListener listener);
 
     /**
-    * Invokes the next step in processing this ActionInvocation. If there are more
-    * Interceptors, this will call the next one. If Interceptors choose not to short-circuit
-    * ActionInvocation processing and return their own return code, they will call
-    * invoke() to allow the next Interceptor to execute. If there are no more Interceptors
-    * to be applied, the Action is executed.
+    * Invokes the next step in processing this ActionInvocation. If there are more Interceptors, this will call the next
+    * one. If Interceptors choose not to short-circuit ActionInvocation processing and return their own return code,
+    * they will call invoke() to allow the next Interceptor to execute. If there are no more Interceptors to be applied,
+    * the Action is executed. If the ActionProxy getExecuteResult() method returns true, the Result is also executed.
     * @return
     * @throws Exception
     */

src/java/com/opensymphony/xwork/ActionProxy.java

 
 
 /**
- * ActionProxy
+ * ActionProxy is an extra layer between XWork and the action so that different proxies are possible.
+ *
+ * An example of this would be a remote proxy, where the layer between XWork and the action might be RMI or SOAP.
  * @author Jason Carreira
  * Created Jun 9, 2003 11:27:55 AM
  */
 public interface ActionProxy extends Serializable {
     //~ Methods ////////////////////////////////////////////////////////////////
 
+    /**
+     * @return the Action instance for this Proxy
+     */
     Action getAction();
 
+    /**
+     * @return the alias name this ActionProxy is mapped to
+     */
     String getActionName();
 
+    /**
+     * @return the ActionConfig this ActionProxy is built from
+     */
     ActionConfig getConfig();
 
+    /**
+     * Sets whether this ActionProxy should also execute the Result after executing the Action
+     * @param executeResult
+     */
     void setExecuteResult(boolean executeResult);
 
+    /**
+     * @return the status of whether the ActionProxy is set to execute the Result after the Action is executed
+     */
     boolean getExecuteResult();
 
+    /**
+     * @return the ActionInvocation associated with this ActionProxy
+     */
     ActionInvocation getInvocation();
 
+    /**
+     * @return the namespace the ActionConfig for this ActionProxy is mapped to
+     */
     String getNamespace();
 
+    /**
+     * Execute this ActionProxy. This will set the ActionContext from the ActionInvocation into the ActionContext
+     * ThreadLocal before invoking the ActionInvocation, then set the old ActionContext back into the ThreadLocal.
+     * @return the result code returned from executing the ActionInvocation
+     * @throws Exception
+     * @see com.opensymphony.xwork.ActionInvocation
+     */
     String execute() throws Exception;
 }

src/java/com/opensymphony/xwork/ActionProxyFactory.java

 
 
 /**
- * ActionProxyFactory
+ * The ActionProxyFactory is used to create ActionProxies to be executed. It is the entry point to XWork that is used
+ * by a dispatcher to create an ActionProxy to execute for a particular namespace and action name.
  * @author Jason Carreira
  * Created Jun 15, 2003 5:18:30 PM
+ * @see com.opensymphony.xwork.DefaultActionProxyFactory
  */
 public abstract class ActionProxyFactory {
     //~ Static fields/initializers /////////////////////////////////////////////
 
     //~ Methods ////////////////////////////////////////////////////////////////
 
+    /**
+     * Set the ActionProxyFactory implementation to use. If no instance is set, a new DefaultActionProxyFactory is used.
+     * @param factory
+     */
     public static void setFactory(ActionProxyFactory factory) {
         ActionProxyFactory.factory = factory;
     }
         return factory;
     }
 
+    /**
+     * Used by an ActionProxy or ActionProxyFactory to create an ActionInvocation to associate with an ActionProxy
+     * as part of creating an ActionProxy. Client code should not need to call the createActionInvocation methods.
+     * @param actionProxy
+     * @param extraContext
+     * @return
+     * @throws Exception
+     */
     public abstract ActionInvocation createActionInvocation(ActionProxy actionProxy, Map extraContext) throws Exception;
 
+    /**
+     * Used by an ActionProxy or ActionProxyFactory to create an ActionInvocation to associate with an ActionProxy
+     * as part of creating an ActionProxy. Client code should not need to call the createActionInvocation methods.
+     * @param actionProxy
+     * @return
+     * @throws Exception
+     */
     public abstract ActionInvocation createActionInvocation(ActionProxy actionProxy) throws Exception;
 
+    /**
+     * Used by an ActionProxy or ActionProxyFactory to create an ActionInvocation to associate with an ActionProxy
+     * as part of creating an ActionProxy. Client code should not need to call the createActionInvocation methods.
+     * @param actionProxy
+     * @param extraContext
+     * @param pushAction tells whether the Action should be pushed onto the ValueStack 
+     * @return
+     * @throws Exception
+     */
     public abstract ActionInvocation createActionInvocation(ActionProxy actionProxy, Map extraContext, boolean pushAction) throws Exception;
 
+    /**
+     * Creates an ActionProxy for the given namespace and action name by looking up the configuration. The ActionProxy
+     * should be fully initialized when it is returned, including having an ActionInvocation instance associated.
+     * @param namespace the namespace of the action
+     * @param actionName
+     * @param extraContext a Map of extra parameters to be provided to the ActionProxy
+     * @return
+     * @throws Exception
+     */
     public abstract ActionProxy createActionProxy(String namespace, String actionName, Map extraContext) throws Exception;
 
+    /**
+     * Creates an ActionProxy for the given namespace and action name by looking up the configuration. The ActionProxy
+     * should be fully initialized when it is returned, including having an ActionInvocation instance associated.
+     * @param namespace the namespace of the action
+     * @param actionName
+     * @param extraContext a Map of extra parameters to be provided to the ActionProxy
+     * @param executeResult flag which tells whether the result should be executed after the action
+     * @return
+     * @throws Exception
+     */
     public abstract ActionProxy createActionProxy(String namespace, String actionName, Map extraContext, boolean executeResult) throws Exception;
 }

src/java/com/opensymphony/xwork/DefaultActionInvocation.java

 
 
 /**
+ * The Default ActionInvocation implementation
  * @author $Author$
  * @version $Revision$
+ * @see com.opensymphony.xwork.DefaultActionProxy
  */
 public class DefaultActionInvocation implements ActionInvocation {
     //~ Static fields/initializers /////////////////////////////////////////////

src/java/com/opensymphony/xwork/DefaultActionProxy.java

 
 
 /**
- * The DefaultActionProxy is an extra layer between XWork and the action so that different proxies are possible.
- *
- * An example of this would be a remote proxy, where the layer between XWork and the action might be RMI or SOAP.
+ * The Default ActionProxy implementation
  *
  * @author $Author$
  * @version $Revision$