com.cloudant.sync.datastore

Interface Datastore

All Known Subinterfaces:

DatastoreExtended

public interface Datastore

The Datastore is the core interaction point for create, delete and update operations (CRUD) for within Cloudant Sync.

The Datastore can be viewed as a pool of heterogeneous JSON documents. One datastore can hold many different types of document, unlike tables within a relational model. The datastore provides hooks, particularly in the DatastoreExtended interface, which allow for various querying models to be built on top of its simpler key-value model.

Each document consists of a set of revisions, hence most methods within this class operating on BasicDocumentRevision objects, which carry both a document ID and a revision ID. This forms the basis of the MVCC data model, used to ensure safe peer-to-peer replication is possible.

Each document is formed of a tree of revisions. Replication can create branches in this tree when changes have been made in two or more places to the same document in-between replications. MVCC exposes these branches as conflicted documents. These conflicts should be resolved by user-code, by marking all but one of the leaf nodes of the branches as "deleted", using the deleteDocumentFromRevision(BasicDocumentRevision) method. When the datastore is next replicated with a remote datastore, this fix will be propagated, thereby resolving the conflicted document across the set of peers.

See Also:

DatastoreExtended, BasicDocumentRevision

Field Summary

Fields

Modifier and Type	Field and Description
static long	SEQUENCE_NUMBER_START The sequence number of the datastore when no updates have been made, -1L.

Method Summary

Modifier and Type	Method and Description
Changes	changes(long since, int limit) Returns a list of changed documents, from since to since + limit, inclusive.
void	close() Close the datastore
void	compact() Compacts the sqlDatabase storage by removing the bodies and attachments of obsolete revisions.
boolean	containsDocument(java.lang.String documentId) Returns whether this datastore contains any revisions of a document.
boolean	containsDocument(java.lang.String documentId, java.lang.String revisionId) Returns whether this datastore contains a particular revision of a document.
BasicDocumentRevision	createDocumentFromRevision(MutableDocumentRevision rev) Adds a new document with body and attachments from rev.
java.util.List<BasicDocumentRevision>	deleteDocument(java.lang.String id) Delete all leaf revisions for the document
BasicDocumentRevision	deleteDocumentFromRevision(BasicDocumentRevision rev) Deletes a document from the datastore.
java.lang.String	extensionDataFolder(java.lang.String extensionName) Return the directory for specified extensionName
java.util.List<java.lang.String>	getAllDocumentIds() Enumerates the current winning revision for all documents in the datastore and return a list of their document identifiers.
java.util.List<BasicDocumentRevision>	getAllDocuments(int offset, int limit, boolean descending) Enumerates the current winning revision for all documents in the datastore.
java.util.Iterator<java.lang.String>	getConflictedDocumentIds() Return @Iterable<String> over ids to all the Documents with conflicted revisions.
java.lang.String	getDatastoreName() Returns the name of this datastore.
BasicDocumentRevision	getDocument(java.lang.String documentId) Returns the current winning revision of a document.
BasicDocumentRevision	getDocument(java.lang.String documentId, java.lang.String revisionId) Retrieves a given revision of a document.
int	getDocumentCount() Return the number of documents in the datastore
java.util.List<BasicDocumentRevision>	getDocumentsWithIds(java.util.List<java.lang.String> documentIds) Returns the current winning revisions for a set of documents.
com.google.common.eventbus.EventBus	getEventBus() Returns the EventBus which this Datastore posts Document Notification Events to.
KeyProvider	getKeyProvider() Returns the encryption KeyProvider of this datastore.
long	getLastSequence() Retrieves the datastore's current sequence number.
java.util.List<java.lang.String>	getPossibleAncestorRevisionIDs(java.lang.String docId, java.lang.String revId, int limit)
void	resolveConflictsForDocument(java.lang.String docId, ConflictResolver resolver) Resolve conflicts for specified Document using the given ConflictResolver
BasicDocumentRevision	updateDocumentFromRevision(MutableDocumentRevision rev) Updates a document that exists in the datastore with with body and attachments from rev.

Field Detail

SEQUENCE_NUMBER_START

static final long SEQUENCE_NUMBER_START

The sequence number of the datastore when no updates have been made, -1L.

See Also:

Constant Field Values

Method Detail

