Document

Document

A Couchbase Lite Document.

Syntax


@interface CBLDocument : NSObject
class CBLDocument : NSObject
public class Document
public class Document
public class Document

Summary


Constants
String
The name of the event raised by a Document in response to an external change.
Events
The type of event raised when a Document changes. This event is not raised in response to local Document changes.
Properties
SavedRevision[]
Gets all of the current conflicting Revisions for the Document. If the Document is not in conflict, only the single current Revision will be returned.
SavedRevision
currentRevision { get; }
Gets the current/latest Revision.
String
If known, gets the Id of the current Revision, otherwise null.
Database
database { get; }
Gets the Database that owns this Document.
boolean
deleted { get; }
Gets if the Document is deleted.
Date
expirationDate { get; set; }
A date/time after which this document will be automatically purged.
String
id { get; }
Gets the Document's id.
SavedRevision[]
leafRevisions { get; }
Gets all of the leaf Revisions in the Document's Revision tree.
Object
model { get; set; }
Gets or sets a reference to an optional application-defined model object representing this Document.
Map<String, Object>
properties { get; }
Gets the properties of the current Revision of the Document.
SavedRevision[]
revisionHistory { get; }
Gets the Document's Revision history in forward order. Older, ancestor, Revisions are not guaranteed to have their properties available.
Map<String, Object>
userProperties { get; }
Gets the properties of the current Revision of the Document without any properties with keys prefixed with '_' (which contain Couchbase Lite data).
Methods
void
Adds a Document change delegate that will be called whenever the Document changes.
UnsavedRevision
Creates a new UnsavedRevision whose properties and attachments are initially identical to the current Revision.
void
delete()
Deletes the Document.
Object
getProperty(String key)
Returns the value of the property with the specified key.
SavedRevision
getRevision(String id)
Returns the Revision with the specified id if it exists, otherwise null.
void
purge()
Completely purges the Document from the local Database. This is different from delete in that it completely deletes everything related to the Document and does not replicate the deletes to other Databases.
boolean
putExistingRevisionWithProperties(Map<String, Object> properties, Map<String, Object> attachments, String[] revIDs, URL sourceURL, Error outError)
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.
SavedRevision
putProperties(Map<String, Object> properties)
Creates and saves a new Revision with the specified properties. To succeed the specified properties must include a '_rev' property whose value maches the current Revision's id.
void
Removes the specified delegate as a listener for the Document change event.
SavedRevision
update( UpdateDelegate delegate)
Creates and saves a new Revision by allowing the caller to update the existing properties. Conflicts are handled by calling the delegate again.
Delegates
void
ChangeDelegate(ChangeEvent event)
A delegate that can be used to listen for Document changes.
boolean
A delegate that can be used to update a Document.

Constants


String Change
The name of the event raised by a Document in response to an external change.

Syntax

extern NSString * const kCBLDocumentChangeNotification
let kCBLDocumentChangeNotification: String!
Not applicable.
Not applicable.
Not applicable.

Events


event ChangeEvent
The type of event raised when a Document changes. This event is not raised in response to local Document changes.

Syntax

@interface NSNotification : NSObject <NSCopying, NSCoding>
class NSNotification : NSObject, NSCopying, NSCoding
public interface ChangeEvent
public interface ChangeEvent
public class DocumentChangeEventArgs : EventArgs

Properties


SavedRevision[] conflictingRevisions { get; }
Gets all of the current conflicting Revisions for the Document. If the Document is not in conflict, only the single current Revision will be returned.

Errors

Returns an error if an issue occurs while getting the Revision history.

Syntax

-(NSArray *)getConflictingRevisions:(NSError **)outError
func getConflictingRevisions(outError: NSErrorPointer) -> [AnyObject]!
public List<SavedRevision> getConflictingRevisions() throws CouchbaseLiteException
public List<SavedRevision> getConflictingRevisions() throws CouchbaseLiteException
public IEnumerable<SavedRevision> ConflictingRevisions { get; }
SavedRevision currentRevision { get; }
Gets the current/latest Revision.

Syntax

@property (readonly) CBLSavedRevision * currentRevision
var currentRevision: CBLSavedRevision! { get }
public SavedRevision getCurrentRevision()
public SavedRevision getCurrentRevision()
public SavedRevision CurrentRevision { get; }
String currentRevisionId { get; }
If known, gets the Id of the current Revision, otherwise null.

Syntax

@property (readonly) NSString * currentRevisionID
var currentRevisionID: String! { get }
public String getCurrentRevisionId()
public String getCurrentRevisionId()
public String CurrentRevisionId { get; }
Database database { get; }
Gets the Database that owns this Document.

Syntax

@property (readonly) CBLDatabase * database
var database: CBLDatabase! { get }
public Database getDatabase()
public Database getDatabase()
public Database Database { get; }
boolean deleted { get; }
Gets if the Document is deleted.

Syntax

@property (readonly) BOOL isDeleted
var isDeleted: Bool { get }
public boolean isDeleted()
public boolean isDeleted()
public Boolean Deleted { get; }
Date expirationDate { get; set; }
A date/time after which this document will be automatically purged.

