com.couchbase.lite

Class Document

java.lang.Object

com.couchbase.lite.Document

public class Document
extends java.lang.Object

A CouchbaseLite document.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Document.ChangeEvent The type of event raised when a Document changes.
static interface	Document.ChangeListener A delegate that can be used to listen for Document changes.
static interface	Document.DocumentUpdater A delegate that can be used to update a Document.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	TAG

Constructor Summary

Constructors

Constructor and Description
Document(Database database, java.lang.String documentId) Constructor

Method Summary

Modifier and Type	Method and Description
void	addChangeListener(Document.ChangeListener changeListener)
UnsavedRevision	createRevision() Creates an unsaved new revision whose parent is the currentRevision, or which will be the first revision if the document doesn't exist yet.
boolean	delete() Deletes this document by adding a deletion revision.
protected void	forgetCurrentRevision()
java.util.List<SavedRevision>	getConflictingRevisions() Returns all the current conflicting revisions of the document.
SavedRevision	getCurrentRevision() Get the current revision
java.lang.String	getCurrentRevisionId() Get the ID of the current revision
Database	getDatabase() Get the document's owning database.
java.util.Date	getExpirationDate() A date/time after which this document will be automatically purged.
java.lang.String	getId() Get the document's ID
java.util.List<SavedRevision>	getLeafRevisions() Returns all the leaf revisions in the document's revision tree, including deleted revisions (i.e.
protected java.util.List<SavedRevision>	getLeafRevisions(boolean includeDeleted)
java.util.Map<java.lang.String,java.lang.Object>	getProperties() The contents of the current revision of the document.
java.lang.Object	getProperty(java.lang.String key) Shorthand for getProperties().get(key)
SavedRevision	getRevision(java.lang.String revID) The revision with the specified ID.
protected SavedRevision	getRevisionFromRev(RevisionInternal internalRevision)
java.util.List<SavedRevision>	getRevisionHistory() Returns the document's history as an array of CBLRevisions.
java.util.Map<java.lang.String,java.lang.Object>	getUserProperties() The user-defined properties, without the ones reserved by CouchDB.
boolean	isDeleted() Is this document deleted? (That is, does its current revision have the '_deleted' property?)
static boolean	isValidDocumentId(java.lang.String id) in CBLDatabase+Insertion.m + (BOOL) isValidDocumentID: (NSString*)str
protected void	loadCurrentRevisionFrom(QueryRow row)
protected java.util.Map<java.lang.String,java.lang.Object>	propertiesToInsert(java.util.Map<java.lang.String,java.lang.Object> properties)
void	purge() Purges this document from the database; this is more than deletion, it forgets entirely about it.
boolean	putExistingRevision(java.util.Map<java.lang.String,java.lang.Object> properties, java.util.Map<java.lang.String,java.lang.Object> attachments, java.util.List<java.lang.String> revIDs, java.net.URL sourceURL) Adds an existing revision copied from another database.
SavedRevision	putProperties(java.util.Map<java.lang.String,java.lang.Object> properties) Saves a new revision.
protected SavedRevision	putProperties(java.util.Map<java.lang.String,java.lang.Object> properties, java.lang.String prevID, boolean allowConflict)
void	removeChangeListener(Document.ChangeListener changeListener)
protected void	revisionAdded(DocumentChange change, boolean notify) Notification from the CBLDatabase that a (current, winning) revision has been added
void	setExpirationDate(java.util.Date date)
SavedRevision	update(Document.DocumentUpdater updater) Saves a new revision by letting the caller update the existing properties.

Methods inherited from class java.lang.Object

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

Field Detail

TAG

public static final java.lang.String TAG

See Also:

Constant Field Values

Constructor Detail

Document

public Document(Database database,
                java.lang.String documentId)

Constructor

Parameters:

database - The document's owning database

documentId - The document's ID

Method Detail

getDatabase

public Database getDatabase()

Get the document's owning database.

getId

public java.lang.String getId()

Get the document's ID

getExpirationDate

public java.util.Date getExpirationDate()

A date/time after which this document will be automatically purged.

setExpirationDate

public void setExpirationDate(java.util.Date date)

addChangeListener

public void addChangeListener(Document.ChangeListener changeListener)

removeChangeListener

public void removeChangeListener(Document.ChangeListener changeListener)

isDeleted

public boolean isDeleted()

Is this document deleted? (That is, does its current revision have the '_deleted' property?)

Returns:

boolean to indicate whether deleted or not

getCurrentRevisionId

public java.lang.String getCurrentRevisionId()

Get the ID of the current revision

getCurrentRevision

public SavedRevision getCurrentRevision()

Get the current revision

getRevisionHistory

public java.util.List<SavedRevision> getRevisionHistory()
                                                 throws CouchbaseLiteException

Returns the document's history as an array of CBLRevisions. (See SavedRevision's method.)

Returns:

document's history

Throws:

CouchbaseLiteException

getConflictingRevisions

public java.util.List<SavedRevision> getConflictingRevisions()
                                                      throws CouchbaseLiteException

Returns all the current conflicting revisions of the document. If the document is not in conflict, only the single current revision will be returned.

Returns:

all current conflicting revisions of the document

Throws:

CouchbaseLiteException

getLeafRevisions

public java.util.List<SavedRevision> getLeafRevisions()
                                               throws CouchbaseLiteException

Returns all the leaf revisions in the document's revision tree, including deleted revisions (i.e. previously-resolved conflicts.)

Returns:

all the leaf revisions in the document's revision tree