getDatastoreName

java.lang.String getDatastoreName()

Returns the name of this datastore.

Returns:

the name of this datastore

getKeyProvider

KeyProvider getKeyProvider()

Returns the encryption KeyProvider of this datastore.

Note the key provider could return null for the key, in which case encryption isn't used on this datastore.

Returns:

the key provider used by this datastore.

getDocument

BasicDocumentRevision getDocument(java.lang.String documentId)
                           throws DocumentNotFoundException

Returns the current winning revision of a document.

Previously deleted documents can be retrieved (via tombstones, see deleteDocumentFromRevision(BasicDocumentRevision))

Parameters:

documentId - ID of document to retrieve.

Returns:

DocumentRevision of the document or null if it doesn't exist.

Throws:

DocumentNotFoundException - When the document specified was not found

getDocument

BasicDocumentRevision getDocument(java.lang.String documentId,
                                  java.lang.String revisionId)
                           throws DocumentNotFoundException

Retrieves a given revision of a document.

This method gets the revision of a document with a given ID. As the datastore prunes the content of old revisions to conserve space, this revision may contain the metadata but not content of the revision.

Previously deleted documents can be retrieved (via tombstones, see deleteDocumentFromRevision(BasicDocumentRevision))

Parameters:

documentId - ID of the document

revisionId - Revision of the document

Returns:

DocumentRevision of the document or null if it doesn't exist.

Throws:

DocumentNotFoundException - if the document at the specified revision was not found

containsDocument

boolean containsDocument(java.lang.String documentId,
                         java.lang.String revisionId)

Returns whether this datastore contains a particular revision of a document.

true will still be returned if the document is deleted.

Parameters:

documentId - id of the document

revisionId - revision of the document

Returns:

true if specified document's particular revision exists in the datastore, false otherwise.

containsDocument

boolean containsDocument(java.lang.String documentId)

Returns whether this datastore contains any revisions of a document.

true will still be returned if the document is deleted.

Parameters:

documentId - id of the document

Returns:

true if specified document exists in the datastore, false otherwise.

getAllDocuments

java.util.List<BasicDocumentRevision> getAllDocuments(int offset,
                                                      int limit,
                                                      boolean descending)

Enumerates the current winning revision for all documents in the datastore.

Logically, this method takes all the documents in either ascending or descending order, skips all documents up to offset then returns up to limit document revisions, stopping either at limit or when the list of document is exhausted.

Parameters:

offset - start position

limit - maximum number of documents to return

descending - whether the documents are read in ascending or descending order.

Returns:

list of DBObjects, maximum length limit.

getAllDocumentIds

java.util.List<java.lang.String> getAllDocumentIds()

Enumerates the current winning revision for all documents in the datastore and return a list of their document identifiers.

Returns:

list of String.

getDocumentsWithIds

java.util.List<BasicDocumentRevision> getDocumentsWithIds(java.util.List<java.lang.String> documentIds)

Returns the current winning revisions for a set of documents.

If the documentIds list contains document IDs not present in the datastore, they will be skipped and there will be no entry for them in the returned list.

Parameters:

documentIds - list of document id

Returns:

list of DocumentRevision objects.

getLastSequence

long getLastSequence()

Retrieves the datastore's current sequence number.

The datastore's sequence number is incremented every time the content of the datastore is changed. Each document revision within the datastore has an associated sequence number, describing when the change took place.

The sequence number is particularly useful to find out the changes to the database since a given time. For example, replication uses the sequence number so only the changes since the last replication are sent. Indexing could also use this in a similar manner.

Returns:

the last sequence number

getDocumentCount

int getDocumentCount()

Return the number of documents in the datastore

Returns:

number of non-deleted documents in datastore

changes

Changes changes(long since,
                int limit)

Returns a list of changed documents, from since to since + limit, inclusive.

Parameters:

since - the lower bound (exclusive) of the change set sequence number

limit - since + limit is the upper bound (inclusive) of the change set sequence number

Returns:

list of the documents and last sequence number of the change set (checkpoint)

getEventBus

com.google.common.eventbus.EventBus getEventBus()

Returns the EventBus which this Datastore posts Document Notification Events to.

Returns:

the Datastore's EventBus

See Also:

Google Guava EventBus documentation

extensionDataFolder

