com.couchbase.lite.store

Interface Store

All Known Implementing Classes:

SQLiteStore

public interface Store

Abstraction of database storage. Every Database has an instance of this, and acts as that instance's delegate.

Method Summary

Modifier and Type	Method and Description
RevisionInternal	add(java.lang.String docID, java.lang.String prevRevID, java.util.Map<java.lang.String,java.lang.Object> properties, boolean deleting, boolean allowConflict, StorageValidation validationBlock, Status outStatus) Creates a new revision of a document.
RevisionList	changesSince(long lastSequence, ChangesOptions options, ReplicationFilter filter, java.util.Map<java.lang.String,java.lang.Object> filterParams) Returns all database changes with sequences greater than `lastSequence`.
void	close() Closes storage before it's deallocated.
void	compact() Explicitly compacts document storage.
boolean	databaseExists(java.lang.String directory) Preflight to see if a database file exists in this directory.
long	expirationOfDocument(java.lang.String docID) Returns a document's expiration date as a Unix timestamp, or 0 for no expiration.
java.util.Set<BlobKey>	findAllAttachmentKeys() Returns the keys (unique IDs) of all attachments referred to by existing un-compacted Each revision key is an NSData object containing a CBLBlobKey (raw SHA-1 getDigest) derived from the "digest" property of the attachment's metadata.
java.lang.String	findCommonAncestorOf(RevisionInternal rev, java.util.List<java.lang.String> revIDs) Returns the most recent member of revIDs that appears in rev's ancestry.
int	findMissingRevisions(RevisionList touchRevs) Looks for each given revision in the local database, and removes each one found from the list.
void	forceInsert(RevisionInternal inRev, java.util.List<java.lang.String> history, StorageValidation validationBlock, java.net.URL source) Inserts an already-existing revision (with its revID), plus its ancestry, into a document.
java.util.Map<java.lang.String,java.lang.Object>	getAllDocs(QueryOptions options) Iterates over all documents in the database, according to the given query options.
RevisionList	getAllRevisions(java.lang.String docID, boolean onlyCurrent) Returns all the known revisions (or all current/conflicting revisions) of a document.
java.util.List<java.lang.String>	getAllViewNames() Returns the names of all existing views in the database.
boolean	getAutoCompact()
StoreDelegate	getDelegate()
RevisionInternal	getDocument(java.lang.String docID, java.lang.String revID, boolean withBody, Status outStatus) Retrieves a document revision by ID.
int	getDocumentCount() The number of (undeleted) documents in the database.
java.lang.String	getInfo(java.lang.String key) Returns the value assigned to the given key by -setInfo:forKey:.
long	getLastSequence() The last sequence number allocated to a revision.
RevisionInternal	getLocalDocument(java.lang.String docID, java.lang.String revID) Returns the contents of a local document.
int	getMaxRevTreeDepth()
RevisionInternal	getParentRevision(RevisionInternal rev) Retrieves the parent revision of a revision, or returns nil if there is no parent.
java.util.List<java.lang.String>	getPossibleAncestorRevisionIDs(RevisionInternal rev, int limit, java.util.concurrent.atomic.AtomicBoolean outHaveBodies, boolean withBodiesOnly) Returns IDs of local revisions of the same document, that have a lower generation number.
java.util.List<RevisionInternal>	getRevisionHistory(RevisionInternal rev) Returns the given revision's list of direct ancestors (as CBL_Revision objects) in _reverse_ chronological order, starting with the revision itself.
ViewStore	getViewStorage(java.lang.String name, boolean create) Instantiates storage for a view.
boolean	inTransaction() Is a transaction active?
RevisionInternal	loadRevisionBody(RevisionInternal rev) Loads the body of a revision.
long	nextDocumentExpiry() Returns the next time at which a document will expire.
void	open() Opens storage.
int	purgeExpiredDocuments() Triggers purging of documents whose expiration time has passed.
java.util.Map<java.lang.String,java.lang.Object>	purgeRevisions(java.util.Map<java.lang.String,java.util.List<java.lang.String>> docsToRevs) Purges specific revisions, which deletes them completely from the local database _without_ adding a "tombstone" revision.
RevisionInternal	putLocalRevision(RevisionInternal revision, java.lang.String prevRevID, boolean obeyMVCC) Creates / updates / deletes a local document.
boolean	runInTransaction(TransactionalTask task) Executes the block within a database transaction.
void	setAutoCompact(boolean value) Whether the database storage should automatically (periodically) be compacted.
void	setDelegate(StoreDelegate delegate) The delegate object, which in practice is the CBLDatabase.
boolean	setExpirationOfDocument(long timestamp, java.lang.String docID) Sets a document's expiration to a Unix timestamp, or 0 for no expiration.
long	setInfo(java.lang.String key, java.lang.String info) Stores an arbitrary string under an arbitrary key, persistently.
void	setMaxRevTreeDepth(int maxRevTreeDepth) The maximum depth a document's revision tree should grow to; beyond that, it should be pruned.

