svn commit: r1225039 - /jackrabbit/sandbox/jackrabbit-microkernel/src/main/java/org/apache/jackrabbit/state/TransientSpace.java

[md...@apache.org]

Author: mduerig
Date: Tue Dec 27 22:39:22 2011
New Revision: 1225039

URL: http://svn.apache.org/viewvc?rev=1225039&view=rev
Log:
Microkernel based prototype of JCR implementation (WIP)
- javadoc

Modified:
    jackrabbit/sandbox/jackrabbit-microkernel/src/main/java/org/apache/jackrabbit/state/TransientSpace.java

Modified: jackrabbit/sandbox/jackrabbit-microkernel/src/main/java/org/apache/jackrabbit/state/TransientSpace.java
URL: http://svn.apache.org/viewvc/jackrabbit/sandbox/jackrabbit-microkernel/src/main/java/org/apache/jackrabbit/state/TransientSpace.java?rev=1225039&r1=1225038&r2=1225039&view=diff
==============================================================================
--- jackrabbit/sandbox/jackrabbit-microkernel/src/main/java/org/apache/jackrabbit/state/TransientSpace.java (original)
+++ jackrabbit/sandbox/jackrabbit-microkernel/src/main/java/org/apache/jackrabbit/state/TransientSpace.java Tue Dec 27 22:39:22 2011
@@ -11,11 +11,24 @@ import org.apache.jackrabbit.utils.Funct
 import javax.jcr.PathNotFoundException;
 import javax.jcr.RepositoryException;
 
+/**
+ * {@code TransientSpace} instances use a {@link org.apache.jackrabbit.state.ChangeTree} to
+ * record transient changes in a JCR hierarchy. Changes can be persisted by calling
+ * {@link #save()}. A transient space is bound to a specific revision. Calling
+ * {@link #refresh(boolean)} updates the revision to the latest.
+ */
 public class TransientSpace {
     private final MicroKernel microkernel;
     private final ChangeTree changeTree;
     private String revision;
 
+    /**
+     * Create a new transient space for the given {@code workspace}, {@code microkernel}
+     * and {@code revision}.
+     * @param workspace
+     * @param microkernel
+     * @param revision
+     */
     public TransientSpace(String workspace, final MicroKernel microkernel, final String revision) {
         this.microkernel = microkernel;
         this.revision = revision;
@@ -28,14 +41,31 @@ public class TransientSpace {
         });
     }
 
+    /**
+     * @param path
+     * @return {@code true} iff there exists a node at the given {@code path}. The node
+     * is either a persisted node in the revision currently bound to this transient space
+     * or a transient node.
+     */
     public boolean nodeExists(Path path) {
         return changeTree.nodeExists(path);
     }
 
+    /**
+     * @param path
+     * @return the node at the given {@code path}. The node is either a persisted node in the
+     * revision currently bound to this transient space or a transient node.
+     * @throws PathNotFoundException
+     */
     public NodeDelta getNode(Path path) throws PathNotFoundException {
         return changeTree.getNode(path);
     }
 
+    /**
+     * Atomically persist all transient changes
+     * @return  the new revision resulting from saving all transient changes.
+     * @throws RepositoryException
+     */
     public String save() throws RepositoryException {
         try {
             final StringBuilder jsop = new StringBuilder();
@@ -89,6 +119,13 @@ public class TransientSpace {
         }
     }
 
+    /**
+     * Refresh to the latest revision of the persistence store. If {@code keepChanges}
+     * is {@code true} transient changes are kept, other wise transient changes are discarded.
+     * <em>Note</em>: Keeping transient changes might cause conflicts on subsequent save operations.
+     * @param keepChanges
+     * @return the new revision
+     */
     public String refresh(boolean keepChanges) {
         if (!keepChanges) {
             changeTree.clear();
@@ -97,6 +134,9 @@ public class TransientSpace {
         return revision = microkernel.getHeadRevision();
     }
 
+    /**
+     * @return {@code true} iff the transient space contains transient changes.
+     */
     public boolean isDirty() {
         return changeTree.hasChanges();
     }