svn commit: r1585420 - /jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/document/DocumentStore.java

[mr...@apache.org]

Author: mreutegg
Date: Mon Apr  7 07:34:58 2014
New Revision: 1585420

URL: http://svn.apache.org/r1585420
Log:
OAK-1678: document atomicity of DS.remove(collection, keys)

Modified:
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/document/DocumentStore.java

Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/document/DocumentStore.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/document/DocumentStore.java?rev=1585420&r1=1585419&r2=1585420&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/document/DocumentStore.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/document/DocumentStore.java Mon Apr  7 07:34:58 2014
@@ -26,6 +26,13 @@ import org.apache.jackrabbit.mk.api.Micr
 /**
  * The interface for the backend storage for documents.
  * <p>
+ * In general atomicity of operations on a DocumentStore are limited to a single
+ * document. That is, an implementation does not have to guarantee atomicity of
+ * the entire effect of a method call. A method that fails with an exception may
+ * have modified just some documents and then abort. However, an implementation
+ * must not modify a document partially. Either the complete update operation
+ * is applied to a document or no modification is done at all.
+ * <p>
  * For keys, the maximum length is 512 bytes in the UTF-8 representation.
  */
 public interface DocumentStore {
@@ -105,7 +112,8 @@ public interface DocumentStore {
                                        int limit);
 
     /**
-     * Remove a document.
+     * Remove a document. This method does nothing if there is no document
+     * with the given key.
      *
      * @param <T> the document type
      * @param collection the collection
@@ -114,7 +122,10 @@ public interface DocumentStore {
     <T extends Document> void remove(Collection<T> collection, String key);
 
     /**
-     * Batch remove documents with given key.
+     * Batch remove documents with given key. Keys for documents that do not
+     * exist are simply ignored. If this method fails with an exception, then
+     * only some of the documents identified by {@code keys} may have been
+     * removed.
      *
      * @param <T> the document type
      * @param collection the collection