Merge pull request #505 from cloudant/416-create-with-history

416 create with history

Author: ricellis

CHANGES.md

@@ -31,7 +31,10 @@
 - [NOTE] The "CRUD Guide" markdown document (previously located in
   `doc/crud.md`) has been migrated to a
   [java source file](https://github.com/cloudant/sync-android/blob/2.0.0/doc/CrudSamples.java).
-  
+
+- [NEW] `databaseWithAdvancedAPIs()` getter on `DocumentStore` for specialist advanced use cases.
+  Adds support for creating specific document revisions with history.
+
 - [FIXED] Issue with double encoding of restricted URL characters in credentials when using
   `ReplicatorBuilder`.
 

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/Database.java

@@ -287,12 +287,13 @@ DocumentRevision create(DocumentRevision rev) throws AttachmentException,
      * @param rev the {@link DocumentRevision} to be updated
      * @return a {@link DocumentRevision} - the updated document
      * @throws ConflictException if <code>rev</code> is not a current revision for this document
+     * @throws DocumentNotFoundException if the {@code rev} being updated does not exist
      * @throws AttachmentException if there was an error saving any new attachments
      * @throws DocumentStoreException if there was an error reading from or writing to the database
      * @see Database#getEventBus()
      */
     DocumentRevision update(DocumentRevision rev) throws ConflictException,
-            AttachmentException, DocumentStoreException;
+            AttachmentException, DocumentStoreException, DocumentNotFoundException;
 
     /**
      * <p>Deletes a document from the datastore.</p>

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/DocumentRevision.java

@@ -105,6 +105,20 @@ public boolean isDeleted() {
         return deleted;
     }
 
+    /**
+     * To delete a document it is preferable to call {@link Database#delete(DocumentRevision)}.
+     * Some use cases need to do a delete via an update in which case it is possible to
+     * call this method, followed by {@link Database#update(DocumentRevision)}.
+     *
+     * This method sets the document revision's {@code _deleted} flag to true and removes the body
+     * and attachments from the document revision.
+     *
+     */
+    public void setDeleted() {
+        this.deleted = true;
+        this.setBody(DocumentBodyFactory.EMPTY);
+    }
+
     public Map<String, Attachment> getAttachments() {
         return attachments;
     }

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/DocumentStore.java

@@ -16,15 +16,15 @@
 
 import com.cloudant.sync.documentstore.encryption.KeyProvider;
 import com.cloudant.sync.documentstore.encryption.NullKeyProvider;
-import com.cloudant.sync.internal.documentstore.DatabaseImpl;
 import com.cloudant.sync.event.EventBus;
 import com.cloudant.sync.event.notifications.DocumentStoreClosed;
 import com.cloudant.sync.event.notifications.DocumentStoreCreated;
 import com.cloudant.sync.event.notifications.DocumentStoreDeleted;
-import com.cloudant.sync.event.notifications.DocumentStoreOpened;
 import com.cloudant.sync.event.notifications.DocumentStoreModified;
-import com.cloudant.sync.query.Query;
+import com.cloudant.sync.event.notifications.DocumentStoreOpened;
+import com.cloudant.sync.internal.documentstore.DatabaseImpl;
 import com.cloudant.sync.internal.query.QueryImpl;
+import com.cloudant.sync.query.Query;
 
 import org.apache.commons.io.FileUtils;
 
@@ -68,7 +68,7 @@ public class DocumentStore {
 
     private static final String EXTENSIONS_LOCATION_NAME = "extensions";
 
-    private final Database database;
+    private final DatabaseImpl database;
     private final Query query;
     protected final String databaseName; // only used for events
     private final File location; // needed for close/delete
@@ -187,6 +187,18 @@ public Database database() {
         return database;
     }
 
+    /**
+     * WARNING: accessing APIs exposed on the
+     * {@link com.cloudant.sync.documentstore.advanced.Database} class returned by this method is
+     * not required for typical use cases. Refer to the javadoc in the
+     * {@link com.cloudant.sync.documentstore.advanced} package before using this.
+     *
+     * @return interface to advanced database methods
+     */
+    public com.cloudant.sync.documentstore.advanced.Database advanced() {
+        return database;
+    }
+
     /**
      * <p>
      * Get a reference to the {@link Query} object.
@@ -208,7 +220,7 @@ public void close() {
         synchronized (documentStores) {
             DocumentStore ds = documentStores.remove(location);
             if (ds != null) {
-                ((DatabaseImpl)database).close();
+                database.close();
                 ((QueryImpl)query).close();
             }
             else {
@@ -255,7 +267,7 @@ public static EventBus getEventBus() {
 
     private void closeQuietlyOnException() {
         if (database != null) {
-            ((DatabaseImpl) database).close();
+            database.close();
         }
         if (query != null) {
             ((QueryImpl) query).close();

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/advanced/Database.java

@@ -0,0 +1,136 @@
+package com.cloudant.sync.documentstore.advanced;
+
+import com.cloudant.sync.documentstore.DocumentException;
+import com.cloudant.sync.documentstore.DocumentRevision;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * <P>
+ * ⚠ Database API methods for advanced use cases.
+ * </P>
+ * <P>
+ * ⚠ Interacting with these methods is not required for the typical use cases. Use with extreme
+ * caution.
+ * </P>
+ */
+public interface Database {
+
+    /**
+     * <P>
+     * ⚠ Creates a new revision in the database with the specified revision history.
+     * </P>
+     * <P>
+     * This is equivalent to inserting a revision with {@code new_edits: false}, functionality that
+     * is typically only required by replicators.
+     * </P>
+     * <P>
+     * Note that the revisionsStart and revisionsIDs parameters describe the revision history of the
+     * document revision being inserted. This history is equivalent to getting the document from
+     * CouchDB with the {@code revs=true} parameter.
+     * An example document retrieved with this _revisions history would be:
+     * </P>
+     * <pre>
+     * {@code
+     * {"_id”:”exampledoc1”,
+     * "_rev":"4-51aa94e4b0ef37271082033bba52b850",
+     * "_revisions":
+     *     {"start":4,
+     *      "ids": [“51aa94e4b0ef37271082033bba52b850",
+     *              "f9fb951ca8dadec1459450156b2205cf",
+     *              "617a372bba833d7acf3ccf2e7dece15a",
+     *              "967a00dff5e02add41819138abb3284d"]
+     *     },
+     *     ... // other document properties
+     * }
+     * }
+     * </pre>
+     * <P>
+     * Example usage to insert this example document:
+     * </P>
+     * <pre>
+     * {@code
+     * DocumentRevision documentRevision = new DocumentRevision("exampledoc1",
+     *     "4-51aa94e4b0ef37271082033bba52b850");
+     * // set document content etc
+     * documentRevision.setBody(...)
+     *
+     * // set attachments if necessary, see note on attachments below.
+     *
+     * documentStore.advanced()
+     *    .createWithHistory(documentRevision, 4, Arrays.asList(“51aa94e4b0ef37271082033bba52b850",
+     *              "f9fb951ca8dadec1459450156b2205cf",
+     *              "617a372bba833d7acf3ccf2e7dece15a",
+     *              "967a00dff5e02add41819138abb3284d"))
+     * }
+     * </pre>
+     * <P>
+     * If the document is deleted then the inserted revision also needs to be made deleted as in
+     * this example:
+     * </P>
+     * <pre>
+     * {@code
+     * DocumentRevision documentRevision = new DocumentRevision("exampledoc1",
+     *     "4-51aa94e4b0ef37271082033bba52b850");
+     * // set document as deleted
+     * documentRevision.setDeleted()
+     *
+     * documentStore.advanced()
+     *    .createWithHistory(documentRevision, 4, Arrays.asList(“51aa94e4b0ef37271082033bba52b850",
+     *              "f9fb951ca8dadec1459450156b2205cf",
+     *              "617a372bba833d7acf3ccf2e7dece15a",
+     *              "967a00dff5e02add41819138abb3284d"))
+     * }
+     * </pre>
+     * <P>
+     * <B>Attachments</B>
+     * </P>
+     * <P>
+     * Note it is the caller's responsibility to correctly set the attachments on the revision to be
+     * created. The existing attachments should be compared to the attachments metadata present in
+     * the JSON of the document revision to be created and an appropriate call made to
+     * {@link DocumentRevision#setAttachments(Map)} to transfer that metadata and any new attachment
+     * files to the {@code DocumentRevision} object. If a comparison of the JSON attachment metadata
+     * to the existing attachments indicates that no new attachments are being added then it is
+     * possible to simply set the existing attachment map like this:
+     * </P>
+     * <pre>
+     * {@code
+     * // Get the existing attachments from the current revision
+     * Map<String, Attachment> atts = database.read("exampledoc1").getAttachments();
+     * // Set the attachment metadata on the DocumentRevision object that will be passed to
+     * // createWithHistory.
+     * documentRevision.setAttachments(atts);
+     * }
+     * </pre>
+     * <P>
+     * If new attachments need to be added, then the normal CRUD API for creating or updating
+     * attachments should be used to create the attachments on the revision before calling
+     * createWithHistory, for example, using
+     * {@link com.cloudant.sync.documentstore.UnsavedFileAttachment}.
+     * </P>
+     * <P>
+     * If no attachments are set then attachments on ancestor revisions in the existing tree will
+     * be deleted on the newly created revision, as it is equivalent to performing an update with an
+     * empty attachment map. It is essential to check for existing attachments and set them
+     * appropriately on the DocumentRevision if you want to preserve attachments when calling
+     * createWithHistory.
+     * </P>
+     *
+     * @param documentRevision the revision of the document to create in the database
+     * @param revisionsStart   the generation ID of the revision being inserted, for
+     *                         example obtained from the {@code start} property of
+     *                         the {@code _revisions} property object of a document
+     *                         obtained with {@code revs=true}
+     * @param revisionsIDs     the sequence of revision IDs (excluding the generational prefix)
+     *                         starting with the revision being inserted and progressing to the root
+     *                         of the document, for example a list of the JSON array content of the
+     *                         {@code ids} property of the {@code _revisions} property object of a
+     *                         document obtained with {@code revs=true}
+     * @throws DocumentException if there was an error inserting the revision or its attachments
+     *                           into the database
+     */
+    void createWithHistory(DocumentRevision documentRevision, int revisionsStart, List<String>
+            revisionsIDs) throws DocumentException;
+}

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/advanced/package-info.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright © 2017 IBM Corp. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the
+ * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied. See the License for the specific language governing permissions
+ * and limitations under the License.
+ */
+
+/**
+ * <P>
+ * ⚠ The interfaces in this package are not needed for typical use of the sync library.
+ * </P>
+ * <P>
+ * ⚠ These interfaces are provided for flexibility to allow interactions with the database that
+ * would otherwise be prevented by the API, but are necessary for some use cases. An example would
+ * be writing your own replicator for this library's DocumentStore.
+ * </P>
+ * <P>
+ * ⚠ Use of the APIs in this package is beyond the intended use case of the sync library and by
+ * their nature they may expose untested edge cases. Incorrect use of the APIs could result in data
+ * loss or corruption. You should only use these interfaces if you really know what you are doing!
+ * </P>
+ */
+package com.cloudant.sync.documentstore.advanced;

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/internal/common/CouchUtils.java

@@ -18,8 +18,9 @@
 
 import com.cloudant.sync.internal.util.Misc;
 
+import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
-import java.util.Map;
 import java.util.UUID;
 
 public class CouchUtils {
@@ -48,23 +49,23 @@ public static boolean isValidDocumentId(String docId) {
         return true;
     }
 
-    /*
-     * Parses the _revisions dict from a document into an array of revision ID strings
+    /**
+     * Get an ascending order revision list from the couch style {@code _revisions} history of
+     * {@code start} and hash {@code ids}.
+     *
+     * @param start the starting generation
+     * @param ids   the list of ID hashes
+     * @return
      */
-    public static List<String> parseCouchDBRevisionHistory(Map<String, Object> docProperties) {
-        Map<String, Object> revisions = (Map<String, Object>) docProperties.get(CouchConstants._revisions);
-        if (revisions == null) {
-            return null;
+    public static List<String> couchStyleRevisionHistoryToFullRevisionIDs(final int start, List<String> ids) {
+        List<String> revisionHistory = new ArrayList<String>();
+        int generation = start;
+        for (String revIdHash : ids) {
+            revisionHistory.add(generation + "-" + revIdHash);
+            generation--;
         }
-        List<String> revIDs = (List<String>) revisions.get(CouchConstants.ids);
-        Integer start = (Integer) revisions.get(CouchConstants.start);
-        if (start != null) {
-            for (int i = 0; i < revIDs.size(); i++) {
-                String revID = revIDs.get(i);
-                revIDs.set(i, Integer.toString(start--) + "-" + revID);
-            }
-        }
-        return revIDs;
+        Collections.reverse(revisionHistory);
+        return revisionHistory;
     }
 
     public static String getFirstLocalDocRevisionId() {