java.lang.String extensionDataFolder(java.lang.String extensionName)

Return the directory for specified extensionName

Parameters:

extensionName - name of the extension

Returns:

the directory for specified extensionName

getConflictedDocumentIds

java.util.Iterator<java.lang.String> getConflictedDocumentIds()

Return @Iterable<String> over ids to all the Documents with conflicted revisions.

Document is modeled as a tree. If a document has at least two leaf revisions that not deleted, those leaf revisions considered conflicted revisions of the document.

Returns:

Iterable of String over ids of all Documents with conflicted revisions

See Also:

Replication and conflicts

resolveConflictsForDocument

void resolveConflictsForDocument(java.lang.String docId,
                                 ConflictResolver resolver)
                          throws ConflictException

Resolve conflicts for specified Document using the given ConflictResolver

Parameters:

docId - id of Document to resolve conflicts

resolver - the ConflictResolver used to resolve conflicts

Throws:

ConflictException - Found new conflicts while resolving the existing conflicted revision. This is very likely caused by new conflicted revision are added while the resolver is running.

See Also:

ConflictResolver

close

void close()

Close the datastore

getPossibleAncestorRevisionIDs

java.util.List<java.lang.String> getPossibleAncestorRevisionIDs(java.lang.String docId,
                                                                java.lang.String revId,
                                                                int limit)

createDocumentFromRevision

BasicDocumentRevision createDocumentFromRevision(MutableDocumentRevision rev)
                                          throws DocumentException

Adds a new document with body and attachments from rev.

If the ID in rev is null, the document's ID will be auto-generated, and can be found by inspecting the returned DocumentRevision.

If the document is successfully created, a DocumentCreated event is posted on the event bus.

Parameters:

rev - the MutableDocumentRevision to be created

Returns:

a DocumentRevision - the newly created document

Throws:

AttachmentException - if there was an error saving any new attachments

DocumentException - if there was an error creating the document

See Also:

getEventBus()

updateDocumentFromRevision

BasicDocumentRevision updateDocumentFromRevision(MutableDocumentRevision rev)
                                          throws DocumentException

Updates a document that exists in the datastore with with body and attachments from rev.

rev must be a current revision for this document.

If the document is successfully updated, a DocumentUpdated event is posted on the event bus.

Parameters:

rev - the MutableDocumentRevision to be updated

Returns:

a DocumentRevision - the updated document

Throws:

ConflictException - rev is not a current revision for this document

AttachmentException - if there was an error saving the attachments

DocumentException - if there was an error updating the document

See Also:

getEventBus()

deleteDocumentFromRevision

BasicDocumentRevision deleteDocumentFromRevision(BasicDocumentRevision rev)
                                          throws ConflictException

Deletes a document from the datastore.

This operation leaves a "tombstone" for the deleted document, so that future replication operations can successfully replicate the deletion.

If the document is successfully deleted, a DocumentDeleted event is posted on the event bus.

If the input revision is already deleted, nothing will be changed.

When resolving conflicts, this method can be used to delete any non-deleted leaf revision of a document. resolveConflictsForDocument(java.lang.String, com.cloudant.sync.datastore.ConflictResolver) handles this deletion step during conflict resolution, so it's not usually necessary to call this method in this way from client code. See the doc/conflicts.md document for more details.

Parameters:

rev - the MutableDocumentRevision to be deleted

Returns:

a DocumentRevision - the deleted or "tombstone" document

Throws:

ConflictException - if the sourceRevisionId is not the current revision

See Also:

getEventBus(), resolveConflictsForDocument(java.lang.String, com.cloudant.sync.datastore.ConflictResolver)

deleteDocument

java.util.List<BasicDocumentRevision> deleteDocument(java.lang.String id)
                                              throws DocumentException

Delete all leaf revisions for the document

This is equivalent to calling deleteDocumentFromRevision on all leaf revisions

Parameters:

id - the ID of the document to delete leaf nodes for

Returns:

a List of a DocumentRevisions - the deleted or "tombstone" documents

Throws:

DocumentException - if there was an error deleting the document

See Also:

getEventBus(), deleteDocumentFromRevision(BasicDocumentRevision)

compact

void compact()

Compacts the sqlDatabase storage by removing the bodies and attachments of obsolete revisions.