Brought javadocs up to date with current api behavior in AVMService.

Got rid of a redundant and mostly unused method, the createSnapshot()
that takes a List of names.  Adjusted to fit.


git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/BRANCHES/WCM-DEV2/root@4453 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261

source/java/org/alfresco/repo/avm/AVMRemote.java

@@ -207,13 +207,6 @@ public interface AVMRemote
      */
     public int getLatestSnapshotID(String storeName);
     
-    /**
-     * Snapshot the given AVMStores.
-     * @param stores A List of the names of the stores to snapshot.
-     * @return A List of the version ids of the newly created snapshots.
-     */
-    public List<Integer> createSnapshot(List<String> stores);
-    
     /**
      * Snapshot an AVMStore.
      * @param store The name of the AVMStore to snapshot.

source/java/org/alfresco/repo/avm/AVMRemoteImpl.java

@@ -573,7 +573,7 @@ public class AVMRemoteImpl implements AVMRemote, Runnable
      */
     public int getLatestVersionID(String storeName)
     {
-        return fAVMService.getLatestVersionID(storeName);
+        return fAVMService.getNextVersionID(storeName);
     }
     
     /**
@@ -586,16 +586,6 @@ public class AVMRemoteImpl implements AVMRemote, Runnable
         return fAVMService.getLatestSnapshotID(storeName);
     }
     
-    /**
-     * Snapshot the given AVMStores.
-     * @param stores A List of the names of the stores to snapshot.
-     * @return A List of the version ids of the newly created snapshots.
-     */
-    public List<Integer> createSnapshot(List<String> stores)
-    {
-        return fAVMService.createSnapshot(stores);
-    }
-    
     // TODO update this if it's ever needed.
     /**
      * Snapshot an AVMStore.

source/java/org/alfresco/repo/avm/AVMServiceImpl.java

@@ -557,7 +557,7 @@ public class AVMServiceImpl implements AVMService
      * @param repName The name of the AVMStore.
      * @return The Latest Version ID.
      */