Syntax

@property (strong, nullable) NSDate* expirationDate;
var expirationDate: NSDate
public Date getExpirationDate()
public void setExpirationDate(Date date)
public Date getExpirationDate()
public void setExpirationDate(Date date)
public DateTime? GetExpirationDate()
public void ExpireAt(DateTime? expireTime)
String id { get; }
Gets the Document's id.

Syntax

@property (readonly) NSString * documentID
var doc: String! { get }
public String getId()
public String getId()
public String Id { get; }
SavedRevision[] leafRevisions { get; }
Gets all of the leaf Revisions in the Document's Revision tree.

Errors

Returns an error if an issue occurs while getting the leaf Revisions.

Syntax

-(NSArray *)getLeafRevisions:(NSError **)outError
func getLeafRevisions(outError: NSErrorPointer) -> [AnyObject]!
public List<SavedRevision> getLeafRevisions() throws CouchbaseLiteException
public List<SavedRevision> getLeafRevisions() throws CouchbaseLiteException
public IEnumerable<SavedRevision> LeafRevisions { get; }
Object model { get; set; }
Gets or sets a reference to an optional application-defined model object representing this Document.

Syntax

@property (weak) id modelObject
var modelObject: CBLDocumentModel!
public Object getModel()
public void setModel(Object model)
public Object getModel()
public void setModel(Object model)
public Object model { get; set; }
Map<String, Object> properties { get; }
Gets the properties of the current Revision of the Document.

Syntax

@property (readonly) NSDictionary * properties
var properties: [NSObject : AnyObject]! { get }
public Map<String, Object> getProperties()
public Map<String, Object> getProperties()
public Dictionary<String, Object> Properties { get; }
SavedRevision[] revisionHistory { get; }
Gets the Document's Revision history in forward order. Older, ancestor, Revisions are not guaranteed to have their properties available.

Errors

Returns an error if an issue occurs while getting the Revision history.

Syntax

-(NSArray *)getRevisionHistory:(NSError **)outError
func getRevisionHistory(outError: NSErrorPointer) -> [AnyObject]!
public List<SavedRevision> getRevisionHistory() throws CouchbaseLiteException
public List<SavedRevision> getRevisionHistory() throws CouchbaseLiteException
public IEnumerable<SavedRevision> RevisionHistory { get; }
Map<String, Object> userProperties { get; }
Gets the properties of the current Revision of the Document without any properties with keys prefixed with '_' (which contain Couchbase Lite data).

Syntax

@property (readonly) NSDictionary * userProperties
var userProperties: [NSObject : AnyObject]! { get }
public Map<String, Object> getUserProperties()
public Map<String, Object> getUserProperties()
public Dictionary<String, Object> UserProperties { get; }

Methods


void addChangeListener( ChangeDelegate delegate)
Adds a Document change delegate that will be called whenever the Document changes.

Parameters

delegate The Document change delegate to add.

Syntax

NSNotificationCenter -(void)addObserver:(id)notificationObserver selector:(SEL)notificationSelector name:kCBLDocumentChangeNotification object:(id)notificationSender
NSNotificationCenter func addObserver(observer: AnyObject, selector: Selector, name: kCBLDocumentChangeNotification, object: AnyObject?)
public void addChangeListener(ChangeListener listener)
public void addChangeListener(ChangeListener listener)
public event EventHandler<DocumentChangeEventArgs> Change
UnsavedRevision createRevision()
Creates a new UnsavedRevision whose properties and attachments are initially identical to the current Revision.

Returns

A new UnsavedRevision whose properties and attachments are initially identical to the current Revision.

Syntax

-(CBLUnsavedRevision *)newRevision
func newRevision() -> CBLUnsavedRevision!
public UnsavedRevision createRevision()
public UnsavedRevision createRevision()
public UnsavedRevision CreateRevision()
void delete()
Deletes the Document.

Errors

Returns an error if an issue occurs while deleting the Document.

Syntax

-(BOOL)deleteDocument:(NSError **)outError
func deleteDocument(outError: NSErrorPointer) -> Bool
public void delete() throws CouchbaseLiteException
public void delete() throws CouchbaseLiteException
public void Delete()
Object getProperty(String key)
Returns the value of the property with the specified key.

Parameters

key The key of the property value to return.

Returns

The value of the property with the specified key.

Syntax

-(id)propertyForKey:(NSString *)key
func propertyForKey(key: String!) -> AnyObject!
public Object getProperty(String key)
public Object getProperty(String key)
public Object GetProperty(String key)
SavedRevision getRevision(String id)
Returns the Revision with the specified id if it exists, otherwise null.

Parameters

id The Revision id.

Returns

The Revision with the specified id if it exists, otherwise null.

Syntax

-(CBLSavedRevision *)revisionWithID:(NSString *)revisionID
func revisionWithID(revisionID: String!) -> CBLSavedRevision
public SavedRevision getRevision(String id)
public SavedRevision getRevision(String id)
public SavedRevision GetRevision(String id)
void purge()
Completely purges the Document from the local Database. This is different from delete in that it completely deletes everything related to the Document and does not replicate the deletes to other Databases.

