com.cloudant.sync.datastore

Interface DatastoreExtended

All Superinterfaces:

Datastore

public interface DatastoreExtended
extends Datastore

DatastoreExtended adds further, lesser-used methods to the Datastore interface.

These methods are typically used by other packages extending the datastore's functionality. For example, the replication package uses these extended APIs to implement replication between local and remote CouchDB-replication-protocol compatible datastores.

Field Summary

Fields inherited from interface com.cloudant.sync.datastore.Datastore

SEQUENCE_NUMBER_START

Method Summary

Modifier and Type	Method and Description
java.util.List<? extends Attachment>	attachmentsForRevision(BasicDocumentRevision rev) Returns all attachments for the revision.
void	deleteLocalDocument(java.lang.String documentId) Deletes a local document.
void	forceInsert(BasicDocumentRevision rev, java.util.List<java.lang.String> revisionHistory, java.util.Map<java.lang.String,java.lang.Object> attachments, java.util.Map<java.lang.String[],java.util.List<PreparedAttachment>> preparedAttachments, boolean pullAttachmentsInline) Inserts a revision of a document with an existing revision ID and revision history.
void	forceInsert(BasicDocumentRevision rev, java.lang.String... revisionHistory) Inserts a revision of a document with an existing revision ID
DocumentRevisionTree	getAllRevisionsOfDocument(java.lang.String documentId) Returns DocumentRevisionTree of a document.
Attachment	getAttachment(BasicDocumentRevision rev, java.lang.String attachmentName) Returns attachment attachmentName for the revision.
int	getDocumentCount() Returns the number of documents in the database, including deleted documents.
LocalDocument	getLocalDocument(java.lang.String documentId) Returns the current winning revision of a local document.
java.lang.String	getPublicIdentifier() Returns the datastore's unique identifier.
LocalDocument	insertLocalDocument(java.lang.String docId, DocumentBody body) Inserts a local document with an ID and body.
PreparedAttachment	prepareAttachment(Attachment att, long length, long encodedLength) Read attachment stream to a temporary location and calculate sha1, prior to being added to the datastore.
java.util.Map<java.lang.String,java.util.Collection<java.lang.String>>	revsDiff(com.google.common.collect.Multimap<java.lang.String,java.lang.String> revisions) Returns the subset of given the document id/revisions that are not stored in the database.

Methods inherited from interface com.cloudant.sync.datastore.Datastore

changes, close, compact, containsDocument, containsDocument, createDocumentFromRevision, deleteDocument, deleteDocumentFromRevision, extensionDataFolder, getAllDocumentIds, getAllDocuments, getConflictedDocumentIds, getDatastoreName, getDocument, getDocument, getDocumentsWithIds, getEventBus, getKeyProvider, getLastSequence, getPossibleAncestorRevisionIDs, resolveConflictsForDocument, updateDocumentFromRevision

Method Detail

insertLocalDocument

LocalDocument insertLocalDocument(java.lang.String docId,
                                  DocumentBody body)
                           throws DocumentException

Inserts a local document with an ID and body. Replacing the current local document of the same id if one is present.

Local documents are not replicated between datastores.

Parameters:

docId - The document id for the document

body - JSON body for the document

Returns:

DocumentRevision of the newly created document

Throws:

DocumentException - if there is an error inserting the local document into the database

getLocalDocument

LocalDocument getLocalDocument(java.lang.String documentId)
                        throws DocumentNotFoundException

Returns the current winning revision of a local document.

Parameters:

documentId - id of the local document

Returns:

LocalDocument of the document

Throws:

DocumentNotFoundException - if the document ID doesn't exist

deleteLocalDocument

void deleteLocalDocument(java.lang.String documentId)
                  throws DocumentNotFoundException

Deletes a local document.

Parameters:

documentId - documentId of the document to be deleted

Throws:

DocumentNotFoundException - if the document ID doesn't exist

getAllRevisionsOfDocument

DocumentRevisionTree getAllRevisionsOfDocument(java.lang.String documentId)

Returns DocumentRevisionTree of a document.

The tree contains the complete revision history of the document, including branches for conflicts and deleted leaves.

Parameters:

documentId - id of the document

Returns:

DocumentRevisionTree of the specified document

forceInsert

void forceInsert(BasicDocumentRevision rev,
                 java.util.List<java.lang.String> revisionHistory,
                 java.util.Map<java.lang.String,java.lang.Object> attachments,
                 java.util.Map<java.lang.String[],java.util.List<PreparedAttachment>> preparedAttachments,
                 boolean pullAttachmentsInline)
          throws DocumentException

Inserts a revision of a document with an existing revision ID and revision history.

This method inserts a revision into the document tree for an existing document. It checks every revision in the revision history, and adds rev is it isn't already present in the datastore.