Throws:

CouchbaseLiteException

getProperties

public java.util.Map<java.lang.String,java.lang.Object> getProperties()

The contents of the current revision of the document. This is shorthand for self.currentRevision.properties. Any keys in the dictionary that begin with "_", such as "_id" and "_rev", contain CouchbaseLite metadata.

Returns:

contents of the current revision of the document. null if currentRevision is null

getUserProperties

public java.util.Map<java.lang.String,java.lang.Object> getUserProperties()

The user-defined properties, without the ones reserved by CouchDB. This is based on -properties, with every key whose name starts with "_" removed.

Returns:

user-defined properties, without the ones reserved by CouchDB.

delete

public boolean delete()
               throws CouchbaseLiteException

Deletes this document by adding a deletion revision. This will be replicated to other databases.

Returns:

boolean to indicate whether deleted or not

Throws:

CouchbaseLiteException

purge

public void purge()
           throws CouchbaseLiteException

Purges this document from the database; this is more than deletion, it forgets entirely about it. The purge will NOT be replicated to other databases.

Throws:

CouchbaseLiteException

getRevision

public SavedRevision getRevision(java.lang.String revID)

The revision with the specified ID.

Parameters:

revID - the revision ID

Returns:

the SavedRevision object

createRevision

public UnsavedRevision createRevision()

Creates an unsaved new revision whose parent is the currentRevision, or which will be the first revision if the document doesn't exist yet. You can modify this revision's properties and attachments, then save it. No change is made to the database until/unless you save the new revision.

Returns:

the newly created revision

getProperty

public java.lang.Object getProperty(java.lang.String key)

Shorthand for getProperties().get(key)

putProperties

public SavedRevision putProperties(java.util.Map<java.lang.String,java.lang.Object> properties)
                            throws CouchbaseLiteException

Saves a new revision. The properties dictionary must have a "_rev" property whose ID matches the current revision's (as it will if it's a modified copy of this document's .properties property.)

Parameters:

properties - the contents to be saved in the new revision

Returns:

a new SavedRevision

Throws:

CouchbaseLiteException

update

public SavedRevision update(Document.DocumentUpdater updater)
                     throws CouchbaseLiteException

Saves a new revision by letting the caller update the existing properties. This method handles conflicts by retrying (calling the block again). The DocumentUpdater implementation should modify the properties of the new revision and return YES to save or NO to cancel. Be careful: the DocumentUpdater can be called multiple times if there is a conflict!

Parameters:

updater - the callback DocumentUpdater implementation. Will be called on each attempt to save. Should update the given revision's properties and then return YES, or just return NO to cancel.

Returns:

The new saved revision, or null on cancellation.

Throws:

CouchbaseLiteException

putExistingRevision

public boolean putExistingRevision(java.util.Map<java.lang.String,java.lang.Object> properties,
                                   java.util.Map<java.lang.String,java.lang.Object> attachments,
                                   java.util.List<java.lang.String> revIDs,
                                   java.net.URL sourceURL)
                            throws CouchbaseLiteException

Adds an existing revision copied from another database. Unlike a normal insertion, this does not assign a new revision ID; instead the revision's ID must be given. The revision's history (ancestry) must be given, which can put it anywhere in the revision tree. It's not an error if the revision already exists locally; it will just be ignored. This is not an operation that clients normally perform; it's used by the replicator. You might want to use it if you're pre-loading a database with canned content, or if you're implementing some new kind of replicator that transfers revisions from another database.

Parameters:

properties - The properties of the revision (_id and _rev will be ignored, but _deleted and _attachments are recognized.)

attachments - A dictionary providing attachment bodies. The keys are the attachment names (matching the keys in the properties' `_attachments` dictionary) and the values are the attachment bodies as NSData or NSURL.

revIDs - The revision history in the form of an array of revision-ID strings, in reverse chronological order. The first item must be the new revision's ID. Following items are its parent's ID, etc.

sourceURL - The URL of the database this revision came from, if any. (This value shows up in the CBLDatabaseChange triggered by this insertion, and can help clients decide whether the change is local or not.)

Returns:

true on success, false on failure.

Throws:

CouchbaseLiteException - Error information will be thrown if the insertion fails.

isValidDocumentId

public static boolean isValidDocumentId(java.lang.String id)

in CBLDatabase+Insertion.m + (BOOL) isValidDocumentID: (NSString*)str

getLeafRevisions

protected java.util.List<SavedRevision> getLeafRevisions(boolean includeDeleted)
                                                  throws CouchbaseLiteException

Throws:

CouchbaseLiteException

propertiesToInsert

protected java.util.Map<java.lang.String,java.lang.Object> propertiesToInsert(java.util.Map<java.lang.String,java.lang.Object> properties)
                                                                       throws CouchbaseLiteException

Throws:

CouchbaseLiteException

putProperties

protected SavedRevision putProperties(java.util.Map<java.lang.String,java.lang.Object> properties,
                                      java.lang.String prevID,
                                      boolean allowConflict)
                               throws CouchbaseLiteException

Throws:

CouchbaseLiteException

getRevisionFromRev

protected SavedRevision getRevisionFromRev(RevisionInternal internalRevision)

loadCurrentRevisionFrom

protected void loadCurrentRevisionFrom(QueryRow row)

revisionAdded

protected void revisionAdded(DocumentChange change,
                             boolean notify)

Notification from the CBLDatabase that a (current, winning) revision has been added

forgetCurrentRevision

protected void forgetCurrentRevision()