-    public int getLatestVersionID(String repName)
+    public int getNextVersionID(String repName)
     {
         if (repName == null)
         {
@@ -581,21 +581,7 @@ public class AVMServiceImpl implements AVMService
         return fAVMRepository.getLatestSnapshotID(storeName);
     }
 
-    /**
+    /*
-     * Create snapshots of a group of AVMStores.
-     * @param stores A List of AVMStore names.
-     * @return A List of the new version ids.
-     */
-    public List<Integer> createSnapshot(List<String> stores)
-    {
-        if (stores == null)
-        {
-            throw new AVMBadArgumentException("Stores is null.");
-        }
-        return fAVMRepository.createSnapshot(stores);
-    }
-
-    /**
      * Snapshot an AVMRepository.
      * @param store The name of the AVMStore.
      * @param tag The short description.

source/java/org/alfresco/repo/avm/AVMServiceTest.java

@@ -1375,7 +1375,7 @@ public class AVMServiceTest extends AVMServiceTestBase
             checkHistory(history, "main");
             // Everything under /abranch should be identical in this version 
             // and the previous.
-            int version = fService.getLatestVersionID("main");
+            int version = fService.getNextVersionID("main");
             assertEquals(recursiveContents("main:/abranch", version - 1, true),
                          recursiveContents("main:/abranch", version - 2, true));
             // Make a branch within a branch.
@@ -1384,7 +1384,7 @@ public class AVMServiceTest extends AVMServiceTestBase
             // History unchanged
             checkHistory(history, "main");
             // Everything under /a should be unchanged between this version and the last.
-            version = fService.getLatestVersionID("main");
+            version = fService.getNextVersionID("main");
             assertEquals(recursiveContents("main:/a", version - 1, true),
                          recursiveContents("main:/a", version - 2, true));
             // Make a branch to something outside of a branch inside a branch.
@@ -1398,7 +1398,7 @@ public class AVMServiceTest extends AVMServiceTestBase
             // History unchanged.
             checkHistory(history, "main");
             // d should not have changed since the previous version.
-            version = fService.getLatestVersionID("main");
+            version = fService.getNextVersionID("main");
             assertEquals(recursiveContents("main:/d", version - 1, true),
                          recursiveContents("main:/d", version - 2, true));
             for (String val : history.values())
@@ -1472,7 +1472,7 @@ public class AVMServiceTest extends AVMServiceTestBase
             checkHistory(history, "main");
             // /d should be unchanged before this version and the last
             // and /g should be unchanged between this version and the last.
-            int version = fService.getLatestVersionID("main");
+            int version = fService.getNextVersionID("main");
             assertEquals(recursiveContents("main:/d", version - 1, true),
                          recursiveContents("main:/d", version - 2, true));
             assertEquals(recursiveContents("main:/g", version - 1, true),
@@ -1483,7 +1483,7 @@ public class AVMServiceTest extends AVMServiceTestBase
             // History unchanged.
             checkHistory(history, "main");
             // /g should not have changed since its last version.
-            version = fService.getLatestVersionID("main");
+            version = fService.getNextVersionID("main");
             assertEquals(recursiveContents("main:/g", version - 1, true),
                          recursiveContents("main:/g", version - 2, true));
             // /layer/under/gover/h/i shows both moo and cow.
@@ -1569,7 +1569,7 @@ public class AVMServiceTest extends AVMServiceTestBase
             // History unchanged.
             checkHistory(history, "main");
             // /layer should not have changed.
-            int version = fService.getLatestVersionID("main");
+            int version = fService.getNextVersionID("main");
             assertEquals(recursiveContents("main:/layer", version - 1, true),
                          recursiveContents("main:/layer", version - 2, true));
             // Change something in /layer
@@ -1578,7 +1578,7 @@ public class AVMServiceTest extends AVMServiceTestBase
             // History unchanged.
             checkHistory(history, "main");
             // /branch should not have changed.
-            version = fService.getLatestVersionID("main");
+            version = fService.getNextVersionID("main");
             assertEquals(recursiveContents("main:/branch", version - 1, true),
                          recursiveContents("main:/branch", version - 2, true));
             // Create another layer on /a
@@ -1597,7 +1597,7 @@ public class AVMServiceTest extends AVMServiceTestBase
             // History unchanged.
             checkHistory(history, "main");
             // /layer2 should be unchanged.
-            version = fService.getLatestVersionID("main");
+            version = fService.getNextVersionID("main");
             assertEquals(recursiveContents("main:/layer2", version - 1, true),
                          recursiveContents("main:/layer2", version - 2, true));
             // Remove something from /layer2
@@ -1606,7 +1606,7 @@ public class AVMServiceTest extends AVMServiceTestBase
             // History unchanged.
             checkHistory(history, "main");
             // /branch2 is unchanged.
-            version = fService.getLatestVersionID("main");
+            version = fService.getNextVersionID("main");
             assertEquals(recursiveContents("main:/branch2", version - 1, true),
                          recursiveContents("main:/branch2", version - 2, true));
             // /a is unchanged.
@@ -2427,7 +2427,7 @@ public class AVMServiceTest extends AVMServiceTestBase
             // History unchanged.
             checkHistory(history, "main");
             // Confirm that /a and /d are unchanged.
-            int version = fService.getLatestVersionID("main");
+            int version = fService.getNextVersionID("main");
             assertEquals(recursiveContents("main:/a", version - 1, true),
                          recursiveContents("main:/a", version - 2, true));
             assertEquals(recursiveContents("main:/d", version - 1, true),
@@ -2436,7 +2436,7 @@ public class AVMServiceTest extends AVMServiceTestBase
             fService.rename("main:/dbranch", "f", "main:/abranch/c", "f");
             fService.createSnapshot("main", null, null);
             // Confirm that /a and /d are unchanged.
-            version = fService.getLatestVersionID("main");
+            version = fService.getNextVersionID("main");
             assertEquals(recursiveContents("main:/a", version - 1, true),
                          recursiveContents("main:/a", version - 2, true));
             assertEquals(recursiveContents("main:/d", version - 1, true),

source/java/org/alfresco/repo/avm/AVMServiceTestBase.java

@@ -19,7 +19,6 @@ package org.alfresco.repo.avm;
 
 import java.io.IOException;
 import java.io.PrintStream;
-import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 import java.util.TreeMap;
@@ -177,9 +176,7 @@ public class AVMServiceTestBase extends TestCase
         out.println("I am main:/a/b/c/bar");
         out.flush();
         out.close();
-        ArrayList<String> toSnapshot = new ArrayList<String>();
+        fService.createSnapshot("main", null, null);
-        toSnapshot.add("main");
-        fService.createSnapshot(toSnapshot);
     }
     
     /**
@@ -191,7 +188,7 @@ public class AVMServiceTestBase extends TestCase
         {
             assertEquals(history.get(i), recursiveList(repName, i, false));
         }
-        int latest = fService.getLatestVersionID(repName);
+        int latest = fService.getNextVersionID(repName);
         history.put(latest - 1, recursiveList(repName, -1, false));
     }
 }

source/java/org/alfresco/service/cmr/avm/AVMService.java

@@ -33,10 +33,12 @@ import org.alfresco.util.Pair;
 
 /**
  * This is the service interface for the [Alfresco|Addled|Advanced|Aleatoric|Apotheosed|Awful] 
- * Versioning Model.  It specifies methods that are close in functionality to the underlying
+ * Versioning Model. Paths are of the form storename:/foo/bar/baz. Since the AVM is
- * implementation, and is intended as both a first class Alfresco service and an
+ * a versioning repository all references to AVM nodes are via a version id (implied for write
- * aid in creating new implementations of existing services.
+ * operations) an a path.  The special version id -1 refers to the latest read write version of 
- * Paths are of the form storename:/foo/bar/baz.  
+ * a store.  All positive versions refer to read only snapshots of a store created
+ * explicitly by a call to createSnapshot() or implicitly by certain other calls
+ * in this interface or the AVMSyncService interface.  
  * @author britt
  */
 public interface AVMService
@@ -46,18 +48,16 @@ public interface AVMService
      * @param version The version id to look in.
      * @param path The simple absolute path to the file node.
      * @return An InputStream for the designated file.
-     * @throws AVMNotFoundException If <code>path</code> is not found.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal
+     * @throws AVMWrongTypeException
-     * component that is not a Directory of if it does not point at a file.
      */
     public InputStream getFileInputStream(int version, String path);
     
     /**
      * Get an output stream to a file node.  The file must already exist.
      * @param path The simple absolute path to the file node.
-     * @throws AVMNotFoundException If <code>path</code> is not found.
+     * @throws AVMNotFoundException    
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal
+     * @throws AVMWrongTypeException 
-     * component that is not a directory, or if it is not pointing to a file.
      */
     public OutputStream getFileOutputStream(String path);
     
@@ -66,6 +66,8 @@ public interface AVMService
      * @param version The version of the file.
      * @param path The path to the file.
      * @return A ContentReader.
+     * @throws AVMNotFoundException
+     * @throws AVMWrongTypeException
      */
     public ContentReader getContentReader(int version, String path);
     
@@ -73,6 +75,8 @@ public interface AVMService
      * Get a ContentWriter to a file node.
      * @param path The path to the file.
      * @return A ContentWriter.
+     * @throws AVMNotFoundException
+     * @throws AVMWrongTypeException
      */
     public ContentWriter createContentWriter(String path);   
     
@@ -81,10 +85,8 @@ public interface AVMService
      * @param version The version id to look in.
      * @param path The simple absolute path to the file node.
      * @return A Map of names to descriptors.
-     * @throws AVMNotFoundException If <code>path</code> is not found.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal
+     * @throws AVMWrongTypeException
-     * component that is not a directory, or if <code>path</code> is not pointing
-     * at a directory.
      */
     public SortedMap<String, AVMNodeDescriptor> getDirectoryListing(int version, String path);
 
@@ -95,10 +97,8 @@ public interface AVMService
      * @param path The simple absolute path to the file node.
      * @param includeDeleted Whether to see Deleted Nodes.
      * @return A Map of names to descriptors.
-     * @throws AVMNotFoundException If <code>path</code> is not found.
+     * @throws AVMNotFoundException 
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal
+     * @throws AVMWrongTypeException
-     * component that is not a directory, or if <code>path</code> is not pointing
-     * at a directory.
      */
     public SortedMap<String, AVMNodeDescriptor> getDirectoryListing(int version, String path,
                                                                     boolean includeDeleted);
@@ -110,9 +110,8 @@ public interface AVMService
      * @param version The version to look up.
      * @param path The full path to get listing for.
      * @return A Map of names to descriptors.
-     * @throws AVMNotFoundException If <code>path</code> does not exist.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeException If <code>path</code> contains any non-directory
+     * @throws AVMWrongTypeException 
-     * elements.
      */
     public SortedMap<String, AVMNodeDescriptor> 
         getDirectoryListingDirect(int version, String path);
@@ -126,9 +125,8 @@ public interface AVMService
      * @param path The full path to get listing for.
      * @param includeDeleted Whether to see Deleted Nodes.
      * @return A Map of names to descriptors.
-     * @throws AVMNotFoundException If <code>path</code> does not exist.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeException If <code>path</code> contains any non-directory
+     * @throws AVMWrongTypeException 
-     * elements.
      */
     public SortedMap<String, AVMNodeDescriptor>
         getDirectoryListingDirect(int version, String path, boolean includeDeleted);
@@ -139,6 +137,8 @@ public interface AVMService
      * @param path The path to the directory to be listed.
      * @param includeDeleted Whether to include ghosts.
      * @return An array of AVMNodeDescriptors.
+     * @throws AVMNotFoundException
+     * @throws AVMWrongTypeException
      */
     public AVMNodeDescriptor [] getDirectoryListingArray(int version, String path,
                                                          boolean includeDeleted);
@@ -148,6 +148,8 @@ public interface AVMService
      * @param dir The directory descriptor.
      * @param includeDeleted Whether to include deleted children.
      * @return A Map of Strings to descriptors.
+     * @throws AVMNotFoundException
+     * @throws AVMWrongTypeException
      */
     public SortedMap<String, AVMNodeDescriptor>
         getDirectoryListingDirect(AVMNodeDescriptor dir, boolean includeDeleted);
@@ -156,9 +158,8 @@ public interface AVMService
      * Get a directory listing from a node descriptor.
      * @param dir The directory node descriptor.
      * @return A Map of names to node descriptors.
-     * @throws AVMNotFoundException If the descriptor is stale.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeException If the descriptor does not point at
+     * @throws AVMWrongTypeException
-     * a directory.
      */
     public SortedMap<String, AVMNodeDescriptor> getDirectoryListing(AVMNodeDescriptor dir);
     
@@ -179,6 +180,8 @@ public interface AVMService
      * @param dir The descriptor pointing at the directory to list.
      * @param includeDeleted Whether to show ghosts.
      * @return An array of AVMNodeDescriptors.
+     * @throws AVMNotFoundException 
+     * @throws AVMWrongTypeException
      */
     public AVMNodeDescriptor [] getDirectoryListingArray(AVMNodeDescriptor dir,
                                                          boolean includeDeleted);
@@ -188,9 +191,8 @@ public interface AVMService
      * @param version The version to look under.
      * @param path The path of the directory.
      * @return A List of names.
-     * @throws AVMNotFoundException If <code>path</code> does not exist.
+     * @throws AVMNotFoundException 
-     * @throws AVMWrongTypeException If <code>path</code> contains any elements
+     * @throws AVMWrongTypeException 
-     * that are not directories.
      */
     public List<String> getDeleted(int version, String path);
     
@@ -198,10 +200,9 @@ public interface AVMService
      * Create a new File. Fails if the file already exists.
      * @param path The simple absolute path to the parent.
      * @param name The name to give the file.
-     * @throws AVMNotFound If <code>path</code> is non existent.
+     * @throws AVMNotFound 
-     * @throws AVMExists If <code>name</code> already exists.
+     * @throws AVMExists
-     * @throws AVMWrongType If some component of <code>path</code> is not
+     * @throws AVMWrongType
-     * a directory.
      */
     public OutputStream createFile(String path, String name);
     
@@ -211,21 +212,21 @@ public interface AVMService
      * @param path The path to the parent directory.
      * @param name The name for the new file. 
      * @param in An input stream with data for the file.
-     * @throws AVMNotFound If <code>path</code> is non existent.
+     * @throws AVMNotFound
-     * @throws AVMExists If <code>name</code> already exists.
+     * @throws AVMExists
-     * @throws AVMWrongType If some component of <code>path</code> is not
+     * @throws AVMWrongType
-     * a directory.
      */
     public void createFile(String path, String name, InputStream in);
     
     /**
-     * Create a new directory.
+     * Create a new directory. The new directory will be a plain 
+     * directory if it is created outside of a layer, it will be a 
+     * layered directory if created within a layer.
      * @param path The simple absolute path to the parent.
      * @param name The name to give the folder.
-     * @throws AVMNotFound If <code>path</code> is non existent.
+     * @throws AVMNotFound
-     * @throws AVMExists If <code>name</code> already exists.
+     * @throws AVMExists
-     * @throws AVMWrongType If some component of <code>path</code> is not
+     * @throws AVMWrongType
-     * a directory.
      */  
     public void createDirectory(String path, String name);
     
@@ -234,33 +235,31 @@ public interface AVMService
      * @param targetPath The simple absolute path that the new file will point at.
      * @param parent The simple absolute path to the parent.
      * @param name The name to give the new file.
-     * @throws AVMNotFound If <code>parent</code> is non existent.
+     * @throws AVMNotFound
-     * @throws AVMExists If <code>name</code> already exists.
+     * @throws AVMExists
-     * @throws AVMWrongType If some component of <code>parent</code> is not
+     * @throws AVMWrongType
-     * a directory.
      */
     public void createLayeredFile(String targetPath, String parent, String name);
     
     /**
-     * Create a new layered directory.
+     * Create a new layered directory. In whatever context this is created, this
+     * will be a layered directory that has a primary indirection.
      * @param targetPath The simple absolute path that the new folder will point at.
      * @param parent The simple absolute path to the parent.
      * @param name The name to give the new folder.
-     * @throws AVMNotFound If <code>parent</code> is non existent.
+     * @throws AVMNotFound
-     * @throws AVMExists If <code>name</code> already exists.
+     * @throws AVMExists
-     * @throws AVMWrongType If some component of <code>parent</code> is not
+     * @throws AVMWrongType
-     * a directory.
      */
     public void createLayeredDirectory(String targetPath, String parent, String name);
 
     /**
-     * Retarget a layered directory.
+     * Retarget a layered directory. Change the path that a layered directory points
+     * to.  This has the side effect of making the layered directory a primary indirection.
      * @param path Path to the layered directory.
      * @param target The new target to aim at.
-     * @throws AVMNotFoundException If <code>path</code> does not exist.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal
+     * @throws AVMWrongTypeException
-     * component that is not a directory or if it does not point at a retargetable 
-     * directory.
      */
     public void retargetLayeredDirectory(String path, String target);
     
@@ -268,54 +267,59 @@ public interface AVMService
      * Create a new AVMStore.  All AVMStores are top level in a hierarchical
      * sense.
      * @param name The name to give the AVMStore.
-     * @throws AVMExistsException If <code>name</code> is an already existing store.
+     * @throws AVMExistsException
      */
     public void createAVMStore(String name);
     
     /**
-     * Create a branch from a given version and path.
+     * Create a branch from a given version and path.  As a side effect 
+     * the store that contains the node that is being branched from is 
+     * automatically snapshotted.
      * @param version The version number from which to make the branch.
      * @param srcPath The path to the node to branch from.
      * @param dstPath The path to the directory to contain the 
      * new branch.
      * @param name The name to give the new branch.
-     * @throws AVMNotFoundException If either <code>srcPath</code> or
+     * @throws AVMNotFoundException
-     * <code>dstPath</code> does not exist.
+     * @throws AVMExistsException
-     * @throws AVMExistsException If <code>name</code> already exists.
+     * @throws AVMWrongTypeException
-     * @throws AVMWrongTypeException If <code>srcPath</code> or <code>dstPath</code>
-     * contains a non-terminal element that is not a directory.
      */
     public void createBranch(int version, String srcPath, String dstPath, String name);
     
     /**
-     * Remove a child from its parent.
+     * Remove a child from its parent. Caution this removes directories even
+     * if they are not empty.
      * @param parent The simple absolute path to the parent directory. 
      * @param name The name of the child to remove.
-     * @throws AVMNotFoundException If <code>parent</code> or <code>name</code>
+     * @throws AVMNotFoundException
-     * does not exist.
+     * @throws AVMWrongTypeException
-     * @throws AVMWrongTypeException If <code>parent</code> contains a non-terminal
-     * element that is not a directory.
      */
     public void removeNode(String parent, String name);
     
     /**
-     * Remove a node from by its full path.
+     * Remove a node by its full path. Sugar coating on removeNode(parent, name).
      * @param path The full path to the node to remove.
+     * @throws AVMNotFoundException
+     * @throws AVMWrongTypeException
      */
     public void removeNode(String path);
     
     /**
-     * Rename a node.
+     * Rename a node. There are a number of things to note about the
+     * interaction of rename and layering. If you rename a layered directory
+     * into a non layered context, the layered directory continues to point 
+     * to the same place it did before it was renamed and automatically becomes
+     * a primary indirection node.  If a plain directory is renamed into a layered
+     * context it remains a plain, thus acting as an opaque node in its new 
+     * layered home. Renaming a layered node into a layered node leaves the renamed 
+     * node pointing to the same place it did before the rename and makes it automatically
+     * a primary indirection node.
      * @param srcParent The simple absolute path to the parent folder.
      * @param srcName The name of the node in the src Folder.
      * @param dstParent The simple absolute path to the destination folder.
      * @param dstName The name that the node will have in the destination folder.
-     * @throws AVMNotFoundException If <code>srcParent</code>, 
+     * @throws AVMNotFoundException 
-     * <code>srcName</code>, or <code>dstParent</code> do not exist.
+     * @throws AVMExistsException 
-     * @throws AVMExistsException If <code>dstName</code> already exists.
-     * @throws AVMWrongTypeException If <code>srcParent</code> or
-     * <code>dstParent</code> contain non-terminal elements that are not directories
-     * or if either do not point at directories.
      */
     public void rename(String srcParent, String srcName, String dstParent, String dstName);
     
@@ -325,9 +329,8 @@ public interface AVMService
      * name from the deleted list.
      * @param dirPath The path to the layered directory.
      * @param name The name to uncover.
-     * @throws AVMNotFoundException If <code>dirPath</code> does not exist.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeExceptiont If <code>dirPath</code> contains a non-terminal
+     * @throws AVMWrongTypeException
-     * element that is not a directory.
      */
     public void uncover(String dirPath, String name);
 
@@ -336,22 +339,25 @@ public interface AVMService
      * removes the offending node from its layered directory parent's direct ownership.
      * @param dirPath The path to the layered directory.
      * @param name The name of the item to flatten.
+     * @throws AVMNotFoundException
+     * @throws AVMWrongTypeException
      */
     public void flatten(String dirPath, String name);
     
     /**
-     * Get the latest version id of the AVMStore.
+     * Gets the id that the next snapshotted version of a store 
+     * will have.
      * @param storeName The name of the AVMStore.
-     * @return The latest version id of the AVMStore.
+     * @return The next version id of the AVMStore.
-     * @throws AVMNotFoundException If <code>storeName</code> does not exist.
+     * @throws AVMNotFoundException
      */
-    public int getLatestVersionID(String storeName);
+    public int getNextVersionID(String storeName);
     
     /**
      * Get the latest snapshot id of a store. 
      * @param storeName The store name.
      * @return The id of the latest extant version of the store.
-     * @throws AVMNotFoundException If <code>storeName</code> does not exist.
+     * @throws AVMNotFoundException
      */
     public int getLatestSnapshotID(String storeName);
     
@@ -364,33 +370,37 @@ public interface AVMService
      * @return A List of the version ids of the newly created snapshots.
      * @throws AVMNotFoundException If any of the stores do not exist.
      */
-    public List<Integer> createSnapshot(List<String> stores);
+    // public List<Integer> createSnapshot(List<String> stores);
     
     /**
      * Snapshot the given AVMStore.
      * @param store The name of the AVMStore to snapshot.
      * @param tag The short description.
      * @param description The thick description.
-     * @throws AVMNotFoundException If <code>store</code> does not exist.
+     * @throws AVMNotFoundException
      */
     public int createSnapshot(String store, String tag, String description);
     
     /**
-     * Get the set of versions in an AVMStore
+     * Get the set of versions in an AVMStore. Since the number of version 
+     * that a store can contain can become large this call can be a resource
+     * pig to the point of causing Out of Memory exceptions.
      * @param name The name of the AVMStore.
-     * @return A Set of version IDs
+     * @return A Set of version descriptors.
-     * @throws AVMNotFoundException If <code>name</code> does not exist.
+     * @throws AVMNotFoundException
      */
     public List<VersionDescriptor> getAVMStoreVersions(String name);
     
     /**
      * Get AVMStore version descriptors by creation date. Either from or
-     * to can be null but not both.
+     * to can be null but not both.  If from is null then all versions before
+     * to will be returned.  If to is null then all versions later than from
+     * will be returned.
      * @param name The name of the AVMStore.
      * @param from Earliest date of version to include.
      * @param to Latest date of version to include.
-     * @return The Set of version IDs that match.
+     * @return The Set of version descriptors that match.
-     * @throws AVMNotFoundException If <code>name</code> does not exist.
+     * @throws AVMNotFoundException
      */
     public List<VersionDescriptor> getAVMStoreVersions(String name, Date from, Date to);
     
@@ -402,7 +412,8 @@ public interface AVMService
 
     /**
      * Get (and create if necessary) the system store. This store houses things
-     * like workflow packages.
+     * like workflow packages. The system store is intended to be a scratch store.
+     * It isn't used internally at this time but may be in the future.
      * @return The descriptor.
      */
     public AVMStoreDescriptor getAVMSystemStore();
@@ -410,8 +421,7 @@ public interface AVMService
     /**
      * Get a descriptor for an AVMStore.
      * @param name The AVMStore's name.
-     * @return A Descriptor.
+     * @return A Descriptor, or null if not foun.
-     * @throws AVMNotFoundException If <code>name</code> does not exist.
      */
     public AVMStoreDescriptor getAVMStore(String name);
     
@@ -420,8 +430,7 @@ public interface AVMService
      * @param version The version to look up.
      * @param name The name of the AVMStore.
      * @return A descriptor for the specified root.
-     * @throws AVMNotFoundException If <code>name</code> does not exist or
+     * @throws AVMNotFoundException
-     * if <code>version</code> does not exist.
      */
     public AVMNodeDescriptor getAVMStoreRoot(int version, String name);
         
@@ -429,11 +438,7 @@ public interface AVMService
      * Lookup a node by version ids and path.
      * @param version The version id to look under.
      * @param path The simple absolute path to the parent directory.
-     * @return An AVMNodeDescriptor.
+     * @return An AVMNodeDescriptor, or null if the node does not exist.
-     * @throws AVMNotFoundException If <code>path</code> does not exist or
-     * if <code>version</code> does not exist.
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal 
-     * element that is not a directory.
      */
     public AVMNodeDescriptor lookup(int version, String path);
     
@@ -443,9 +448,7 @@ public interface AVMService
      * @param version The version id to look under.
      * @param path The simple absolute path to the parent directory.
      * @param includeDeleted Whether to see Deleted Nodes.
-     * @return An AVMNodeDescriptor.
+     * @return An AVMNodeDescriptor, or null if the version does not exist.
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal 
-     * element that is not a directory.
      */
     public AVMNodeDescriptor lookup(int version, String path, boolean includeDeleted);
     
@@ -464,30 +467,37 @@ public interface AVMService
      * @param dir The descriptor for the directory node.
      * @param name The name to lookup.
      * @param includeDeleted Whether to see Deleted Nodes.
-     * @return The descriptor for the child.
+     * @return The descriptor for the child, null if the child doesn't exist.
-     * @throws AVMWrongTypeException If <code>dir</code> does not refer to a directory.
+     * @throws AVMNotFoundException
+     * @throws AVMWrongTypeException
      */
     public AVMNodeDescriptor lookup(AVMNodeDescriptor dir, String name, boolean includeDeleted);
     
     /**
-     * Get a list of all paths that a given node has.
+     * Get a list of all paths that a given node has.  This can be an expensive 
+     * operation.
      * @param desc The node descriptor to get paths for.
      * @return A List of version, path Pairs.
+     * @throws AVMNotFoundException
      */
     public List<Pair<Integer, String>> getPaths(AVMNodeDescriptor desc);
     
     /**
      * Get all paths that a given node has that are in the head version.
+     * This can be an expensive operation but less so than getPaths().
      * @param desc The node descriptor to get paths for.
      * @return A List of version, path Pairs.
+     * @throws AVMNotFoundException
      */
     public List<Pair<Integer, String>> getHeadPaths(AVMNodeDescriptor desc);
     
     /**
      * Get all paths to a node starting at the HEAD version of a store.
+     * This can be an expensive operation but less so than getHeadPaths().
      * @param desc The node descriptor.
      * @param store The store.
      * @return A List of all paths meeting the criteria.
+     * @throws AVMNotFoundException
      */
     public List<Pair<Integer, String>> getPathsInStoreHead(AVMNodeDescriptor desc, String store);
     
@@ -496,18 +506,15 @@ public interface AVMService
      * @param version The version number to get.
      * @param path The path to the node of interest.
      * @return The indirection path, or null if the path is not in a layered context.
-     * @throws AVMNotFoundException If <code>path</code> does not exist or
+     * @throws AVMNotFoundException
-     * if <code>version</code> does not exist.
+     * @throws AVMWrongTypeException
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal
-     * element that is not a directory or if it does not refer to a layered
-     * node.
      */
     public String getIndirectionPath(int version, String path);
     
     /**
      * Purge an AVMStore.  This is a complete wipe of an AVMStore.
      * @param name The name of the AVMStore.
-     * @throws AVMNotFoundException If <code>name</code> does not exist.
+     * @throws AVMNotFoundException 
      */
     public void purgeAVMStore(String name);
     
@@ -524,19 +531,17 @@ public interface AVMService
     /**
      * Make a directory into a primary indirection node.
      * @param path The full path.
-     * @throws AVMNotFoundException If <code>path</code> does not exist.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal
+     * @throws AVMWrongTypeException
-     * element that is not a directory or if it refers to a node that can't be made
-     * primary.
      */
     public void makePrimary(String path);
     
     /**
-     * Get a list of all the ancestor versions of a node.
+     * Get a list of up to count nodes in the history chain of a node.
-     * @param desc The version of a node to find ancestors for.
+     * @param desc The descriptor for a node to find ancestors for.
      * @param count How many. -1 means all.
      * @return A List of ancestors starting with the most recent.
-     * @throws AVMNotFoundException If <code>desc</code> is dangling.
+     * @throws AVMNotFoundException
      */
     public List<AVMNodeDescriptor> getHistory(AVMNodeDescriptor desc, int count);
     
@@ -544,10 +549,8 @@ public interface AVMService
      * Set the opacity of a layered directory.  An opaque layered directory
      * hides the contents of its indirection.
      * @param path The path to the layered directory.
-     * @throws AVMNotFoundException If <code>path</code> does not exist.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal
+     * @throws AVMWrongTypeException
-     * element that is not a directory or if it refers to a node that cannot have
-     * its opacity set.
      */
     public void setOpacity(String path, boolean opacity);
     
@@ -560,8 +563,7 @@ public interface AVMService
      * an ancestor of right.  Right returned means that right is strictly an
      * ancestor of left.  Any other non null return is the common ancestor and
      * indicates that left and right are in conflict.
-     * @throws AVMNotFoundException If <code>left</code> or <code>right</code>
+     * @throws AVMNotFoundException 
-     * do not exist.
      */
     public AVMNodeDescriptor getCommonAncestor(AVMNodeDescriptor left,
                                                AVMNodeDescriptor right);
@@ -571,10 +573,8 @@ public interface AVMService
      * @param version The version to look under.
      * @param path The full AVM path.
      * @return A LayeringDescriptor.
-     * @throws AVMNotFoundException If <code>path</code> or <code>version</code>
+     * @throws AVMNotFoundException
-     * do not exist.
+     * @throws AVMWrongTypeException
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal
-     * element that is not a directory.
      */
     public LayeringDescriptor getLayeringInfo(int version, String path);
     
@@ -583,9 +583,8 @@ public interface AVMService
      * @param path The path to the node to set the property on. 
      * @param name The QName of the property.
      * @param value The property to set.
-     * @throws AVMNotFoundException If <code>path</code> does not exist.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal
+     * @throws AVMWrongTypeException
-     * element that is not a directory.
      */
     public void setNodeProperty(String path, QName name, PropertyValue value);
     
@@ -593,9 +592,8 @@ public interface AVMService
      * Set a collection of properties on a node.
      * @param path The path to the node.
      * @param properties The Map of properties to set.
-     * @throws AVMNotFoundException If <code>path</code> does not exist.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal
+     * @throws AVMWrongTypeException
-     * element that is not a directory.
      */
     public void setNodeProperties(String path, Map<QName, PropertyValue> properties);
     
@@ -605,10 +603,8 @@ public interface AVMService
      * @param path The path to the node.
      * @param name The QName.
      * @return The PropertyValue or null if it doesn't exist.
-     * @throws AVMNotFoundException If <code>path</code> or <code>version</code>
+     * @throws AVMNotFoundException
-     * do not exist.
+     * @throws AVMWrongTypeException
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal
-     * element that is not a directory.
      */
     public PropertyValue getNodeProperty(int version, String path, QName name);
     
@@ -617,10 +613,7 @@ public interface AVMService
      * @param version The version to look under.
      * @param path The path to the node.
      * @return A Map of QNames to PropertyValues.
-     * @throws AVMNotFoundException If <code>path</code> or <code>version</code>
+     * @throws AVMNotFoundException
-     * do not exist.
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal
-     * element that is not a directory.
      */
     public Map<QName, PropertyValue> getNodeProperties(int version, String path);
     
@@ -628,15 +621,14 @@ public interface AVMService
      * Delete a property.
      * @param path The path to the node.
      * @param name The QName of the property to delete.
-     * @throws AVMNotFoundException If <code>path</code> does not exist.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeException If <code>path</code> contains a non-terminal
-     * element that is not a directory.
      */
     public void deleteNodeProperty(String path, QName name);
     
     /**
      * Delete all the properties attached to an AVM node.
      * @param path The path to the node.
+     * @throws AVMNotFoundException
      */
     public void deleteNodeProperties(String path);
     
@@ -645,8 +637,7 @@ public interface AVMService
      * @param store The store to set the property on.
      * @param name The name of the property.
      * @param value The value of the property.
-     * @throws AVMNotFoundException If <code>store</code>
+     * @throws AVMNotFoundException
-     * does not exist.
      */
     public void setStoreProperty(String store, QName name, PropertyValue value);
     
@@ -654,8 +645,7 @@ public interface AVMService
      * Set a group of properties on a store. Existing properties will be overwritten.
      * @param store The name of the store.
      * @param props A Map of the properties to set.
-     * @throws AVMNotFoundException If <code>store</code>
+     * @throws AVMNotFoundException
-     * does not exist.
      */
     public void setStoreProperties(String store, Map<QName, PropertyValue> props);
     
@@ -664,8 +654,7 @@ public interface AVMService
      * @param store The name of the store.
      * @param name The name of the property.
      * @return A PropertyValue or null if non-existent.
-     * @throws AVMNotFoundException If <code>store</code>
+     * @throws AVMNotFoundException
-     * does not exist.
      */
     public PropertyValue getStoreProperty(String store, QName name);
     
@@ -673,8 +662,7 @@ public interface AVMService
      * Get all the properties associated with a store.
      * @param store The name of the store.
      * @return A Map of the stores properties.
-     * @throws AVMNotFoundException If <code>store</code>
+     * @throws AVMNotFoundException
-     * does not exist.
      */
     public Map<QName, PropertyValue> getStoreProperties(String store);
 
@@ -699,29 +687,26 @@ public interface AVMService
      * Delete a property on a store by name.
      * @param store The name of the store.
      * @param name The name of the property to delete.
-     * @throws AVMNotFoundException If <code>store</code>
+     * @throws AVMNotFoundException
-     * does not exist.
      */
     public void deleteStoreProperty(String store, QName name);
     
     /**
-     * Get the ContentData for a node. Only applies to a file.
+     * Get the ContentData for a node in a read context. Only applies to a file.
      * @param version The version to look under.
      * @param path The path to the node.
      * @return The ContentData object.
-     * @throws AVMNotFoundException If <code>path</code> does not exist.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeException If <code>path</code> does not
+     * @throws AVMWrongTypeException
-     * point to a file.
      */
     public ContentData getContentDataForRead(int version, String path);
     
     /**
-     * Get the ContentData for a node.
+     * Get the ContentData for a node in a write context.
      * @param path The path to the node.
      * @return The ContentData object.
-     * @throws AVMNotFoundException If <code>path</code> does not exist.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeException If <code>path</code> does not point
+     * @throws AVMWrongTypeException
-     * to a file.
      */
     public ContentData getContentDataForWrite(String path);
     
@@ -729,9 +714,8 @@ public interface AVMService
      * Set the content data on a file. 
      * @param path The path to the file.
      * @param data The ContentData to set.
-     * @throws AVMNotFoundException If <code>path</code> does not exist.
+     * @throws AVMNotFoundException
-     * @throws AVMWrongTypeException If <code>path</code> does not point
+     * @throws AVMWrongTypeException
-     * to a file.
      */
     public void setContentData(String path, ContentData data);
     
@@ -739,6 +723,7 @@ public interface AVMService
      * Set all metadata on a node from another node. Aspects, properties, ACLs.
      * @param path The path to the node to set.
      * @param from The descriptor for the node to get metadata from.
+     * @throws AVMNotFoundException
      */
     public void setMetaDataFrom(String path, AVMNodeDescriptor from);
     
@@ -746,8 +731,8 @@ public interface AVMService
      * Add an aspect to an AVM node.
      * @param path The path to the node.
      * @param aspectName The QName of the aspect.
-     * @throws AVMNotFoundException If <code>path</code> does not exist.
+     * @throws AVMNotFoundException
-     * @throws AVMExistsException If the aspect already exists.
+     * @throws AVMExistsException
      */
     public void addAspect(String path, QName aspectName);
     
@@ -756,6 +741,7 @@ public interface AVMService
      * @param version The version to look under.
      * @param path The path to the node.
      * @return A List of the QNames of the aspects.
+     * @throws AVMNotFoundException   
      */
     public List<QName> getAspects(int version, String path);
     
@@ -763,6 +749,7 @@ public interface AVMService
      * Remove an aspect and its properties from a node.
      * @param path The path to the node.
      * @param aspectName The name of the aspect.
+     * @throws AVMNotFoundException
      */
     public void removeAspect(String path, QName aspectName);
     
@@ -772,30 +759,39 @@ public interface AVMService
      * @param path The path to the node.
      * @param aspectName The aspect name to check.
      * @return Whether the given node has the given aspect.
+     * @throws AVMNotFoundException
      */
     public boolean hasAspect(int version, String path, QName aspectName);
     
     /**
-     * This inserts a node into a parent directly.
+     * This inserts a node into a parent directly. This is not something
+     * one generally wants to do as the results are often not what you think.
+     * Used internally by the AVMSyncService.update() method. This may disappear
+     * from the public interface.
      * @param parentPath The path to the parent directory.
      * @param name The name to give the node.
      * @param toLink A descriptor for the node to insert.
+     * @throws AVMNotFoundException
      */
     public void link(String parentPath, String name, AVMNodeDescriptor toLink);
     
     /**
-     * Force copy on write of a path.
+     * Force copy on write of a path. Forces a copy on write event
+     * on the given node.  Not usually needed, and may disappear from the
+     * public interface.
      * @param path The path to force.
+     * @throws AVMNotFoundException
      */
     public AVMNodeDescriptor forceCopy(String path);
     
     /**
      * Copy (possibly recursively) the source into the destination
-     * directory.
+     * directory. This copies all node properties, acls, and aspects.
      * @param srcVersion The version of the source.
      * @param srcPath The path to the source.
      * @param dstPath The destination directory.
      * @param name The name to give the destination.
+     * @throws AVMNotFoundException
      */
     public void copy(int srcVersion, String srcPath, String dstPath, String name);
 }