Here is an example of revHistory:

 [
     "1-421ff3d58df47ea6c5e83ca65efb2fa9",
     "2-74e0572530e3b4cd4776616d2f591a96",
     "3-d8e1fb8127d8dd732d9ae46a6c38ae3c",
     "4-47d7102726fc89914431cb217ab7bace"
 ]
 

This method should only be called by the replicator. It's designed to allow revisions from different datastores to be added to this datastore during the replication process, when we wouldn't want to create new revision IDs (as if we did, we wouldn't know that we already had a particular revision from a previous replication).

The revisionHistory is required so that we know whether the rev is part of the existing document tree, so we can see whether it's a conflict which needs to be grafted to the tree or whether it's a newer version of the same branch we already have.

If the document was successfully inserted, a DocumentCreated, DocumentModified, or DocumentDeleted event is posted on the event bus. The event will depend on the nature of the update made.

Parameters:

rev - A DocumentRevision containing the information for a revision from a remote datastore.

revisionHistory - The history of the revision being inserted, including the rev ID of rev. This list needs to be sorted in ascending order

attachments - Attachments metadata and optionally data if pullAttachmentsInline true

preparedAttachments - Non-empty if pullAttachmentsInline false. Attachments that have already been prepared, this is a Map of String[docId,revId] → list of attachments

pullAttachmentsInline - If true, use attachments metadata and data directly from received JSON to add new attachments for this revision. Else use preparedAttachments which were previously downloaded and prepared by processOneChangesBatch in BasicPullStrategy

Throws:

DocumentException - if there was an error inserting the revision or its attachments into the database

See Also:

Datastore.getEventBus()

forceInsert

void forceInsert(BasicDocumentRevision rev,
                 java.lang.String... revisionHistory)
          throws DocumentException

Inserts a revision of a document with an existing revision ID

Equivalent to:

forceInsert(rev, Arrays.asList(revisionHistory), null, null, false);

Parameters:

rev - A DocumentRevision containing the information for a revision from a remote datastore.

revisionHistory - The history of the revision being inserted, including the rev ID of rev. This list needs to be sorted in ascending order

Throws:

DocumentException - if there was an error inserting the revision into the database

See Also:

forceInsert(BasicDocumentRevision, java.util.List,java.util.Map, java.util.Map, boolean)

getPublicIdentifier

java.lang.String getPublicIdentifier()
                              throws DatastoreException

Returns the datastore's unique identifier.

This is used for the checkpoint document in a remote datastore during replication.

Returns:

a unique identifier for the datastore.

Throws:

DatastoreException - if there was an error retrieving the unique identifier from the database

getDocumentCount

int getDocumentCount()

Returns the number of documents in the database, including deleted documents.

Specified by:

getDocumentCount in interface Datastore

Returns:

document count, including deleted docs.

revsDiff

java.util.Map<java.lang.String,java.util.Collection<java.lang.String>> revsDiff(com.google.common.collect.Multimap<java.lang.String,java.lang.String> revisions)

Returns the subset of given the document id/revisions that are not stored in the database. The input revisions is a map, whose key is document id, and value is a list of revisions. An example input could be (in json format): { "03ee06461a12f3c288bb865b22000170": [ "1-b2e54331db828310f3c772d6e042ac9c", "2-3a24009a9525bde9e4bfa8a99046b00d" ], "82e04f650661c9bdb88c57e044000a4b": [ "3-bb39f8c740c6ffb8614c7031b46ac162" ] } The output is in same format.

Parameters:

revisions - a Multimap of document id → revision id

Returns:

a Map of document id → collection of revision id: the subset of given the document id/revisions that are not stored in the database

See Also:

HttpPostRevsDiff documentation

prepareAttachment

PreparedAttachment prepareAttachment(Attachment att,
                                     long length,
                                     long encodedLength)
                              throws AttachmentException

Read attachment stream to a temporary location and calculate sha1, prior to being added to the datastore.

Used by replicator when receiving new/updated attachments

Parameters:

att - Attachment to be prepared, providing data either from a file or a stream

length - Size in bytes of attachment as signalled by "length" metadata property

encodedLength - Size in bytes of attachment, after encoding, as signalled by "encoded_length" metadata property

Returns:

A prepared attachment, ready to be added to the datastore

Throws:

AttachmentException - if there was an error preparing the attachment, e.g., reading attachment data.

getAttachment

Attachment getAttachment(BasicDocumentRevision rev,
                         java.lang.String attachmentName)

Returns attachment attachmentName for the revision.

Used by replicator when pushing attachments

Parameters:

rev - The revision with which the attachment is associated

attachmentName - Name of the attachment

Returns:

Attachment or null if there is no attachment with that name.

attachmentsForRevision

java.util.List<? extends Attachment> attachmentsForRevision(BasicDocumentRevision rev)
                                                     throws AttachmentException

Returns all attachments for the revision.

Used by replicator when pulling attachments

Parameters:

rev - The revision with which the attachments are associated

Returns:

List of Attachment

Throws:

AttachmentException - if there was an error reading the attachment metadata from the database