docs: public void crudSamples() throws Exception {
  
          // DocumentStore and Database:
          // The examples below show how to obtain a DocumentStore instance how to obtain the Database
          // object it owns.
  
          // Choose a path for your DocumentStores
          File path = new File("/tmp");
          // on Android, we could do something like:
          // File path = getApplicationContext().getDir("document_stores");
  
          // Once you've got a path, it's straightforward to create DocumentStores:
          DocumentStore ds = DocumentStore.getInstance(new File(path, "my_document_store"));
          DocumentStore ds2 = DocumentStore.getInstance(new File(path, "other_document_store"));
  
          // Static getInstance() methods on DocumentStore will create and initialize a DocumentStore
          // instance if it doesn't already exist, or retrieve an existing one.
  
          // Document CRUD APIs
  
          // Once you have a DocumentStore instance, you can use it to create, read, update and
          // delete documents
  
          // Create
  
          // Documents are represented as a set of revisions. To create a document, you
          // set up the initial revision of the document and save that to the DocumentStore.
  
          // Create a document revision object, set its body, ID and attachments
          // and then call create(DocumentRevision) to add it to the DocumentStore:
  
          // Create a document with a document id as the constructor argument
          DocumentRevision rev = new DocumentRevision("doc1");
          // Or don't assign the docId property, we'll generate one
          rev = new DocumentRevision();
  
          // Build up body content from a Map
          Map<String, Object> json = new HashMap<String, Object>();
          json.put("description", "Buy milk");
          json.put("completed", false);
          json.put("type", "com.cloudant.sync.example.task");
          rev.setBody(DocumentBodyFactory.create(json));
  
          // Now call create(). Note that we call all of the CRUD methods through the Database
          // instance which is obtained via the database() getter.
          DocumentRevision revision = ds.database().create(rev);
  
          // The only mandatory property to set before calling
          // create(DocumentRevision) is the body. An ID will be generated
          // for documents which don't have docId set.
  
          // Read
  
          // Also known as retrieve. Once you have created one or more documents, retrieve them by ID:
          String docId = revision.getId();
          DocumentRevision retrieved = ds.database().read(docId);
  
          // if you know the revision ID of a particular revision you want to retrieve, use the 2
          // argument form of read():
          retrieved = ds.database().read(docId, "4-c88152f475d5ebee7ad222b54e870d73");
  
          // This document is mutable and you can make changes to it, as shown below.
  
          // Update
  
          // To update a document, make your changes and save the document:
          json = retrieved.getBody().asMap();
          json.put("completed", true);
          retrieved.setBody(DocumentBodyFactory.create(json));
  
          // Note that "updated" is the new DocumentRevision with a new revision ID
          DocumentRevision updated = ds.database().update(retrieved);
  
          // Delete
  
          // To delete a document, you need the current revision:
          ds.database().delete(updated);
  
          // Indexing and Query
  
          // You don't need to know the ID of the document to retrieve it. The DocumentStore
          // provides ways to index and search the fields of your JSON documents.
          // For more, see https://github.com/cloudant/sync-android/blob/master/doc/query.md.
  
          // Conflicts
  
          // getConflictedIds can be used to retrieve IDs of documents which are in a conflicted
          // state. resolveConflicts can be used to pick a winning revision and mark all others as
          // deleted, thus resolving the conflicted state. For more details see
          // https://github.com/cloudant/sync-android/blob/master/doc/conflicts.md
          for (String conflictedDocId : ds.database().getConflictedIds()) {
              ds.database().resolveConflicts(conflictedDocId, new ConflictResolver() {
                  @Override
                  public DocumentRevision resolve(String docId, List<? extends DocumentRevision>
                          conflicts) {
                      // pick the first revision - not a recommended strategy for a 'real' resolver
                      return conflicts.get(0);
                  }
              });
          }
  
          // Getting all documents
  
          // The read(int offset, int limit, boolean descending) method allows iterating through
          // all documents in the database:
  
          // read all documents in one go
          int pageSize = ds.database().getDocumentCount();
          List<DocumentRevision> docs = ds.database().read(0, pageSize, true);
  
          // Using attachments
  
          // You can associate attachments with the JSON documents in your DocumentStores.
          // Attachments are blobs of binary data, such as photos or short sound snippets.
          // They should be of small length -- maximum a few MB -- because they are
          // replicated to and from the server in a way which doesn't allow for resuming
          // an upload or download.
          //
          // Attachments are stored via the attachments getters/setters on a DocumentRevision
          // object. This is a map of attachments, keyed by attachment name.
          //
          // To add an attachment to a document, just add (or overwrite) the attachment
          // in the attachments map:
  
          // create a body
          rev.setBody(DocumentBodyFactory.create(json));
  
          // create an UnsavedFileAttachment: the constructor takes
          // a File object on disk and a MIME type
          UnsavedFileAttachment att1 = new UnsavedFileAttachment(
                  new File("/path/to/image.jpg"), "image/jpeg");
          // the name can be any unique identifier for a given document ID
          // it can be used later to look up the attachment within the DocumentRevision
          String att1Name = "image.jpg";
  
          // As with the document body, you can replace the attachments
          rev.setAttachments(new HashMap<String, Attachment>());
  
          // Or just add or update a single one:
          // (because the getter will always return the underlying map and not a copy)
          rev.getAttachments().put(att1Name, att1);
  
          DocumentRevision saved = ds.database().create(rev);
  
          // Above, we used UnsavedFileAttachment for data which was already on disk. Use
          // UnsavedStreamAttachment for data which comes from an InputStream or is already in
          // memory.
  
          byte[] imageData = new byte[256];
          // ByteArrayInputStream adapts imageData to be used as a stream
          UnsavedStreamAttachment att2 = new UnsavedStreamAttachment(
                  new ByteArrayInputStream(imageData), "image/jpeg");
          String att2Name = "cute_cat.jpg";
  
          rev = new DocumentRevision();
          rev.getAttachments().put(att1Name, att1);
          rev.getAttachments().put(att2Name, att2);
          saved = ds.database().create(rev);
  
          // To read an attachment, get the SavedAttachment from the attachments
          // map. Then use getInputStream() to read the data:
  
          retrieved = ds.database().read("myDoc");
          Attachment att = retrieved.getAttachments().get("cute_cat.jpg");
          InputStream is = att.getInputStream();
  
          // get all bytes in memory if required
          byte[] data = new byte[(int) att.length];
          is.read(data);
  
          // To remove an attachment, remove it from the attachments map:
  
          retrieved = ds.database().read("myDoc");
          retrieved.getAttachments().remove("cute_cat.jpg");
          updated = ds.database().update(retrieved);
  
          // To remove all attachments, set the attachments property to an empty map
          // or null:
  
          updated.setAttachments(null);
          ds.database().update(updated);
  
          // Closing and deleting the DocumentStore
  
          // Finally, to close a DocumentStore (which closes the underlying database files and
          // releases native resources):
          ds.close();
  
          // or to delete a DocumentStore (which closes it first):
          ds.delete();
  
  
          // Cookbook
          //
          // This section shows all the ways (that I could think of) that you can update,
          // modify and delete documents.
          //
          // Creating a new document
          //
          // This is the simplest case as we don't need to worry about previous revisions.
          //
          // Add a document with body, but not attachments or ID. You'll get an
          // autogenerated ID.
          DocumentRevision newRev = new DocumentRevision();
  
          newRev.setBody(DocumentBodyFactory.create(json));
  
          saved = ds.database().create(newRev);
  
          // Add a new document to the store with a body and ID, but without attachments.
          newRev = new DocumentRevision("doc1");
          newRev.setBody(DocumentBodyFactory.create(json));
  
          saved = ds.database().create(newRev);
  
          // Add a new document to the store with attachments.
  
          newRev = new DocumentRevision("doc1");
          newRev.setBody(DocumentBodyFactory.create(json));
  
          att1 = new UnsavedFileAttachment(
                  new File("/path/to/image.jpg"), "image/jpeg");
          newRev.getAttachments().put(att1Name, att1);
  
          saved = ds.database().create(newRev);
  
          // Add a document with body and attachments, but no ID. You'll get an
          // autogenerated ID.
          newRev = new DocumentRevision();
          newRev.setBody(DocumentBodyFactory.create(json));
  
          att1 = new UnsavedFileAttachment(
                  new File("/path/to/image.jpg"), "image/jpeg");
          rev.getAttachments().put(att1Name, att1);
  
          saved = ds.database().create(rev);
  
          // You can't create a document without a body (body is the only required property).
          rev = new DocumentRevision();
  
          saved = ds.database().create(rev);
          // will throw java.lang.IllegalArgumentException: Input document body can not be null
  
          // Updating a document
  
          // To update a document, make your changes and save the document.
  
          // Update body for doc that has no attachments, adding no attachments
          Map<String, Object> updatedJson = new HashMap<String, Object>();
          updatedJson.put("description", "Buy eggs");
          updatedJson.put("completed", true);
          updatedJson.put("type", "com.cloudant.sync.example.task");
          saved.setBody(DocumentBodyFactory.create(updatedJson));
          updated = ds.database().update(saved);
  
          // Update body for doc with no attachments, adding attachments. The
          // attachments map is accessed and modified via the getAttachments()
          // getter.
          saved.setBody(DocumentBodyFactory.create(updatedJson));
          saved.getAttachments().put(att1Name, att1);
          updated = ds.database().update(saved);
  
          // Update body and remove all attachments.
          saved.setBody(DocumentBodyFactory.create(updatedJson));
          saved.setAttachments(null);
          updated = ds.database().update(saved);
  
          // Update the attachments without changing the body, add attachments to a doc
          // that had none.
          saved.getAttachments().put(att1Name, att1);
          updated = ds.database().update(saved);
  
          // Update attachments by copying from another revision.
          DocumentRevision anotherDoc = ds.database().read("anotherId");
          saved.getAttachments().putAll(anotherDoc.getAttachments());
          updated = ds.database().update(saved);
  
          // Updating a document using an outdated source revision causes a conflict
          saved.setBody(DocumentBodyFactory.create(updatedJson));
          updated = ds.database().update(saved);
          // this will throw ConflictException, because updated is now the latest version:
          ds.database().update(saved);
  
          // For the second set of examples the original document is set up with a body and
          // several attachments:
  
          DocumentRevision revWithAttachments = new DocumentRevision("doc1");
          revWithAttachments.setBody(DocumentBodyFactory.create(json));
          revWithAttachments.getAttachments().put(att1Name, att1);
          revWithAttachments.getAttachments().put(att2Name, att2);
          DocumentRevision savedWithAttachments = ds.database().create(revWithAttachments);
  
          // Update body without changing attachments
          savedWithAttachments.setBody(DocumentBodyFactory.create(updatedJson));
          updated = ds.database().update(savedWithAttachments);
          // Should have the same attachments
  
          // Update the attachments without changing the body, remove attachments
          savedWithAttachments.getAttachments().remove(att1Name);
          updated = ds.database().update(savedWithAttachments);
  
          // Update the attachments without changing the body, add attachments
          savedWithAttachments.getAttachments().put(att1Name, att1);
          updated = ds.database().update(savedWithAttachments);
  
          // Update the attachments without changing the body, remove all attachments
          // by setting null for attachments map.
          savedWithAttachments.setAttachments(null);
          updated = ds.database().update(savedWithAttachments);
  
          // Update the attachments without changing the body, remove all attachments
          // by setting an empty dictionary.
          savedWithAttachments.setAttachments(new HashMap<String, Attachment>());
          updated = ds.database().update(savedWithAttachments);
  
          // Copy an attachment from one document to another.
          DocumentRevision copiedAttachments = new DocumentRevision();
          copiedAttachments.setBody(DocumentBodyFactory.create(json));
          Attachment toCopy = revWithAttachments.getAttachments().get(att1Name);
          copiedAttachments.getAttachments().put(att1Name, toCopy);
          savedWithAttachments = ds.database().create(copiedAttachments);
  
          // Add attachment to "saved" from "revWithAttachments"
          Attachment savedAttachment = revWithAttachments.getAttachments().get("nameOfAttachment");
          saved.getAttachments().put("nameOfAttachment", savedAttachment);
          updated = ds.database().update(saved);
  
          // Deleting a document
  
          // You should be able to delete a given revision (i.e., add a tombstone to the end of
          // the branch).
          saved = ds.database().read("doc1");
          DocumentRevision deleted = ds.database().delete(saved);
  
          // This would refuse to delete if saved was not a leaf node.
  
          // Advanced: you should also be able to delete a document in its entirety by passing
          // in an ID.
  
          List<DocumentRevision> deleteds = ds.database().delete("doc1");
  
          // This marks *all* leaf nodes deleted. Make sure to read the conflicts documentation at
          // https://github.com/cloudant/sync-android/blob/master/doc/conflicts.md
          // before using this method as it can result in data loss (deleting conflicted versions
          // of documents, not just the current winner).
  
      }