Errors

Returns an error if an issue occurs while purging the Document.

Syntax

-(BOOL)purgeDocument:(NSError **)outError
func purgeDocument(outError: NSErrorPointer) -> Bool
public void purge() throws CouchbaseLiteException
public void purge() throws CouchbaseLiteException
public void Purge()
boolean putExistingRevisionWithProperties(Map<String, Object> properties, Map<String, Object> attachments, String[] revIDs, URL sourceURL, Error outError)
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 (metadata like _id and _rev will be ignored)
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 and 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.)
outError Error information will be stored here if the insertion fails. @return YES on success, NO on failure.

Syntax

-(BOOL) putExistingRevisionWithProperties:(CBLJSONDict*)properties attachments:(nullable NSDictionary*)attachments revisionHistory:(NSArray*)revIDs fromURL:(NSURL*)sourceURL error:(NSError**)outError
func putExistingRevisionWithProperties(properties: CBLJSONDict, attachments: nullable NSDictionary, revisionHistory revIDs: [AnyObject], fromURL sourceURL: NSURL, error outError: NSError) -> Bool
public boolean putExistingRevision(Map<String, Object> properties, Map<String, Object> attachments, List<String> revIDs, URL sourceURL)
public boolean putExistingRevision(Map<String, Object> properties, Map<String, Object> attachments, List<String> revIDs, URL sourceURL)
public bool PutExistingRevision(IDictionary<string, object> properties, IDictionary<string, Stream> attachments, IList<string> revisionHistory, Uri sourceUri)
SavedRevision putProperties(Map<String, Object> properties)
Creates and saves a new Revision with the specified properties. To succeed the specified properties must include a '_rev' property whose value maches the current Revision's id.

Parameters

properties The properties to set on the new Revision.

Returns

The new SavedRevision.

Errors

Returns an error if an error occurs while creating or saving the new Revision.

Syntax

-(CBLSavedRevision *)putProperties:(NSDictionary *)properties error:(NSError **)outError
func putProperties(properties: [NSObject : AnyObject]!, error: NSErrorPointer) -> CBLSavedRevision!
public SavedRevision putProperties(Map<String, Object> properties) throws CouchbaseLiteException
public SavedRevision putProperties(Map<String, Object> properties) throws CouchbaseLiteException
public SavedRevision PutProperties(Dictionary<String, Object> properties)
void removeChangeListener( ChangeDelegate delegate)
Removes the specified delegate as a listener for the Document change event.

Parameters

delegate The Document change delegate to remove.

Syntax

NSNotificationCenter -(void)removeObserver:(id)observer name:kCBLDocumentChangeNotification object:(id)anObject
NSNotificationCenter func removeObserver:(observer: AnyObject, name: kCBLDocumentChangeNotification, object: AnyObject?)
public void removeChangeListener(ChangeListener listener)
public void removeChangeListener(ChangeListener listener)
public event EventHandler<DocumentChangeEventArgs> Change
SavedRevision update( UpdateDelegate delegate)
Creates and saves a new Revision by allowing the caller to update the existing properties. Conflicts are handled by calling the delegate again.

Parameters

delegate The delegate that will be called to update the new Revision's properties.

Returns

The new SavedRevision, or null on error or cancellation.

Errors

Returns an error if an error occurs while creating or saving the new Revision.

Syntax

-(CBLRevision *)update:(BOOL(^)(CBLUnsavedRevision *))block error:(NSError **)outError
func update(block: ((CBLUnsavedRevision!) -> Bool)!, error: NSErrorPointer) -> CBLSavedRevision!
public SavedRevision update(DocumentUpdater documentUpdater) throws CouchbaseLiteException
public SavedRevision update(DocumentUpdater documentUpdater) throws CouchbaseLiteException
public SavedRevision Update(UpdateDelegate updateDelegate)

Delegates


void ChangeDelegate(ChangeEvent event)
A delegate that can be used to listen for Document changes.

Parameters

event The Document change event.

Syntax

-(void)documentChangeNotification:(NSNotification *)notification
func documentChangeNotification(notification: NSNotification)
public interface ChangeListener {
    void changed(ChangeEvent event);
}
public interface ChangeListener {
    void changed(ChangeEvent event);
}
Not applicable.
boolean UpdateDelegate( UnsavedRevision revision)
A delegate that can be used to update a Document.

Parameters

revision The UnsavedRevision to update.

Returns

True if the UnsavedRevision should be saved, otherwise false.

Syntax

^BOOL(CBLUnsavedRevision * revision) {
    ...
}
{ (revision: CBLUnsavedRevision!) -> Bool in
}
interface DocumentUpdater {
    boolean update(UnsavedRevision revision);
}
interface DocumentUpdater {
    boolean update(UnsavedRevision revision);
}
public delegate Boolean UpdateDelegate(UnsavedRevision revision);