[Statelessfilter-commits] SF.net SVN: statelessfilter:[81] trunk/stateless-core/src/main/java/net/ sourceforge/statelessfilter/backend/support/CookieBackendSupport.java

[<nri...@us...>]

Revision: 81
          http://statelessfilter.svn.sourceforge.net/statelessfilter/?rev=81&view=rev
Author:   nricheton
Date:     2011-06-15 10:39:12 +0000 (Wed, 15 Jun 2011)

Log Message:
-----------
Added comments

Modified Paths:
--------------
    trunk/stateless-core/src/main/java/net/sourceforge/statelessfilter/backend/support/CookieBackendSupport.java

Modified: trunk/stateless-core/src/main/java/net/sourceforge/statelessfilter/backend/support/CookieBackendSupport.java
===================================================================
--- trunk/stateless-core/src/main/java/net/sourceforge/statelessfilter/backend/support/CookieBackendSupport.java	2011-03-19 15:07:44 UTC (rev 80)
+++ trunk/stateless-core/src/main/java/net/sourceforge/statelessfilter/backend/support/CookieBackendSupport.java	2011-06-15 10:39:12 UTC (rev 81)
@@ -32,15 +32,52 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * An helper class for backend implementations which are using cookies to store
+ * data.
+ * 
+ * <p>
+ * Includes standard cookies attributes parameters (domain / name, maxAge, path)
+ * and implements cookie creation and reading.
+ * 
+ * <p>
+ * If cookie data is over 3k, it is automatically split into several cookies.
+ * <p>
+ * Default values are :
+ * <ul>
+ * <li>cookieName : "session"</li>
+ * <li>domain : default</li>
+ * <li>maxAge : unlimited</li>
+ * <li>path : "/"</li>
+ * </ul>
+ * 
+ * @author Nicolas Richeton
+ * 
+ */
 public abstract class CookieBackendSupport implements ISessionBackend {
+	/**
+	 * If cookie data exceed this value, multiple cookie are created.
+	 */
 	private static final int COOKIE_MAX_SIZE = 3000;
 	private static Logger logger = LoggerFactory
 			.getLogger(CookieBackendSupport.class);
+
+	/* Constants used in properties */
 	private static final String PARAM_COOKIEDOMAIN = "cookiedomain"; //$NON-NLS-1$
 	private static final String PARAM_COOKIEMAXAGE = "cookiemaxage"; //$NON-NLS-1$
 	private static final String PARAM_COOKIENAME = "cookiename"; //$NON-NLS-1$
 	private static final String PARAM_COOKIEPATH = "cookiepath"; //$NON-NLS-1$
+
+	/**
+	 * Constant used to store the number of cookie segment within a single
+	 * request. This information is used for cleaning.
+	 * 
+	 * <p>Constant value depends of the cookie name. 
+	 * @see CookieBackendSupport#setCookieName(String)
+	 */
 	private String ATTR_COUNT = "stateless.session.count"; //$NON-NLS-1$
+
+	/* Default values */
 	protected String cookieName = "session"; //$NON-NLS-1$
 	protected String domain = null;
 	protected Integer maxAge = null;
@@ -57,24 +94,30 @@
 	abstract public String getId();
 
 	/**
-	 * Implements cookie name configuration.
+	 * Read cookie configuration : name, path, domain and maxAge.
 	 * 
 	 * @see net.sourceforge.statelessfilter.backend.ISessionBackend#init(java.util.Map)
 	 */
 	public void init(Map<String, String> config) throws Exception {
+		// Name
 		String name = config.get(PARAM_COOKIENAME);
 		if (!StringUtils.isEmpty(name)) {
 			setCookieName(name);
 		}
 
+		// Path
 		String path = config.get(PARAM_COOKIEPATH);
 		if (!StringUtils.isEmpty(path)) {
 			this.path = path;
 		}
+
+		// Domain
 		String domain = config.get(PARAM_COOKIEDOMAIN);
 		if (!StringUtils.isEmpty(domain)) {
 			this.domain = domain;
 		}
+
+		// MaxAge
 		String maxAge = config.get(PARAM_COOKIEMAXAGE);
 		if (!StringUtils.isEmpty(maxAge)) {
 			this.maxAge = new Integer(Integer.parseInt(maxAge));
@@ -83,6 +126,9 @@
 	}
 
 	/**
+	 * Always true for cookies since we need to create cookie at the end of the
+	 * request, when data has already been sent.
+	 * 
 	 * @see net.sourceforge.statelessfilter.backend.ISessionBackend#isBufferingRequired()
 	 */
 	public boolean isBufferingRequired() {
@@ -94,9 +140,10 @@
 	 */
 	abstract public ISessionData restore(HttpServletRequest request);
 
-	
 	/**
-	 * @see net.sourceforge.statelessfilter.backend.ISessionBackend#save(net.sourceforge.statelessfilter.backend.ISessionData, java.util.List, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)
+	 * @see net.sourceforge.statelessfilter.backend.ISessionBackend#save(net.sourceforge.statelessfilter.backend.ISessionData,
+	 *      java.util.List, javax.servlet.http.HttpServletRequest,
+	 *      javax.servlet.http.HttpServletResponse)
 	 */
 	abstract public void save(ISessionData session,
 			List<String> dirtyAttributes, HttpServletRequest request,
@@ -135,6 +182,13 @@
 		return null;
 	}
 
+	/**
+	 * Read raw data from cookie.
+	 * 
+	 * @param request
+	 * @param response
+	 * @return
+	 */
 	protected byte[] getCookieData(HttpServletRequest request,
 			HttpServletResponse response) {
 		int i = 0;
@@ -156,8 +210,11 @@
 	}
 
 	/**
-	 * Set cookie. Data is split in several cookies if it exceeds max cookie
-	 * length.
+	 * Set raw data in a cookie. Data is split in several cookies if it exceeds
+	 * max cookie length.
+	 * <p>
+	 * Also ensure that the reponse cannot be cached (Cache-control header set
+	 * to private/no-cache/no-store/must-revalidate)
 	 * 
 	 * @param request
 	 * @param response
@@ -166,8 +223,9 @@
 	protected void setCookieData(HttpServletRequest request,
 			HttpServletResponse response, byte[] data) {
 		// As soon as we send a session cookie, the response must not be cached.
-		response.setHeader("Cache-Control", "private, no-cache, no-store, must-revalidate");
-		
+		response.setHeader("Cache-Control",
+				"private, no-cache, no-store, must-revalidate");
+
 		String encoded = StringUtils.EMPTY;
 		if (data != null) {
 			encoded = new String(Base64.encodeBase64(data));
@@ -198,12 +256,17 @@
 			response.addCookie(c);
 			i++;
 		}
-		
-	
+
 	}
 
+	/**
+	 * Set the name of the cookie and update internal values accordingly.
+	 * @param cookieName
+	 */
 	protected void setCookieName(String cookieName) {
 		this.cookieName = cookieName;
+		
+		// Update constant to inclue cookie name. 
 		ATTR_COUNT = "stateless." + cookieName + ".count"; //$NON-NLS-1$ //$NON-NLS-2$
 	}
 }


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.