Merge branch 'master' of github.com:jcoleman/tomcat-redis-session-manager into tomcat-7

Author: jcoleman

README.markdown

@@ -38,6 +38,44 @@ Copy the tomcat-redis-session-manager.jar and jedis-2.0.0.jar files into the `li
 
 Reboot the server, and sessions should now be stored in Redis.
 
+Session Change Tracking
+-----------------------
+
+As noted in the "Overview" section above, in order to prevent colliding writes, the Redis Session Manager only serializes the session object into Redis if the session object has changed (it always updates the expiration separately however.) This dirty tracking marks the session as needing serialization according to the following rules:
+
+* Calling `session.removeAttribute(key)` always marks the session as dirty (needing serialization.)
+* Calling `session.setAttribute(key, newAttributeValue)` marks the session as dirty if any of the following are true:
+    * `previousAttributeValue == null && newAttributeValue != null`
+    * `previousAttributeValue != null && newAttributeValue == null`
+    * `!newAttributeValue.getClass().isInstance(previousAttributeValue)`
+    * `!newAttributeValue.equals(previousAttributeValue)`
+
+This feature can have the unintended consequence of hiding writes if you implicitly change a key in the session or if the object's equality does not change even though the key is updated. For example, assuming the session already contains the key `"myArray"` with an Array instance as its corresponding value, and has been previously serialized, the following code would not cause the session to be serialized again:
+
+    List myArray = session.getAttribute("myArray");
+    myArray.add(additionalArrayValue);
+
+If your code makes these kind of changes, then the RedisSession provides a mechanism by which you can mark the session as dirty in order to guarantee serialization at the end of the request. For example:
+
+    List myArray = session.getAttribute("myArray");
+    myArray.add(additionalArrayValue);
+    session.setAttribute("__changed__");
+
+In order to not cause issues with an application that may already use the key `"__changed__"`, this feature is disabled by default. To enable this feature, simple call the following code in your application's initialization:
+
+    RedisSession.setManualDirtyTrackingSupportEnabled(true);
+
+This feature also allows the attribute key used to mark the session as dirty to be changed. For example, if you executed the following:
+
+    RedisSession.setManualDirtyTrackingAttributeKey("customDirtyFlag");
+
+Then the example above would look like this:
+
+    List myArray = session.getAttribute("myArray");
+    myArray.add(additionalArrayValue);
+    session.setAttribute("customDirtyFlag");
+
+
 Possible Issues
 ---------------
 

src/main/java/com/radiadesign/catalina/session/RedisSession.java

@@ -12,6 +12,19 @@
 public class RedisSession extends StandardSession {
   private static Logger log = Logger.getLogger("RedisSession");
 
+  protected static Boolean manualDirtyTrackingSupportEnabled = false;
+
+  public void setManualDirtyTrackingSupportEnabled(Boolean enabled) {
+    manualDirtyTrackingSupportEnabled = enabled;
+  }
+
+  protected static String manualDirtyTrackingAttributeKey = "__changed__";
+
+  public void setManualDirtyTrackingAttributeKey(String key) {
+    manualDirtyTrackingAttributeKey = key;
+  }
+
+
   protected HashMap<String, Object> changedAttributes;
   protected Boolean dirty;
 
@@ -34,6 +47,11 @@ public void resetDirtyTracking() {
   }
 
   public void setAttribute(String key, Object value) {
+    if (manualDirtyTrackingSupportEnabled && manualDirtyTrackingAttributeKey.equals(key)) {
+      dirty = true;
+      return;
+    }
+
     Object oldValue = getAttribute(key);
     if ( value == null && oldValue != null
          || oldValue == null && value != null