com.cloudant.sync.datastore

Class DatastoreImpl

java.lang.Object

com.cloudant.sync.datastore.DatastoreImpl

All Implemented Interfaces:

Datastore

public class DatastoreImpl
extends java.lang.Object
implements Datastore

API Status: Private - API users are discouraged from using this class as fields, method signatures, and implementation details may be subject to change

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	GET_ALL_LEAFS
static java.lang.String	GET_NON_DELETED_LEAFS
static java.lang.String	SQL_CHANGE_IDS_SINCE_LIMIT
static int	SQLITE_QUERY_PLACEHOLDERS_LIMIT

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

SEQUENCE_NUMBER_START

Constructor Summary

Constructors

Constructor and Description
DatastoreImpl(java.lang.String dir, java.lang.String name)
DatastoreImpl(java.lang.String dir, java.lang.String name, KeyProvider provider) Constructor for single thread SQLCipher-based datastore.

Method Summary

Modifier and Type	Method and Description
java.util.List<? extends Attachment>	attachmentsForRevision(DocumentRevision rev) Returns all attachments for the revision.
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 docId) Returns whether this datastore contains any revisions of a document.
boolean	containsDocument(java.lang.String docId, java.lang.String revId) Returns whether this datastore contains a particular revision of a document.
DocumentRevision	createDocumentFromRevision(DocumentRevision rev) Adds a new document with body and attachments from rev.
java.util.List<DocumentRevision>	deleteDocument(java.lang.String id) Delete all leaf revisions for the document
DocumentRevision	deleteDocumentFromRevision(DocumentRevision rev) Deletes a document from the datastore.
void	deleteLocalDocument(java.lang.String docId) Deletes a local document.
java.lang.String	extensionDataFolder(java.lang.String extensionName)
void	forceInsert(DocumentRevision 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(DocumentRevision 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.
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<DocumentRevision>	getAllDocuments(int offset, int limit, boolean descending) Enumerates the current winning revision for all documents in the datastore.
DocumentRevisionTree	getAllRevisionsOfDocument(java.lang.String docId) Returns DocumentRevisionTree of a document.
Attachment	getAttachment(java.lang.String id, java.lang.String rev, java.lang.String attachmentName) Returns attachment attachmentName for the revision.
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.
DocumentRevision	getDocument(java.lang.String id) Returns the current winning revision of a document.
DocumentRevision	getDocument(java.lang.String id, java.lang.String rev) Retrieves a given revision of a document.
int	getDocumentCount() Return the number of documents in the datastore
java.util.List<DocumentRevision>	getDocumentsWithIds(java.util.List<java.lang.String> docIds) Returns the current winning revisions for a set of documents.
EventBus	getEventBus() Returns the EventBus which this Datastore posts Document Notification Events to.
KeyProvider	getKeyProvider()
long	getLastSequence() Retrieves the datastore's current sequence number.
LocalDocument	getLocalDocument(java.lang.String docId) Returns the current winning revision of a local document.
java.util.List<java.lang.String>	getPossibleAncestorRevisionIDs(java.lang.String docId, java.lang.String revId, int limit)
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.
void	resolveConflictsForDocument(java.lang.String docId, ConflictResolver resolver) Resolve conflicts for specified Document using the given ConflictResolver
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.
DocumentRevision	updateDocumentFromRevision(DocumentRevision rev) Updates a document that exists in the datastore with with body and attachments from rev.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SQL_CHANGE_IDS_SINCE_LIMIT

public static final java.lang.String SQL_CHANGE_IDS_SINCE_LIMIT

See Also:

Constant Field Values

GET_NON_DELETED_LEAFS

public static final java.lang.String GET_NON_DELETED_LEAFS

See Also:

Constant Field Values

GET_ALL_LEAFS

public static final java.lang.String GET_ALL_LEAFS

See Also:

Constant Field Values

SQLITE_QUERY_PLACEHOLDERS_LIMIT

public static final int SQLITE_QUERY_PLACEHOLDERS_LIMIT

See Also:

Constant Field Values

Constructor Detail

DatastoreImpl

public DatastoreImpl(java.lang.String dir,
                     java.lang.String name)
              throws java.sql.SQLException,
                     java.io.IOException,
                     DatastoreException

Throws:

java.sql.SQLException

java.io.IOException

DatastoreException

DatastoreImpl

public DatastoreImpl(java.lang.String dir,
                     java.lang.String name,
                     KeyProvider provider)
              throws java.sql.SQLException,
                     java.io.IOException,
                     DatastoreException

Constructor for single thread SQLCipher-based datastore.

Parameters:

dir - The directory where the datastore will be created

name - The user-defined name of the datastore

provider - The key provider object that contains the user-defined SQLCipher key

Throws:

java.sql.SQLException

java.io.IOException

DatastoreException

Method Detail

getDatastoreName

public java.lang.String getDatastoreName()

Description copied from interface: Datastore

Returns the name of this datastore.

Specified by:

getDatastoreName in interface Datastore

Returns:

the name of this datastore

getKeyProvider

public KeyProvider getKeyProvider()

getLastSequence

public long getLastSequence()

Description copied from interface: Datastore

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.

Specified by:

getLastSequence in interface Datastore

Returns:

the last sequence number

getDocumentCount

public int getDocumentCount()

Description copied from interface: Datastore

Return the number of documents in the datastore

Specified by:

getDocumentCount in interface Datastore

Returns:

number of non-deleted documents in datastore

containsDocument

public boolean containsDocument(java.lang.String docId,
                                java.lang.String revId)

Description copied from interface: Datastore

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

true will still be returned if the document is deleted.

Specified by:

containsDocument in interface Datastore

Parameters:

docId - id of the document

revId - revision of the document

Returns:

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

containsDocument

public boolean containsDocument(java.lang.String docId)

Description copied from interface: Datastore

Returns whether this datastore contains any revisions of a document.

true will still be returned if the document is deleted.

Specified by:

containsDocument in interface Datastore

Parameters:

docId - id of the document

Returns:

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

getDocument

public DocumentRevision getDocument(java.lang.String id)
                             throws DocumentNotFoundException

Description copied from interface: Datastore

Returns the current winning revision of a document.

Previously deleted documents can be retrieved (via tombstones, see Datastore.deleteDocumentFromRevision(DocumentRevision))

Specified by:

getDocument in interface Datastore

Parameters:

id - 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

public DocumentRevision getDocument(java.lang.String id,
                                    java.lang.String rev)
                             throws DocumentNotFoundException

Description copied from interface: Datastore

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 Datastore.deleteDocumentFromRevision(DocumentRevision))

Specified by:

getDocument in interface Datastore

Parameters:

id - ID of the document

rev - 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

getAllRevisionsOfDocument

public DocumentRevisionTree getAllRevisionsOfDocument(java.lang.String docId)

Returns DocumentRevisionTree of a document.

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

Parameters:

docId - id of the document

Returns:

DocumentRevisionTree of the specified document

changes

public Changes changes(long since,
                       int limit)

Description copied from interface: Datastore

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

Specified by:

changes in interface Datastore

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)

