svn commit: r1517763 - /jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/RefreshManager.java

[mduerig]

Author: mduerig
Date: Tue Aug 27 08:28:58 2013
New Revision: 1517763

URL: http://svn.apache.org/r1517763
Log:
OAK-960 Provide an interceptor for SessionOperations
Javadoc

Modified:
    
jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/RefreshManager.java

Modified: 
jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/RefreshManager.java
URL: 
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/RefreshManager.java?rev=1517763&r1=1517762&r2=1517763&view=diff
==============================================================================
--- 
jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/RefreshManager.java
 (original)
+++ 
jackrabbit/oak/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/delegate/RefreshManager.java
 Tue Aug 27 08:28:58 2013
@@ -25,8 +25,19 @@ import static java.util.concurrent.TimeU
 import org.apache.jackrabbit.oak.jcr.operation.SessionOperation;
 
 /**
-* michid document
-*/
+ * This class contains the auto refresh logic for sessions, which is done to 
enhance backwards
+ * compatibility with Jackrabbit 2.
+ * <p>
+ * A sessions is automatically refreshed when
+ * <ul>
+ *     <li>it has not been accessed for the number of seconds specified by the
+ *         {@code refreshInterval} parameter,</li>
+ *     <li>an observation event has been delivered to a listener registered 
from within this
+ *         session,</li>
+ *     <li>an updated occurred through a different session from <em>within the 
same
+ *         thread.</em></li>
+ * </ul>
+ */
 public class RefreshManager {
     private final Exception initStackTrace = new Exception("The session was 
created here:");
     private final long refreshInterval;
@@ -54,6 +65,14 @@ public class RefreshManager {
         sessionSaveCount = getOr0(threadSaveCount);
     }
 
+    /**
+     * Called before the passed {@code sessionOperation} is performed. This 
method
+     * refreshes the session according to the rules given in the class comment.
+     *
+     * @param delegate  session on which the {@code sessionOperation} is 
executed
+     * @param sessionOperation  the operation to be executed
+     * @return  {@code true} if a refreshed, {@code false} otherwise.
+     */
     boolean refreshIfNecessary(SessionDelegate delegate, SessionOperation<?> 
sessionOperation) {
         long now = System.currentTimeMillis();
         long timeElapsed = now - lastAccessed;