Commits

Anonymous committed e1cf2fc

Cleaned up JavaDocs

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

Comments (0)

Files changed (1)

src/java/com/opensymphony/xwork/ActionContext.java

 
 
 /**
- * @author $Author$
- * @version $Revision$
+ * The ActionContext is the context in which an {@link Action} is executed. Each context is basically a
+ * container of objects an action needs for execution like the session, parameters, locale, etc. <p>
+ *
+ * The ActionContext is thread local which means that values stored in the ActionContext are
+ * unique per thread. See the {@link java.lang.ThreadLocal} class for more information. The benefit of
+ * this is you don't need to worry about a user specific action context, you just get it:
+ *
+ * <ul><code>ActionContext context = ActionContext.getContext();</code></ul>
+ *
+ * Finally, because of the thread local usage you don't need to worry about making your actions thread safe.
+ *
+ * @author Patrick Lightbody
+ * @author Bill Lynch (docs)
  */
 public class ActionContext {
     //~ Static fields/initializers /////////////////////////////////////////////
 
     static ThreadLocal actionContext = new ActionContextThreadLocal();
+
+    /**
+     * Constant for the name of the action being executed.
+     */
     public static final String ACTION_NAME = "com.opensymphony.xwork.ActionContext.name";
+    /**
+     * Constant for the {@link com.opensymphony.xwork.util.OgnlValueStack OGNL value stack}.
+     */
     public static final String VALUE_STACK = OgnlValueStack.VALUE_STACK;
+    /**
+     * Constant for the action's session.
+     */
     public static final String SESSION = "com.opensymphony.xwork.ActionContext.session";
+    /**
+     * Constant for the action's application context.
+     */
     public static final String APPLICATION = "com.opensymphony.xwork.ActionContext.application";
+    /**
+     * Constant for the action's parameters.
+     */
     public static final String PARAMETERS = "com.opensymphony.xwork.ActionContext.parameters";
+    /**
+     * Constant for the action's locale.
+     */
     public static final String LOCALE = "com.opensymphony.xwork.ActionContext.locale";
+    /**
+     * Constant for the action's type converter.
+     */
     public static final String TYPE_CONVERTER = "com.opensymphony.xwork.ActionContext.typeConverter";
+    /**
+     * Constant for the action's {@link com.opensymphony.xwork.ActionInvocation invocation} context.
+     */
     public static final String ACTION_INVOCATION = "com.opensymphony.xwork.ActionContext.actionInvocation";
+    /**
+     * Constant for the map of type conversion errors.
+     */
     public static final String CONVERSION_ERRORS = "com.opensymphony.xwork.ActionContext.conversionErrors";
 
     //~ Instance fields ////////////////////////////////////////////////////////
 
     //~ Constructors ///////////////////////////////////////////////////////////
 
+    /**
+     * Creates a new ActionContext initialized with another context.
+     *
+     * @param context a context map.
+     */
     public ActionContext(Map context) {
         this.context = context;
     }
 
     //~ Methods ////////////////////////////////////////////////////////////////
 
+    /**
+     * Sets the action invocation (the execution state).
+     *
+     * @param actionInvocation the action execution state.
+     */
     public void setActionInvocation(ActionInvocation actionInvocation) {
         put(ACTION_INVOCATION, actionInvocation);
     }
 
+    /**
+     * Gets the action invocation (the execution state).
+     *
+     * @return the action invocation (the execution state).
+     */
     public ActionInvocation getActionInvocation() {
         return (ActionInvocation) get(ACTION_INVOCATION);
     }
 
     /**
-     * Set an application level Map.
+     * Sets the action's application context.
+     *
+     * @param application the action's application context.
      */
     public void setApplication(Map application) {
         put(APPLICATION, application);
     }
 
     /**
-     * Returns a Map of the ServletContext when in a servlet environment or
-     * a generic application level Map otherwise.
+     * Returns a Map of the ServletContext when in a servlet environment or a generic application level Map otherwise.
      *
-     * @return Map of ServletContext or generic application level Map
+     * @return a Map of ServletContext or generic application level Map
      */
     public Map getApplication() {
         return (Map) get(APPLICATION);
     }
 
-    public static void setContext(ActionContext aContext) {
-        actionContext.set(aContext);
+    /**
+     * Sets the action context for the current thread.
+     *
+     * @param context the action context.
+     */
+    public static void setContext(ActionContext context) {
+        actionContext.set(context);
     }
 
     /**
      * Returns the ActionContext specific to the current thread.
      *
-     * @return ActionContext for the current thread
+     * @return the ActionContext for the current thread.
      */
     public static ActionContext getContext() {
         ActionContext context = (ActionContext) actionContext.get();
         return context;
     }
 
-    public void setContextMap(Map lookup) {
-        getContext().context = lookup;
+    /**
+     * Sets the action's context map.
+     *
+     * @param contextMap the context map.
+     */
+    public void setContextMap(Map contextMap) {
+        getContext().context = contextMap;
     }
 
+    /**
+     * Gets the context map.
+     *
+     * @return the context map.
+     */
     public Map getContextMap() {
         return context;
     }
 
+    /**
+     * Sets conversion errors which occurred when executing the action.
+     *
+     * @param conversionErrors a Map of errors which occurred when executing the action.
+     */
     public void setConversionErrors(Map conversionErrors) {
         put(CONVERSION_ERRORS, conversionErrors);
     }
 
+    /**
+     * Gets the map of conversion errors which occurred when executing the action.
+     *
+     * @return the map of conversion errors which occurred when executing the action or an empty map if
+     *      there were no errors.
+     */
     public Map getConversionErrors() {
         Map errors = (Map) get(CONVERSION_ERRORS);
 
     }
 
     /**
-     * Sets the Locale for the current request
-     * @param locale
+     * Sets the Locale for the current action.
+     *
+     * @param locale the Locale for the current action.
      */
     public void setLocale(Locale locale) {
         put(LOCALE, locale);
     }
 
     /**
-     * Gets the Locale of the current request
-     * @return Locale
+     * Gets the Locale of the current action. If no locale was ever specified the platform's
+     * {@link java.util.Locale#getDefault() default locale} is used.
+     *
+     * @return the Locale of the current action.
      */
     public Locale getLocale() {
         Locale locale = (Locale) get(LOCALE);
     }
 
     /**
-     * Stores the name of the current Action in the ActionContext.
+     * Sets the name of the current Action in the ActionContext.
      *
-     * @param name The name of the current action.
+     * @param name the name of the current action.
      */
     public void setName(String name) {
         put(ACTION_NAME, name);
     }
 
     /**
-     * Returns the name of the current Action.
+     * Gets the name of the current Action.
      *
-     * @return The current Action name.
+     * @return the name of the current action.
      */
     public String getName() {
         return (String) get(ACTION_NAME);
     }
 
     /**
-     * Set a Map of parameters.
+     * Sets the action parameters.
      *
-     * @param parameters The parameters for the current action context.
+     * @param parameters the parameters for the current action.
      */
     public void setParameters(Map parameters) {
         put(PARAMETERS, parameters);
     }
 
     /**
-     * Returns a Map of the HttpServletRequest parameters when in a servlet
-     * environment or a generic Map of parameters otherwise.
+     * Returns a Map of the HttpServletRequest parameters when in a servlet environment or a generic Map of
+     * parameters otherwise.
      *
-     * @return Map of HttpServletRequest parameters, generic Map of parameters or
-     * multipart Map.
+     * @return a Map of HttpServletRequest parameters or a multipart map when in a servlet environment, or a
+     *      generic Map of parameters otherwise.
      */
     public Map getParameters() {
         return (Map) get(PARAMETERS);
     }
 
     /**
-     * Set a session Map.
+     * Sets a map of action session values.
      */
     public void setSession(Map session) {
         put(SESSION, session);
     }
 
     /**
-     * Returns the HttpSession when in a servlet environment or a generic
-     * session map otherwise.
+     * Gets the Map of HttpSession values when in a servlet environment or a generic session map otherwise.
      *
-     * @return a map of HttpSession or a generic session map
+     * @return the Map of HttpSession values when in a servlet environment or a generic session map otherwise.
      */
     public Map getSession() {
         return (Map) get(SESSION);
     }
 
+    /**
+     * Sets the OGNL value stack.
+     *
+     * @param stack the OGNL value stack.
+     */
     public void setValueStack(OgnlValueStack stack) {
         put(VALUE_STACK, stack);
     }
 
+    /**
+     * Gets the OGNL value stack.
+     *
+     * @return the OGNL value stack.
+     */
     public OgnlValueStack getValueStack() {
         return (OgnlValueStack) get(VALUE_STACK);
     }
 
     /**
-     * Returns a value that is stored in the current ActionContext
-     * by doing a lookup using the value's key.
+     * Returns a value that is stored in the current ActionContext by doing a lookup using the value's key.
      *
-     * @param key The key used to find the value.
-     * @return The value that was found using the key.
+     * @param key the key used to find the value.
+     * @return the value that was found using the key or <tt>null</tt> if the key was not found.
      */
     public Object get(Object key) {
         return context.get(key);
     }
 
     /**
-     * Stores a value in the current ActionContext.  The value can
-     * be looked up using the key.
+     * Stores a value in the current ActionContext. The value can be looked up using the key.
      *
-     * @param key The key of the value.
-     * @param value The value to be stored.
+     * @param key the key of the value.
+     * @param value the value to be stored.
      */
     public void put(Object key, Object value) {
         context.put(key, value);