getAllDocuments

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

Description copied from interface: Datastore

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.

Specified by:

getAllDocuments in interface Datastore

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

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

Description copied from interface: Datastore

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

Specified by:

getAllDocumentIds in interface Datastore

Returns:

list of String.

getDocumentsWithIds

public java.util.List<DocumentRevision> getDocumentsWithIds(java.util.List<java.lang.String> docIds)
                                                     throws DocumentException

Description copied from interface: Datastore

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.

Specified by:

getDocumentsWithIds in interface Datastore

Parameters:

docIds - list of document id

Returns:

list of DocumentRevision objects.

Throws:

DocumentException - if there was an error retrieving the documents.

getPossibleAncestorRevisionIDs

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

getLocalDocument

public LocalDocument getLocalDocument(java.lang.String docId)
                               throws DocumentNotFoundException

Returns the current winning revision of a local document.

Parameters:

docId - id of the local document

Returns:

LocalDocument of the document

Throws:

DocumentNotFoundException - if the document ID doesn't exist

insertLocalDocument

public 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

deleteLocalDocument

public void deleteLocalDocument(java.lang.String docId)
                         throws DocumentNotFoundException

Deletes a local document.

Parameters:

docId - documentId of the document to be deleted

Throws:

DocumentNotFoundException - if the document ID doesn't exist

getPublicIdentifier

public 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

forceInsert

@Deprecated
public void forceInsert(DocumentRevision 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

public 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

public void forceInsert(DocumentRevision 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(DocumentRevision, java.util.List,java.util.Map, java.util.Map, boolean)

compact

public void compact()

Description copied from interface: Datastore

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

Specified by:

compact in interface Datastore

close

public void close()

Description copied from interface: Datastore

Close the datastore

Specified by:

close in interface Datastore

revsDiff

public 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

extensionDataFolder

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

getConflictedDocumentIds

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

Description copied from interface: Datastore

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.

Specified by:

getConflictedDocumentIds in interface Datastore

Returns:

Iterable of String over ids of all Documents with conflicted revisions

See Also:

Replication and conflicts

resolveConflictsForDocument

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

Description copied from interface: Datastore

Resolve conflicts for specified Document using the given ConflictResolver

Specified by:

resolveConflictsForDocument in interface Datastore

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

prepareAttachment

public 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

public Attachment getAttachment(java.lang.String id,
                                java.lang.String rev,
                                java.lang.String attachmentName)

Returns attachment attachmentName for the revision.

Used by replicator when pushing attachments

Parameters:

id - The revision ID with which the attachment is associated

rev - The document ID with which the attachment is associated

attachmentName - Name of the attachment

Returns:

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

attachmentsForRevision

public java.util.List<? extends Attachment> attachmentsForRevision(DocumentRevision 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

getEventBus

public EventBus getEventBus()

Description copied from interface: Datastore

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

Specified by:

getEventBus in interface Datastore

Returns:

the Datastore's EventBus

See Also:

Google Guava EventBus documentation

createDocumentFromRevision

public DocumentRevision createDocumentFromRevision(DocumentRevision rev)
                                            throws DocumentException

Description copied from interface: Datastore

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.

Specified by:

createDocumentFromRevision in interface Datastore

Parameters:

rev - the DocumentRevision 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:

Datastore.getEventBus()

updateDocumentFromRevision

public DocumentRevision updateDocumentFromRevision(DocumentRevision rev)
                                            throws DocumentException

Description copied from interface: Datastore

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.

Specified by:

updateDocumentFromRevision in interface Datastore

Parameters:

rev - the DocumentRevision 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:

Datastore.getEventBus()

deleteDocumentFromRevision

public DocumentRevision deleteDocumentFromRevision(DocumentRevision rev)
                                            throws ConflictException

Description copied from interface: Datastore

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. Datastore.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.

Specified by:

deleteDocumentFromRevision in interface Datastore

Parameters:

rev - the DocumentRevision to be deleted

Returns:

a DocumentRevision - the deleted or "tombstone" document

Throws:

ConflictException - if the sourceRevisionId is not the current revision

See Also:

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

deleteDocument

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

Description copied from interface: Datastore

Delete all leaf revisions for the document

This is equivalent to calling deleteDocumentFromRevision on all leaf revisions

Specified by:

deleteDocument in interface Datastore

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:

Datastore.getEventBus(), Datastore.deleteDocumentFromRevision(DocumentRevision)