Method Detail

databaseExists

boolean databaseExists(java.lang.String directory)

Preflight to see if a database file exists in this directory. Called _before_ open() method!

open

void open()
   throws CouchbaseLiteException

Opens storage. Files will be created in the directory, which must already exist.

Throws:

CouchbaseLiteException

close

void close()

Closes storage before it's deallocated.

setDelegate

void setDelegate(StoreDelegate delegate)

The delegate object, which in practice is the CBLDatabase.

getDelegate

StoreDelegate getDelegate()

setMaxRevTreeDepth

void setMaxRevTreeDepth(int maxRevTreeDepth)

The maximum depth a document's revision tree should grow to; beyond that, it should be pruned. This will be set soon after the -openInDirectory call.

getMaxRevTreeDepth

int getMaxRevTreeDepth()

setAutoCompact

void setAutoCompact(boolean value)

Whether the database storage should automatically (periodically) be compacted. This will be set soon after the open() method call.

getAutoCompact

boolean getAutoCompact()

setInfo

long setInfo(java.lang.String key,
             java.lang.String info)

Stores an arbitrary string under an arbitrary key, persistently.

getInfo

java.lang.String getInfo(java.lang.String key)

Returns the value assigned to the given key by -setInfo:forKey:.

getDocumentCount

int getDocumentCount()

The number of (undeleted) documents in the database.

getLastSequence

long getLastSequence()

The last sequence number allocated to a revision.

inTransaction

boolean inTransaction()

Is a transaction active?

compact

void compact()
      throws CouchbaseLiteException

Explicitly compacts document storage.

Throws:

CouchbaseLiteException

runInTransaction

boolean runInTransaction(TransactionalTask task)

Executes the block within a database transaction. If the block returns a non-OK status, the transaction is aborted/rolled back. If the block returns kCBLStatusDBBusy, the block will also be retried after a short delay; if 10 retries all fail, the kCBLStatusDBBusy will be returned to the caller. Any exception raised by the block will be caught and treated as kCBLStatusException.

getDocument

RevisionInternal getDocument(java.lang.String docID,
                             java.lang.String revID,
                             boolean withBody,
                             Status outStatus)

Retrieves a document revision by ID.

Parameters:

docID - The document ID

revID - The revision ID; may be nil, meaning "the current revision".

withBody - If false, revision's body won't be loaded

outStatus -

Returns:

The revision, or nil if not found.

loadRevisionBody

RevisionInternal loadRevisionBody(RevisionInternal rev)
                           throws CouchbaseLiteException

Loads the body of a revision. On entry, rev.docID and rev.revID will be valid. On success, rev.body and rev.sequence will be valid.

Throws:

CouchbaseLiteException

getParentRevision

RevisionInternal getParentRevision(RevisionInternal rev)

Retrieves the parent revision of a revision, or returns nil if there is no parent.

getRevisionHistory

java.util.List<RevisionInternal> getRevisionHistory(RevisionInternal rev)

