svn commit: r740232 - /cocoon/cocoon3/trunk/cocoon-servlet/src/main/java/org/apache/cocoon/servlet/controller/ControllerContextHelper.java

[re...@apache.org]

Author: reinhard
Date: Tue Feb  3 06:59:49 2009
New Revision: 740232

URL: http://svn.apache.org/viewvc?rev=740232&view=rev
Log:
. Javadocs
. add a method to directly store controller context objects in the Request

Modified:
    cocoon/cocoon3/trunk/cocoon-servlet/src/main/java/org/apache/cocoon/servlet/controller/ControllerContextHelper.java

Modified: cocoon/cocoon3/trunk/cocoon-servlet/src/main/java/org/apache/cocoon/servlet/controller/ControllerContextHelper.java
URL: http://svn.apache.org/viewvc/cocoon/cocoon3/trunk/cocoon-servlet/src/main/java/org/apache/cocoon/servlet/controller/ControllerContextHelper.java?rev=740232&r1=740231&r2=740232&view=diff
==============================================================================
--- cocoon/cocoon3/trunk/cocoon-servlet/src/main/java/org/apache/cocoon/servlet/controller/ControllerContextHelper.java (original)
+++ cocoon/cocoon3/trunk/cocoon-servlet/src/main/java/org/apache/cocoon/servlet/controller/ControllerContextHelper.java Tue Feb  3 06:59:49 2009
@@ -25,12 +25,26 @@
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 
+/**
+ * This class helps with storing and retrieving the controller context.
+ * Internally it uses the current servlet request. Thanks to the servlet-service
+ * framework, the current request becomes the parent of all sub-requests that
+ * use e.g. the 'servlet:' protocol. This means that it is enough to store
+ * objects that should be available in a sub-request into the current request.
+ */
 public class ControllerContextHelper {
 
     private static final Log LOG = LogFactory.getLog(ControllerContextHelper.class);
 
     private static final String CONTEXT_OBJECT = ControllerContextHelper.class.getName();
 
+    /**
+     * Retrieve the current controller context from the Cocoon parameters.
+     * 
+     * @param parameters The Cocoon parameters map.
+     * @return The controller context map as being available in the current
+     *         servlet request.
+     */
     @SuppressWarnings("unchecked")
     public static Map<String, Object> getContext(Map<String, ? extends Object> parameters) {
         HttpServletRequest request = HttpContextHelper.getRequest(parameters);
@@ -44,8 +58,28 @@
         return Collections.EMPTY_MAP;
     }
 
+    /**
+     * Store the controller context (a {@link Map}) in the Cocoon parameters.
+     * 
+     * @param controllerContext The objects that should be available in the
+     *            child request.
+     * @param parameters The Cocoon parameters map.
+     */
     public static void storeContext(Map<String, Object> controllerContext, Map<String, Object> parameters) {
         HttpServletRequest request = HttpContextHelper.getRequest(parameters);
+        storeContext(controllerContext, request);
+    }
+
+    /**
+     * Store the controller context (a {@link Map} directly into the
+     * {@link HttpServletRequest}.
+     * 
+     * @param controllerContext The objects that should be available in the
+     *            child request.
+     * @param request The current request that becomes the parent of the next
+     *            request.
+     */
+    public static void storeContext(Map<String, Object> controllerContext, HttpServletRequest request) {
         request.setAttribute(CONTEXT_OBJECT, controllerContext);
     }
 }