* - * Because the AVM is a versioning repository, fully explicit - * references to the nodes within it consist of an absolute AVM path, - * and a version ID. Absolute AVM paths are of + * Because the AVM is a + * + * versioning repository, + * fully explicit references to the nodes within it consist of an + * absolute AVM path, and a version ID. Absolute AVM paths are of * the form: <store-name>:<store-relative-path>. *
* For example:
- * If instead, you wish to obtain a list of only
- * the deleted nodes within a directory, see:
- * {@link #getDeleted(int version, String path) getDeleted}.
- *
- * @param version The version ID to look in.
- * @param path The absolute AVM path to the file.
- * @param includeDeleted Whether to include deleted nodes
- * @return A Map of names to descriptors.
- * @throws AVMNotFoundException
- * @throws AVMWrongTypeException
- */
- public SortedMap
* The store name must be non-null, cannot be the empty string,
* and must not contain characters that are illegal in
@@ -513,18 +340,7 @@ public interface AVMService
* @throws AVMWrongTypeException
*/
public void removeNode(String parent, String name);
-
- /**
- * A convenience method that removes a node specified by an AVM path.
- * It merely parses an absolute path into a parent directory and a child
- * name, then calls {@link #removeNode(parent, name) removeNode}.
- *
- * @param path The full path to the node to remove.
- * @throws AVMNotFoundException
- * @throws AVMWrongTypeException
- */
- public void removeNode(String path);
/**
@@ -572,7 +388,7 @@ public interface AVMService
* @throws AVMExistsException
*/
public void rename(String srcParent, String srcName, String dstParent, String dstName);
-
+
/**
* If a layered directory
- * Note: paths that only access
- * For those concerned with records management applications,
- * it's worth noting that once every path to an asset has
- * been deleted, the system will purge it entirely in an
- * asynchronous manner.
- *
- * @param desc The node descriptor to get paths for.
- * @return A List of version, path Pairs.
- * @throws AVMNotFoundException
- */
- public List
+ * Note: to remove an apsect, see: {@link #removeAspect(String path, QName aspectName) removeAspect}
*
* @param path The path to the node.
* @param name The QName of the property to delete.
@@ -1050,6 +776,8 @@ public interface AVMService
/**
* Delete all the properties attached to an AVM node.
+ *
+ * Note: to remove an apsect, see: {@link #removeAspect(String path, QName aspectName) removeAspect}
*
* @param path The path to the node.
* @throws AVMNotFoundException
@@ -1084,7 +812,7 @@ public interface AVMService
* @throws AVMNotFoundException
*/
public PropertyValue getStoreProperty(String store, QName name);
-
+
/**
* Get all the properties associated with a store.
*
@@ -1103,18 +831,11 @@ public interface AVMService
*/
public Map
+ * Note: to remove an apsect, see: {@link #removeAspect(String path, QName aspectName) removeAspect}
*
* @param store The name of the store.
* @param name The name of the property to delete.
@@ -1123,60 +844,6 @@ public interface AVMService
public void deleteStoreProperty(String store, QName name);
- /**
- * Low-level internal function: 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
- * @throws AVMWrongTypeException
- */
- public ContentData getContentDataForRead(int version, String path);
-
- /**
- * Get ContentData using only a node descriptor.
- * @param desc The node descriptor.
- * @return The ContentData
- * @throws AVMNotFoundException
- */
- public ContentData getContentDataForRead(AVMNodeDescriptor desc);
-
-
- /**
- * Low-level internal function: Get the ContentData for
- * a node in a write context.
- *
- * @param path The path to the node.
- * @return The ContentData object.
- * @throws AVMNotFoundException
- * @throws AVMWrongTypeException
- */
- public ContentData getContentDataForWrite(String path);
-
-
- /**
- * Low-level internal function: Set the content data on a file.
- *
- * @param path The path to the file.
- * @param data The ContentData to set.
- * @throws AVMNotFoundException
- * @throws AVMWrongTypeException
- */
- public void setContentData(String path, ContentData data);
-
-
- /**
- * 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);
-
-
/**
* Add an aspect to an AVM node.
*
@@ -1186,7 +853,7 @@ public interface AVMService
* @throws AVMExistsException
*/
public void addAspect(String path, QName aspectName);
-
+
/**
* Get all the aspects on an AVM node.
*
@@ -1197,13 +864,7 @@ public interface AVMService
*/
public Set
+ * If instead, you wish to obtain a list of only
+ * the deleted nodes within a directory, see:
+ * {@link #getDeleted(int version, String path) getDeleted}.
+ *
+ * @param version The version ID to look in.
+ * @param path The absolute AVM path to the file.
+ * @param includeDeleted Whether to include deleted nodes
+ * @return A Map of names to descriptors.
+ * @throws AVMNotFoundException
+ * @throws AVMWrongTypeException
+ */
+ public SortedMap
+ * Note: paths that only access
+ * For those concerned with records management applications,
+ * it's worth noting that once every path to an asset has
+ * been deleted, the system will purge it entirely in an
+ * asynchronous manner.
*
- * @param sourceName The original name.
- * @param destName The new name.
- * @throws AVMNotFoundException
- * @throws AVMExistsException
+ * @param desc The node descriptor to get paths for.
+ * @return A List of version, path Pairs.
+ * @throws AVMNotFoundException
*/
- public void renameStore(String sourceName, String destName);
+ public List
+ *
+ * Because the AVM is a
+ *
+ * versioning repository,
+ * fully explicit references to the nodes within it consist of an
+ * absolute AVM path, and a version ID. Absolute AVM paths are of
+ * the form: <store-name>:<store-relative-path>.
+ *
+ * For example:
+ * Within AVMService, whenever an API takes a path
+ * and a name, the path is the parent
+ * directory in which the name appears.
+ * Whenever just a path is needed by an API, it is an absolute
+ * path to a file or directory.
+ *
+ * The special version ID
+ * Snapshots can be created explicitly via a call to
+ * {@link #createSnapshot(String store, String tag, String description) createSnapshot},
+ * or implicitly by various APIs in this interface and in
+ * {@link org.alfresco.service.cmr.avmsync.AVMSyncService AVMSyncService}.
+ * Although a new snapshot of a store will have version a ID one higher
+ * than the previous snapshot in that store, the history of an AMV store
+ * does not necessarily contain a continuous range of version ID values,
+ * because {@link #purgeVersion(int version, String name) purgeVersion}
+ * may have been called. Regardless of whether
+ * {@link #purgeVersion(int version, String name) purgeVersion}
+ * has been called, the AVM never recycles version ID values
+ * within a store.
+ *
* @author britt
*/
public interface AVMRemote
{
/**
- * Get an input handle. A handle is an opaque reference
- * to a server side input stream.
- * @param version The version to look under.
- * @param path The path to the file.
- * @return An InputStream.
+ * Get an InputStream for reading the contents of a
+ * file identified by its version ID and AVM path.
+ * This method can be used for either plain or layered files.
+ *
+ * @param version The version ID to look in.
+ * @param path The absolute path to the file.
+ * @return An InputStream for the designated file.
+ * @throws AVMNotFoundException
+ * @throws AVMWrongTypeException
*/
public InputStream getFileInputStream(int version, String path);
/**
- * Get an InputStream from a descriptor directly.
+ * Get an InputStream for reading the contents of a
+ * file node identified by its descriptor.
+ * This method can be used for either plain or layered files.
+ *
* @param desc The descriptor.
* @return An InputStream.
+ * @throws AVMNotFoundException
*/
public InputStream getFileInputStream(AVMNodeDescriptor desc);
/**
- * Get an opaque handle to a server side output stream.
- * @param path The path to the existing file.
- * @return An opaque handle.
+ * Get an output stream to write to a file
+ * identified by an AVM path. This file must already exist.
+ * This method can be used for either plain or layered files.
+ *
+ * To create a plain file, see:
+ * {@link #createFile(String path, String name) createFile}.
+ * To create a layered file, see:
+ * {@link #createLayeredFile(String targetPath, String parent, String name) createLayeredFile}.
+ *
+ * @param path The absolute path to the file.
+ * @throws AVMNotFoundException
+ * @throws AVMWrongTypeException
*/
public OutputStream getFileOutputStream(String path);
+
+
+ /**
+ * Get a non-recursive listing of a directory
+ * identified by its version ID and path.
+ * If
+ * If this function is called on a "plain" (non-layered) directory,
+ * it is equivalent to
+ * {@link #getDirectoryListing(int version, String path) getDirectoryListing}.
+ *
+ * @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
+ * @throws AVMWrongTypeException
*/
public SortedMap
+ * Note: the target of the indirection does not need to exist at
+ * the time the layered file node is created.
+ *
+ * @param targetPath The absolute path of the underlying file being pointed at
+ * @param parent The absolute path of the directory containing layered file to be created
+ * @param name The name of the layered file to be created
+ * @throws AVMNotFound
+ * @throws AVMExists
+ * @throws AVMWrongType
*/
public void createLayeredFile(String targetPath, String parent, String name);
+
/**
- * Create a layered directory.
- * @param targetPath The path that is targeted.
- * @param parent The parent directory.
- * @param name The name of the new directory.
+ * Create a new layered directory. In whatever context this is created, this
+ * will be a layered directory that has a primary indirection.
+ *
+ * Note: a "primary" indirection is one in which the target is explicitly set;
+ * "non-primary" indirect nodes compute their effective target dynamically
+ * on the basis of their relative position to the closest "primary"
+ * indirect node that contains them. Therefore, changing the target of a
+ * "primary" layered directory node immediately alters the indirection
+ * targets computed by the "non-primary" layered nodes it contains.
+ *
+ * Note: the target of the indirection does not need to exist at
+ * the time the layered directory node is created.
+ *
+ * @param targetPath The absolute path to the underlying directory that
+ * the layered directory being created will point at.
+ * @param parent The absolute path to directory containing the layered directory being created.
+ * @param name The name of the layered directory being created
+ * @throws AVMNotFound
+ * @throws AVMExists
+ * @throws AVMWrongType
*/
public void createLayeredDirectory(String targetPath, String parent, String name);
-
+
+
/**
- * Set a layered directory node to point at a different target.
- * @param path The path to the layered directory node.
- * @param target The new target.
+ * Retarget a layered directory.
+ * Change the target pointed to by a layered directory node.
+ * This has the side effect of making the layered directory
+ * a primary indirection if the layered directory's indirection
+ * was "non-primary".
+ *
+ * @param path Path to the layered directory.
+ * @param target The new indirection target of the layered directory
+ * @throws AVMNotFoundException
+ * @throws AVMWrongTypeException
*/
public void retargetLayeredDirectory(String path, String target);
+
/**
- * Create a new AVMStore.
- * @param name The name to give the new store.
+ * Create a new AVMStore.
+ * All stores are top level objects within the AVM repository.
+ * The AVM is a forest of versioned trees; each versioned
+ * tree is contained within a AVM store with a unique
+ * name. If a store is removed via
+ * {@link purgeStore(String name) purgeStore}, the name of
+ * the deleted store can be reused in a later call to
+ * {@link createStore(String name) createStore}.
+ *
+ * The store name must be non-null, cannot be the empty string,
+ * and must not contain characters that are illegal in
+ * normal file names.
+ *
+ * @param name The name of the new AVMStore.
+ * @throws AVMExistsException
*/
public void createStore(String name);
+
/**
- * Create a new branch.
- * @param version The version to look under for the source node.
- * @param srcPath The path to the source node.
- * @param dstPath The path to the destination directory.
- * @param name The name of the new branch.
+ * Create a branch from a given version and path. As a side effect,
+ * an automatic snapshot is taken of the store that contains the
+ * node that is being branched from.
+ *
+ * @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
+ * @throws AVMExistsException
+ * @throws AVMWrongTypeException
*/
public void createBranch(int version, String srcPath, String dstPath, String name);
+
/**
- * Remove a node.
- * @param parent The path to the parent directory.
- * @param name The name of the node to remove.
+ * Remove a file or directory from its parent directory.
+ * In a layered context, the newly deleted node will hide
+ * a file of the same name in the corresponding layer below.
+ *
+ * If instead you want to make the file in the lower layer visible
+ * via transparency, see:
+ * {@link uncover(String dirPath, String name) uncover}.
+ * If you want to perform a removal and an uncover
+ * operation atomically, see:
+ * {@link #makeTransparent(String dirPath, String name) makeTransparent}.
+ *
+ *
+ *
+ * Caution: this removes directories even if they are not empty.
+ *
+ *
+ * Note: developers of records management systems must also
+ * be aware that the AVMNode corresponding to the
+ *
+ *
+ *
+ * Note: if instead you want to rename an AVM store, see
+ * {@link #renameStore(String sourceName, String destName) renameStore}.
+ *
+ * @param srcParent The absolute path to the parent directory.
+ * @param srcName The name of the node in the src directory.
+ * @param dstParent The absolute path to the destination directory.
+ * @param dstName The name that the node will have in the destination directory.
+ * @throws AVMNotFoundException
+ * @throws AVMExistsException
*/
public void rename(String srcParent, String srcName, String dstParent, String dstName);
+
/**
- * Uncover a name in a layered directory.
- * @param dirPath The path to the directory.
- * @param name The name to uncover.
+ * If a layered directory
+ * Note: if you are looking for an atomic operation
+ * that first deletes an object, then performs
+ * an "uncover" operation to make it transparent, see
+ * {@link #makeTransparent(String dirPath, String name) makeTransparent}.
+ *
+ * @param dirPath The path to the layered directory.
+ * @param name The name to uncover.
+ * @throws AVMNotFoundException
+ * @throws AVMWrongTypeException
*/
public void uncover(String dirPath, String name);
+
/**
- * Get the next version id of the given AVMStore.
+ * Gets the ID that the next snapshotted version of a store
+ * will have.
+ *
+ *
+ * Note: unless the operations that require this value
+ * to be valid are performed within a transaction,
+ * this value can become "stale".
+ *
* @param storeName The name of the AVMStore.
- * @return The latest version id.
+ * @return The next version ID of the AVMStore.
+ * @throws AVMNotFoundException
*/
public int getNextVersionID(String storeName);
+
/**
- * Get the id of the latest extant snpashot.
- * @param storeName The name of the store.
- * @return The id.
+ * Get the latest snapshot ID of a store.
+ * Note: All stores have at least one snapshot ID: 0;
+ * this is the "empty" snapshot taken when
+ * the store is first created.
+ *
+ * @param storeName The store name.
+ * @return The ID of the latest extant version of the store.
+ * @throws AVMNotFoundException
*/
public int getLatestSnapshotID(String storeName);
+
/**
- * Snapshot an AVMStore.
+ * Snapshot the given AVMStore.
+ * When files have been modified since the previous snapshot,
+ * a new snapshot version is created; otherwise, no extra
+ * snapshot is actually taken.
+ *
+ * When no snapshot is actually taken, but either 'tag'
+ * or 'store' are non-null, they will override the value for
+ * the last snapshot (i.e.: the old values will be discarded);
+ * however, if both 'tag' and 'description' are null then
+ * invoking createSnapshot when no files have been modified
+ * becomes a true no-op.
+ *
* @param store The name of the AVMStore to snapshot.
- * @return The map of implicitely and explicitely snapshotted stores.
+ * @param tag The short description.
+ * @param description The thick description.
+ * @return A Map of all implicitly or explicitly snapshotted stores to last
+ * version id.
+ * @throws AVMNotFoundException
*/
- public Map
+ *
+ *
+ * The order of the values returned is not guaranteed, nor are the version
+ * IDs necessarily free of "missing" values (due to the possibility that
+ * {@link #purgeStore(String name) purgeStore} operations have
+ * been performed).
+ *
+ *
+ * Note: for portability, all dates are stored as 64-bit longs, with a
+ * time resolution of one millisecond. Therefore, aliasing/wrapping
+ * are not a concern unless you need to plan 292.4 million years ahead.
+ * If so, please contact your system administrator.
+ *
+ * @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 descriptors that match.
+ * @throws AVMNotFoundException
*/
public List
+ * For example, if "mysite--alice:/www" is a layered
+ * directory that targets "mysite:/www", and "mysite--alice"
+ * contains no content directly, then if the path
+ * path "mysite:/www/avm_webapps/ROOT/x/y/z" is valid,
+ * calling
+ * Note: while the store being purged disappears from view
+ * immediately, any nodes that become unreachable as a result
+ * are deleted asynchronously.
+ *
+ * @param name The name of the AVMStore.
+ * @throws AVMNotFoundException
*/
public void purgeStore(String name);
/**
- * Purge a given version from a given store.
- * @param version The version id.
- * @param name The name of the store.
+ * Purge a version from an AVMStore.
+ * Deletes everything that lives in the given version only.
+ *
+ * @param version The version to purge.
+ * @param name The name of the AVMStore from which to purge it.
+ * @throws AVMNotFoundException If
+ * Note: to remove an apsect, see: {@link #removeAspect(String path, QName aspectName) removeAspect}
+ *
* @param path The path to the node.
- * @param name The name of the property.
+ * @param name The QName of the property to delete.
+ * @throws AVMNotFoundException
*/
public void deleteNodeProperty(String path, QName name);
/**
- * Delete all properties from a node.
+ * Delete all the properties attached to an AVM node.
+ *
+ * Note: to remove an apsect, see: {@link #removeAspect(String path, QName aspectName) removeAspect}
+ *
* @param path The path to the node.
+ * @throws AVMNotFoundException
*/
public void deleteNodeProperties(String path);
/**
- * Set a property on a store.
- * @param store The name of the store.
- * @param name The name of the property to set.
- * @param value The value of the property to set.
+ * Set a property on a store. If the property exists it will be overwritten.
+ *
+ * @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
*/
public void setStoreProperty(String store, QName name, PropertyValue value);
/**
- * Set a group of properties on a store.
+ * 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 QNames to PropertyValues to set.
+ * @param props A Map of the properties to set.
+ * @throws AVMNotFoundException
*/
public void setStoreProperties(String store, Map
+ * Note: to remove an apsect, see: {@link #removeAspect(String path, QName aspectName) removeAspect}
+ *
* @param store The name of the store.
- * @param name The name of the property.
+ * @param name The name of the property to delete.
+ * @throws AVMNotFoundException
*/
public void deleteStoreProperty(String store, QName name);
- /**
- * Rename a store.
- * @param sourceName The original name.
- * @param destName The new name.
- */
- public void renameStore(String sourceName, String destName);
/**
* Add an aspect to an AVM node.
- * @param path The path to the node.
+ *
+ * @param path The path to the node.
* @param aspectName The QName of the aspect.
- * @throws AVMNotFoundException
- * @throws AVMExistsException
+ * @throws AVMNotFoundException
+ * @throws AVMExistsException
*/
public void addAspect(String path, QName aspectName);
-
+
/**
* Get all the aspects on an AVM node.
+ *
* @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
+ * @param path The path to the node.
+ * @return A Set of the QNames of the aspects.
+ * @throws AVMNotFoundException
*/
public Setmystore:/www/avm_webapps/ROOT/x/y/z.html
@@ -70,11 +74,13 @@ import org.alfresco.util.Pair;
* {@link #createSnapshot(String store, String tag, String description) createSnapshot},
* or implicitly by various APIs in this interface and in
* {@link org.alfresco.service.cmr.avmsync.AVMSyncService AVMSyncService}.
- * While a new snapshot of a store will have version a ID one higher
+ * Although a new snapshot of a store will have version a ID one higher
* than the previous snapshot in that store, the history of an AMV store
* does not necessarily contain a continuous range of version ID values,
* because {@link #purgeVersion(int version, String name) purgeVersion}
- * may have been called. However, version ID values are never recycled
+ * may have been called. Regardless of whether
+ * {@link #purgeVersion(int version, String name) purgeVersion}
+ * has been called, the AVM never recycles version ID values
* within a store.
*
* @author britt
@@ -105,7 +111,6 @@ public interface AVMService
*/
public InputStream getFileInputStream(AVMNodeDescriptor desc);
-
/**
* Get an output stream to write to a file
* identified by an AVM path. This file must already exist.
@@ -121,34 +126,6 @@ public interface AVMService
* @throws AVMWrongTypeException
*/
public OutputStream getFileOutputStream(String path);
-
-
- /**
- * Low-level internal function: Fetch a content reader for a file node.
- *
- * This function is similar to
- * {@link getFileInputStream(int version, String path) getFileInputStream};
- * however, it can be used to fetch either InputStream or a
- * random-access nio channel.
- *
- * @param version The version ID of the file.
- * @param path The absolute AVM path to the file.
- * @return A ContentReader.
- * @throws AVMNotFoundException
- * @throws AVMWrongTypeException
- */
- public ContentReader getContentReader(int version, String path);
-
-
- /**
- * Low-level internal function: Fetch a ContentWriter to a file node.
- *
- * @param path The path to the file.
- * @return A ContentWriter.
- * @throws AVMNotFoundException
- * @throws AVMWrongTypeException
- */
- public ContentWriter getContentWriter(String path);
/**
@@ -164,26 +141,6 @@ public interface AVMService
* @throws AVMWrongTypeException
*/
public SortedMappath must already exist.
- *
- * @param path The path of the directory containing the created file.
- * @param name The name of the new file
- * @param in An input stream with data for the file.
- * @throws AVMNotFound
- * @throws AVMExists
- * @throws AVMWrongType
- */
- public void createFile(String path, String name, InputStream in);
-
-
- /**
- * Create a new "plain" (non-layered) file.
- * Guarantees that the entire contents of the
- * input stream will be loaded atomically.
- * The directory identified by path must already exist.
- *
- * @param path The path of the directory containing the created file.
- * @param name The name of the new file
- * @param in An input stream with data for the file.
- * @param aspect A list of aspects to give the file.
- * @param properties A map of properties to give the file.
- * @throws AVMNotFound
- * @throws AVMExists
- * @throws AVMWrongType
- */
- public void createFile(String path, String name, InputStream in, Listpath is within a layer, the new directory will be a layered directory;
@@ -369,21 +211,6 @@ public interface AVMService
* @throws AVMWrongType
*/
public void createDirectory(String path, String name);
-
- /**
- * Create a new directory.
- * If path is within a layer, the new directory will be a layered directory;
- * otherwise, the new directory will be a plain directory.
- *
- * @param path The simple absolute path to the parent.
- * @param name The name to give the directory.
- * @param aspects A list of aspects to add.
- * @param properties A Map of properties to add.
- * @throws AVMNotFound
- * @throws AVMExists
- * @throws AVMWrongType
- */
- public void createDirectory(String path, String name, ListdirPath
@@ -595,24 +411,6 @@ public interface AVMService
public void uncover(String dirPath, String name);
- /**
- * Atomically delete name within dirPath
- * and {@link uncover(String dirPath, String name) uncover}
- * it so whatever is underneath can be seen via transparency.
- * If name corresponds to a deletion already,
- * then the deletion step is skipped, and the "uncover"
- * operation is performed.
- *
- * @param dirPath The path to the layered directory.
- * @param name The name of the item this method will
- * {@link org.alfresco.service.cmr.avmsync.AVMSyncService#flatten(String layerPath, String underlyingPath) flatten}
- *
- * @throws AVMNotFoundException
- * @throws AVMWrongTypeException
- */
- public void makeTransparent(String dirPath, String name);
-
-
/**
* Gets the ID that the next snapshotted version of a store
* will have.
@@ -627,7 +425,7 @@ public interface AVMService
* @throws AVMNotFoundException
*/
public int getNextVersionID(String storeName);
-
+
/**
* Get the latest snapshot ID of a store.
@@ -725,18 +523,6 @@ public interface AVMService
* @return A List of all AVMStores.
*/
public Listdir does not refer to a directory.
*/
public AVMNodeDescriptor lookup(AVMNodeDescriptor dir, String name);
-
+
+
/**
* Lookup a node identified by the directory that contains it, and its name;
* optionally, the lookup can retrive the descriptor of a node even if
@@ -803,73 +590,16 @@ public interface AVMService
* @throws AVMWrongTypeException
*/
public AVMNodeDescriptor lookup(AVMNodeDescriptor dir, String name, boolean includeDeleted);
-
-
- /**
- * Get a list of all paths that a given node has.
- * This can be an extremely expensive operation due to the large number
- * of paths to an AVMNodeDescriptor that can be generated
- * via branching and versioning. For example, if an asset
- * is present in the initial version of a store, and
- * that store has been versioned 10,000 times,
- * there are a minimum of 10,000 paths that lead to it.
- * The effect of branching is multiplicative.
- * desc
- * via transparency are not returned by this function;
- * only "direct" containment relationships are considered.
- * HEAD version ( -1 ).
- * 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 ListHEAD version ( -1 )
- * 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 ListHEAD path to a given version.
+ * This works by cloning the version to revert to, and then linking
+ * that new version into HEAD.
+ * The reverted version will have the previous
+ * HEAD version as ancestor.
+ *
+ * @param path The path to the node to revert.
+ * @param toRevertTo The descriptor of the version to revert to.
+ * @throws AVMNotFoundException
+ */
+ public void revert(String path, AVMNodeDescriptor toRevertTo);
+
+
+ /**
+ * Set the GUID on a node. The GUID of a node uniquely identifies
+ * the state of a node, i.e. its content, metadata, and aspects.
+ * @param path The path to the node.
+ * @param guid The GUID to set.
+ */
+ public void setGuid(String path, String guid);
+
+ /**
+ * Set the mime type.
+ * @param path The path of the file.
+ * @param mimeType The mime type.
+ */
+ public void setMimeType(String path, String mimeType);
+
+ /**
+ * Set the encoding.
+ * @param path The path of the file.
+ * @param encoding The encoding.
+ */
+ public void setEncoding(String path, String encoding);
+
+ /**
+ * Queries all AVM stores for properties with keys that match a given pattern.
+ *
+ * @param keyPattern The sql 'like' pattern, inserted into a QName.
+ * @return A Map of store names to Maps of property key value pairs that match
+ * the pattern.
+ */
+ public Mappath is within a layer, the new directory will be a layered directory;
+ * otherwise, the new directory will be a plain directory.
+ *
+ * @param path The simple absolute path to the parent.
+ * @param name The name to give the directory.
+ * @param aspects A list of aspects to add.
+ * @param properties A Map of properties to add.
+ * @throws AVMNotFound
+ * @throws AVMExists
+ * @throws AVMWrongType
+ */
+
+ public void createDirectory(String path, String name, Listpath must already exist.
+ *
+ * @param path The path of the directory containing the created file.
+ * @param name The name of the new file
+ * @param in An input stream with data for the file.
+ * @throws AVMNotFound
+ * @throws AVMExists
+ * @throws AVMWrongType
+ */
+ public void createFile(String path, String name, InputStream in);
+
+
+ /**
+ * Create a new "plain" (non-layered) file with aspects and properties.
+ * Guarantees that the entire contents of the
+ * input stream will be loaded atomically.
+ * The directory identified by path must already exist.
+ *
+ * @param path The path of the directory containing the created file.
+ * @param name The name of the new file
+ * @param in An input stream with data for the file.
+ * @param aspect A list of aspects to give the file.
+ * @param properties A map of properties to give the file.
+ * @throws AVMNotFound
+ * @throws AVMExists
+ * @throws AVMWrongType
+ */
+ public void createFile(String path, String name, InputStream in, Listname within dirPath
+ * and {@link uncover(String dirPath, String name) uncover}
+ * it so whatever is underneath can be seen via transparency.
+ * If name corresponds to a deletion already,
+ * then the deletion step is skipped, and the "uncover"
+ * operation is performed.
+ *
+ * @param dirPath The path to the layered directory.
+ * @param name The name of the item this method will
+ * {@link org.alfresco.service.cmr.avmsync.AVMSyncService#flatten(String layerPath, String underlyingPath) flatten}
+ *
+ * @throws AVMNotFoundException
+ * @throws AVMWrongTypeException
+ */
+ public void makeTransparent(String dirPath, String name);
+
+ /**
+ * Low-level internal function:
+ * Retrieve the reserved "system" store.
+ * This method isn't currently used,
+ * but may be in some future release.
+ *
+ * @return The descriptor.
+ */
+ public AVMStoreDescriptor getSystemStore();
+
+ /**
+ * 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);
+
/**
* Low-level internal function: Insert a node
* into a parent directly. Caution: this is not something
@@ -1265,47 +1183,151 @@ public interface AVMService
/**
- * Rename a store.
+ * Get a list of all paths that a given node has.
+ * This can be an extremely expensive operation due to the large number
+ * of paths to an AVMNodeDescriptor that can be generated
+ * via branching and versioning. For example, if an asset
+ * is present in the initial version of a store, and
+ * that store has been versioned 10,000 times,
+ * there are a minimum of 10,000 paths that lead to it.
+ * The effect of branching is multiplicative.
+ * desc
+ * via transparency are not returned by this function;
+ * only "direct" containment relationships are considered.
+ * HEAD path to a given version.
- * This works by cloning the version to revert to, and then linking
- * that new version into HEAD.
- * The reverted version will have the previous
- * HEAD version as ancestor.
+ * Get all paths that a given node has that are in the
+ * HEAD version ( -1 ).
+ * This can be an expensive operation but less so than getPaths().
*
- * @param path The path to the node to revert.
- * @param toRevertTo The descriptor of the version to revert to.
- * @throws AVMNotFoundException
+ * @param desc The node descriptor to get paths for.
+ * @return A List of version, path Pairs.
+ * @throws AVMNotFoundException
*/
- public void revert(String path, AVMNodeDescriptor toRevertTo);
+ public ListHEAD version ( -1 )
+ * 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
+ * For the in-process API, see:
+ * {@link org.alfresco.service.cmr.avm.AVMService AVMService}.
+ * mystore:/www/avm_webapps/ROOT/x/y/z.html
+ * -1 (negative one)
+ * refers to the latest read/write version at the given absolute AVM path.
+ * Non-negative version ID values refer to read-only snapshots of a store.
+ * For this reason, the version ID -1
+ * is implicit for all write operations. Sometimes,
+ * -1 is referred to as the
+ * HEAD version (a term that should be
+ * already be familiar to users of other versioning systems like
+ * CVS
+ * and SVN).
+ * path does not refer to a directory
+ * node, AVMWrongTypeException is thrown.
+ *
+ * @param version The version ID to look in.
+ * @param path The absolute AVM path to the file.
+ * @return A Map of names to descriptors.
+ * @throws AVMNotFoundException
+ * @throws AVMWrongTypeException
+ */
+ public SortedMappath
+ * does not exist.
+ *
+ * @param path The path of the directory containing the created file.
+ * @param name The name of the new file
+ * @throws AVMNotFound
+ * @throws AVMExists
+ * @throws AVMWrongType
* @return An opaque handle to a server side output stream.
*/
public OutputStream createFile(String path, String name);
/**
- * Create a directory.
- * @param path The path to the containing directory.
- * @param name The name for the new directory.
- */
+ * Create a new directory.
+ * If path is within a layer, the new directory will be a layered directory;
+ * otherwise, the new directory will be a plain directory.
+ *
+ * @param path The simple absolute path to the parent.
+ * @param name The name to give the directory.
+ * @throws AVMNotFound
+ * @throws AVMExists
+ * @throws AVMWrongType
+ */
public void createDirectory(String path, String name);
-
+
/**
- * Create a new layered file.
- * @param targetPath The path that is targeted.
- * @param parent The path to the parent directory.
- * @param name The name for the new file.
+ * Create a new layered file.
+ * parent directory and name
+ * provided might still be accessible via different
+ * path lookups after this function has completed;
+ * this because branching and versioning operations create
+ * manifestations of nodes in a manner that is similar
+ * to a UNIX hard link. If you need to discover every
+ * possible path that could retrieve the associated AVMNode, see:
+ * {@link #getPaths(AVMNodeDescriptor desc) getPaths},
+ * {@link #getHeadPaths(AVMNodeDescriptor desc) getHeadPaths}, and
+ * {@link #getPathsInStoreHead(AVMNodeDescriptor desc) getPathsInStoreHead}.
+ *
+ * @param parent The absolute path to the parent directory.
+ * @param name The name of the child to remove.
+ * @throws AVMNotFoundException
+ * @throws AVMWrongTypeException
*/
public void removeNode(String parent, String name);
+
+
/**
- * Rename a node.
- * @param srcParent The source directory path.
- * @param srcName The source node name.
- * @param dstParent The destination directory path.
- * @param dstName The destination name for the node.
+ * Rename a file or directory.
+ * There are a number of things to note about the
+ * interaction of rename and layering:
+ *
+ *
+ * dirPath
+ * has a deleted entry of the given name,
+ * remove that name from the deleted list,
+ * so that if a layer below it contains an entry
+ * of this name, it can be seen via transparency
+ * from dirPath.
+ * from or to can be null but not both.
+ *
+ *
+ * from is null, all versions earlier than
+ * to will be returned.
+ * to is null, all versions later than
+ * from will be returned.
+ * "mysite:/").
+ *
+ * @param version The version to look up.
+ * @param name The name of the AVMStore.
+ * @return A descriptor for the specified root.
+ * @throws AVMNotFoundException
*/
public AVMNodeDescriptor getStoreRoot(int version, String name);
-
+
+
/**
- * Get a descriptor for the specified node.
- * @param version The version to look under.
- * @param path The path to the node.
- * @return An AVMNodeDescriptor.
+ * Lookup a node identified by version ID and path.
+ *
+ * @param version The version ID to look under.
+ * @param path The simple absolute path to the parent directory.
+ * @return An AVMNodeDescriptor, or null if the node does not exist.
*/
public AVMNodeDescriptor lookup(int version, String path);
@@ -259,13 +571,16 @@ public interface AVMRemote
public AVMNodeDescriptor lookup(int version, String path, boolean includeDeleted);
/**
- * Get a descriptor for the specified node.
- * @param dir The descriptor for the directory node.
- * @param name The name of the node to lookup.
- * @return An AVMNodeDescriptor.
+ * Lookup a node identified by the directory node that contains it, and its name.
+ *
+ * @param dir The descriptor for the directory node.
+ * @param name The name to lookup.
+ * @return The descriptor for the child.
+ * @throws AVMWrongTypeException If dir does not refer to a directory.
*/
public AVMNodeDescriptor lookup(AVMNodeDescriptor dir, String name);
+
/**
* Lookup a node identified by the directory that contains it, and its name;
* optionally, the lookup can retrive the descriptor of a node even if
@@ -279,227 +594,341 @@ public interface AVMRemote
* @throws AVMWrongTypeException
*/
public AVMNodeDescriptor lookup(AVMNodeDescriptor dir, String name, boolean includeDeleted);
-
+
/**
- * Get the indirection path for a node.
- * @param version The version to look under.
- * @param path The path to the node.
- * @return The indirection path/target.
+ * Get a single valid path to a given node.
+ * @param desc The descriptor of the node to which a version and path will be fetched.
+ * @return version and path.
+ * @throws AVMNotFoundException
+ */
+ public PairgetIndirectionPath on
+ * "mysite--alice:/www/avm_webapps/ROOT/x/y/z" will yield
+ * "mysite:/www/avm_webapps/ROOT/x/y/z".
+ *
+ * @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
+ * @throws AVMWrongTypeException
*/
public String getIndirectionPath(int version, String path);
-
+
+
/**
- * Purge an AVMStore.
- * @param name The name of the store to purge.
+ * Purge an AVMStore.
+ * This completely removes an AVMStore.
+ * name or version
+ * do not exist.
*/
public void purgeVersion(int version, String name);
+
/**
- * Turn a directory into a primary indirection node.
- * @param path The path to the directory.
+ * Make a directory into a primary indirection node.
+ * @param path The full path.
+ * @throws AVMNotFoundException
+ * @throws AVMWrongTypeException
*/
public void makePrimary(String path);
+
/**
- * Get a list of ancestors of a node.
- * @param desc The descriptor of the node whose history is to be fetched.
- * @param count The maximum number of ancestors that will be returned.
- * @return A List of descriptors for ancestors starting most recent first.
+ * Get a list of up to count nodes in the history chain of a node.
+ * The initial element of the list returned will be desc
+ * (as long as the count is non-zero).
+ *
+ * @param desc The descriptor for a node to find ancestors for.
+ * @param count maximum number of ancestors to return in the list
+ * (the value -1 means
+ * "no limit -- return them all")
+ * @return A List of ancestors starting with the most recent.
+ * @throws AVMNotFoundException
*/
public Listpath.
+ *
+ *
* @param version The version to look under.
- * @param path The path to the node.
- * @return A LayeringDescriptor.
+ * @param path The absolute AVM path.
+ * @return A LayeringDescriptor.
+ * @throws AVMNotFoundException
+ * @throws AVMWrongTypeException
*/
public LayeringDescriptor getLayeringInfo(int version, String path);
/**
* Set a property on a node.
- * @param path The path to the node.
- * @param name The name of the property.
- * @param value The value to give the property.
+ *
+ * @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
+ * @throws AVMWrongTypeException
*/
public void setNodeProperty(String path, QName name, PropertyValue value);
/**
- * Set a group of properties on a node.
- * @param path The path to the node.
- * @param properties A Map of QNames to PropertyValues to set.
+ * 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
+ * @throws AVMWrongTypeException
*/
public void setNodeProperties(String path, MapHEAD path to a given version.
+ * This works by cloning the version to revert to, and then linking
+ * that new version into HEAD.
+ * The reverted version will have the previous
+ * HEAD version as ancestor.
+ *
+ * @param path The path to the node to revert.
* @param toRevertTo The descriptor of the version to revert to.
- * @throws AVMNotFoundException
+ * @throws AVMNotFoundException
*/
- public void revert(String path, AVMNodeDescriptor toRevertTo);
-
+ public void revert(String path, AVMNodeDescriptor toRevertTo);
+
+
/**
- * Get a version and path of a node.
- * @param desc The descriptor for the node to which we want a path.
- * @return version and path.
- * @throws AVMNotFoundException
- */
- public Pair