Returns the given revision's list of direct ancestors (as CBL_Revision objects) in _reverse_ chronological order, starting with the revision itself.

getAllRevisions

RevisionList getAllRevisions(java.lang.String docID,
                             boolean onlyCurrent)

Returns all the known revisions (or all current/conflicting revisions) of a document.

Parameters:

docID - The document ID

onlyCurrent - If true, only leaf revisions (whether or not deleted) should be returned.

Returns:

An array of all available revisions of the document.

getPossibleAncestorRevisionIDs

java.util.List<java.lang.String> getPossibleAncestorRevisionIDs(RevisionInternal rev,
                                                                int limit,
                                                                java.util.concurrent.atomic.AtomicBoolean outHaveBodies,
                                                                boolean withBodiesOnly)

Returns IDs of local revisions of the same document, that have a lower generation number. If possible, returns only leaf revisions; if none match, returns non-leaves.

Parameters:

rev - The revision to look for ancestors of. Only its docID and revID are used.

limit - The maximum number of results to return, or if 0, unlimited.

outHaveBodies - On return, if not NULL, then *outHaveBodies will be YES if all the revisions returned have their JSON bodies available, otherwise NO.

withBodiesOnly - Specifies whether or not to search for non-empty and non-removed revisions.

Returns:

An array of revIDs of existing revisions that could be ancestors of `rev`.

findCommonAncestorOf

java.lang.String findCommonAncestorOf(RevisionInternal rev,
                                      java.util.List<java.lang.String> revIDs)

Returns the most recent member of revIDs that appears in rev's ancestry. In other words: Look at the revID properties of rev, its parent, grandparent, etc. As soon as you find a revID that's in the revIDs array, stop and return that revID. If no match is found, return nil.

findMissingRevisions

int findMissingRevisions(RevisionList touchRevs)

Looks for each given revision in the local database, and removes each one found from the list. On return, therefore, `revs` will contain only the revisions that don't exist locally.

findAllAttachmentKeys

java.util.Set<BlobKey> findAllAttachmentKeys()
                                      throws CouchbaseLiteException

Returns the keys (unique IDs) of all attachments referred to by existing un-compacted Each revision key is an NSData object containing a CBLBlobKey (raw SHA-1 getDigest) derived from the "digest" property of the attachment's metadata.

Throws:

CouchbaseLiteException

getAllDocs

java.util.Map<java.lang.String,java.lang.Object> getAllDocs(QueryOptions options)
                                                     throws CouchbaseLiteException

Iterates over all documents in the database, according to the given query options.

Throws:

CouchbaseLiteException

changesSince

RevisionList changesSince(long lastSequence,
                          ChangesOptions options,
                          ReplicationFilter filter,
                          java.util.Map<java.lang.String,java.lang.Object> filterParams)

Returns all database changes with sequences greater than `lastSequence`.

Parameters:

lastSequence - The sequence number to start _after_

options - Options for ordering, document content, etc.

filter - If non-nil, will be called on every revision, and those for which it returns NO will be skipped.

Returns:

The list of CBL_Revisions

add

RevisionInternal add(java.lang.String docID,
                     java.lang.String prevRevID,
                     java.util.Map<java.lang.String,java.lang.Object> properties,
                     boolean deleting,
                     boolean allowConflict,
                     StorageValidation validationBlock,
                     Status outStatus)
              throws CouchbaseLiteException

Creates a new revision of a document. On success, before returning the new CBL_Revision, the implementation will also call the delegate's -databaseStorageChanged: method to give it more details about the change.

Parameters:

docID - The document ID, or nil if an ID should be generated at random.

prevRevID - The parent revision ID, or nil if creating a new document.

properties - The new revision's properties. (Metadata other than "_attachments" ignored.)

deleting - YES if this revision is a deletion.

allowConflict - YES if this operation is allowed to create a conflict; otherwise a 409, status will be returned if the parent revision is not a leaf.

