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) Deprecated.
void	forceInsert(BasicDocumentRevision rev, java.lang.String... revisionHistory) Inserts a revision of a document with an existing revision ID
void	forceInsert(java.util.List<ForceInsertItem> items) Inserts one or more revisions of a document into the database.
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(java.util.List<ForceInsertItem> items)
          throws DocumentException

Inserts one or more revisions of a document into the database. For efficiency, this is performed as one database transaction.

Each revision is inserted at a point in the tree expressed by the path described in the revisionHistory field. If any non-leaf revisions do not exist locally, then they are created as "stub" revisions.

This method should only be called by the replicator. It is designed to allow revisions from remote databases to be added to this database during the replication process: the documents in the remote database already have revision IDs that need to be preserved for the two databases to be in sync (otherwise it would not be possible to tell that the two represent the same revision). This is analogous to using the _new_edits false option in CouchDB (see the CouchDB wiki for more detail).

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:

items - one or more revisions to insert. Each ForceInsertItem consists of:

• 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

@Deprecated
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

Deprecated.

This method has been deprecated and should not be used.

Throws:

DocumentException

See Also:

forceInsert(List)

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