validationBlock - If non-nil, this block will be called before the revision is added. It's given the parent revision, with its properties if available, and can reject the operation by returning an error status.

outStatus - On return a status will be stored here. Note that on success, the status should be 201 for a created revision but 200 for a deletion.

Returns:

The new revision, with its revID and sequence filled in, or nil on error.

Throws:

CouchbaseLiteException

forceInsert

void forceInsert(RevisionInternal inRev,
                 java.util.List<java.lang.String> history,
                 StorageValidation validationBlock,
                 java.net.URL source)
          throws CouchbaseLiteException

Inserts an already-existing revision (with its revID), plus its ancestry, into a document. This is called by the pull replicator to add the revisions received from the server. On success, the implementation will also call the delegate's -databaseStorageChanged: method to give it more details about the change.

Parameters:

inRev - The revision to insert. Its revID will be non-nil.

history - The revIDs of the revision and its ancestors, in reverse chronological order. The first item will be equal to inRev.revID.

validationBlock - If non-nil, this block will be called before the revision is added. It's given the parent revision, with its properties if available, and can reject the operation by returning an error status.

source - The URL of the remote database this was pulled from, or nil if it's local. (This will be used to create the CBLDatabaseChange object sent to the delegate.)

Throws:

CouchbaseLiteException

purgeRevisions

java.util.Map<java.lang.String,java.lang.Object> purgeRevisions(java.util.Map<java.lang.String,java.util.List<java.lang.String>> docsToRevs)

Purges specific revisions, which deletes them completely from the local database _without_ adding a "tombstone" revision. It's as though they were never there.

Parameters:

docsToRevs - A dictionary mapping document IDs to arrays of revision IDs. The magic revision ID "*" means "all revisions", indicating that the document should be removed entirely from the database.

Returns:

On success will point to an NSDictionary with the same form as docsToRev, containing the doc/revision IDs that were actually removed.

Throws:

CouchbaseLiteException

expirationOfDocument

long expirationOfDocument(java.lang.String docID)

Returns a document's expiration date as a Unix timestamp, or 0 for no expiration.

setExpirationOfDocument

boolean setExpirationOfDocument(long timestamp,
                                java.lang.String docID)

Sets a document's expiration to a Unix timestamp, or 0 for no expiration.

nextDocumentExpiry

long nextDocumentExpiry()

Returns the next time at which a document will expire.

purgeExpiredDocuments

int purgeExpiredDocuments()

Triggers purging of documents whose expiration time has passed.

getViewStorage

ViewStore getViewStorage(java.lang.String name,
                         boolean create)
                  throws CouchbaseLiteException

Instantiates storage for a view.

Parameters:

name - The name of the view

create - If YES, the view should be created; otherwise it must already exist

Returns:

Storage for the view, or nil if create=NO and it doesn't exist.

Throws:

CouchbaseLiteException

getAllViewNames

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

Returns the names of all existing views in the database.

getLocalDocument

RevisionInternal getLocalDocument(java.lang.String docID,
                                  java.lang.String revID)

Returns the contents of a local document. Note that local documents do not have revision histories, so only the current revision exists.

Parameters:

docID - The document ID, which will begin with "_local/"

revID - revID The revision ID, or nil to return the current revision.

Returns:

A revision containing the body of the document, or nil if not found.

putLocalRevision

RevisionInternal putLocalRevision(RevisionInternal revision,
                                  java.lang.String prevRevID,
                                  boolean obeyMVCC)
                           throws CouchbaseLiteException

Creates / updates / deletes a local document.

Parameters:

revision - The new revision to save. Its docID must be set but the revID is ignored. If its .deleted property is YES, it's a deletion.

prevRevID - The revision ID to replace

obeyMVCC - If YES, the prevRevID must match the document's current revID (or nil if the document doesn't exist) or a 409 error is returned. If NO, the prevRevID is ignored and the operation always succeeds.

Returns:

The new revision, with revID filled in, or nil on error.

Throws:

CouchbaseLiteException