Package com.couchbase.lite

Class Collection

java.lang.Object

com.couchbase.lite.internal.BaseCollection

com.couchbase.lite.Collection

All Implemented Interfaces:

com.couchbase.lite.internal.Listenable<CollectionChange,CollectionChangeListener>, AutoCloseable

public final class Collection
extends com.couchbase.lite.internal.BaseCollection
implements com.couchbase.lite.internal.Listenable<CollectionChange,CollectionChangeListener>, AutoCloseable

A Collection is a container for documents similar to aa table in a relational database. Collections are grouped into namespaces called `scope`s and have a unique name within that scope.

Every database contains a default collection named "_default" (the constant Collection.DEFAULT_NAME) in the default scope (also named "_default", the constant Scope.DEFAULT_NAME)

While creating a new collection requires the name of the collection and the name of its scope, there are convenience methods that take only the name of the collection and create the collection in the default scope.

The naming rules for collections and scopes are as follows:

• Must be between 1 and 251 characters in length.
• Can only contain the characters A-Z, a-z, 0-9, and the symbols _, -, and %.
• Cannot start with _ or %.
• Both scope and collection names are case sensitive.

Collection objects are only valid during the time the database that contains them is open. An attempt to use a collection that belongs to a closed database will throw an IllegalStateException. An application can hold references to multiple instances of a single database. Under these circumstances, it is possible that a collection will be deleted in one instance before an attempt to use it in another. Such an attempt will also cause an IllegalStateException to be thrown.

Collections are AutoCloseable. While garbage collection will manage them correctly, developers are strongly encouraged to to use them in try-with-resources blocks or to close them explicitly, after use.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DEFAULT_NAME

Method Summary

Modifier and Type	Method	Description
ListenerToken	addChangeListener(CollectionChangeListener listener)	Add a change listener to listen to change events occurring to any documents in the collection.
ListenerToken	addChangeListener(Executor executor, CollectionChangeListener listener)	Add a change listener to listen to change events occurring to any documents in the collection.
ListenerToken	addDocumentChangeListener(String id, DocumentChangeListener listener)	Add a change listener to listen to change events occurring to a document of the given document id.
ListenerToken	addDocumentChangeListener(String id, Executor executor, DocumentChangeListener listener)	Adds a change listener for the changes that occur to the specified document with an executor on which the changes will be posted to the listener.
void	close()
void	createIndex(String name, Index index)	Add an index to the collection.
void	createIndex(String name, IndexConfiguration config)	Add an index to the collection.
void	delete(Document document)	Delete a document from the collection.
boolean	delete(Document document, ConcurrencyControl concurrencyControl)	Delete a document from the collection with a specified concurrency control.
void	deleteIndex(String name)	Delete the named index from the collection.
boolean	equals(Object o)
long	getCount()	The number of documents in the collection.
Document	getDocument(String id)	Gets an existing Document object with the given ID.
Date	getDocumentExpiration(String id)	Get the expiration date set to the document of the given id.
Set<String>	getIndexes()	Get a list of the names of indices in the collection.
String	getName()	Return the collection name
Scope	getScope()	Get scope
int	hashCode()
void	purge(Document document)	When purging a document, the collection instance of the document and this collection instance must be the same, otherwise, the InvalidParameter error will be thrown.
void	purge(String id)	Purge a document by id from the collection.
void	save(MutableDocument document)	Save a document into the collection.
boolean	save(MutableDocument document, ConcurrencyControl concurrencyControl)	Save a document into the collection with a specified concurrency control.
boolean	save(MutableDocument document, ConflictHandler conflictHandler)	Save a document into the collection with a specified conflict handler.
void	setDocumentExpiration(String id, Date expiration)	Set an expiration date to the document of the given id.
String	toString()

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Details

DEFAULT_NAME

public static final String DEFAULT_NAME

See Also:

• Constant Field Values

Method Details

getScope

@NonNull
public Scope getScope()

Get scope

getName

@NonNull
public String getName()

Return the collection name

getCount

public long getCount()

The number of documents in the collection.

getDocument

@Nullable
public Document getDocument(@NonNull
 String id)
                     throws CouchbaseLiteException

Gets an existing Document object with the given ID. If the document with the given ID doesn't exist in the collection, the value returned will be null.

Parameters:

id - the document id

Returns:

the Document object or null

Throws:

CouchbaseLiteException - if the database is closed, the collection has been deleted, etc.

save

public void save(@NonNull
 MutableDocument document)
          throws CouchbaseLiteException

Save a document into the collection. The default concurrency control, lastWriteWins, will be used when there is conflict during save.

When saving a document that already belongs to a collection, the collection instance of the document and this collection instance must be the same, otherwise, the InvalidParameter error will be thrown.

Throws:

CouchbaseLiteException

save

public boolean save(@NonNull
 MutableDocument document,
 @NonNull
 ConcurrencyControl concurrencyControl)
             throws CouchbaseLiteException

Save a document into the collection with a specified concurrency control. When specifying the failOnConflict concurrency control, and conflict occurred, the save operation will fail with 'false' value returned. When saving a document that already belongs to a collection, the collection instance of the document and this collection instance must be the same, otherwise, the InvalidParameter error will be thrown.

Throws:

CouchbaseLiteException

save

public boolean save(@NonNull
 MutableDocument document,
 @NonNull
 ConflictHandler conflictHandler)
             throws CouchbaseLiteException

Save a document into the collection with a specified conflict handler. The specified conflict handler will be called if there is conflict during save. If the conflict handler returns 'false', the save operation will be canceled with 'false' value returned.

When saving a document that already belongs to a collection, the collection instance of the document and this collection instance must be the same, otherwise, the InvalidParameter error will be thrown.

Throws:

CouchbaseLiteException

delete

public void delete(@NonNull
 Document document)
            throws CouchbaseLiteException

Delete a document from the collection. The default concurrency control, lastWriteWins, will be used when there is conflict during delete. If the document doesn't exist in the collection, the NotFound error will be thrown.

When deleting a document that already belongs to a collection, the collection instance of the document and this collection instance must be the same, otherwise, the InvalidParameter error will be thrown.

Throws:

CouchbaseLiteException

delete

public boolean delete(@NonNull
 Document document,
 @NonNull
 ConcurrencyControl concurrencyControl)
               throws CouchbaseLiteException

Delete a document from the collection with a specified concurrency control. When specifying the failOnConflict concurrency control, and conflict occurred, the delete operation will fail with 'false' value returned.

When deleting a document, the collection instance of the document and this collection instance must be the same, otherwise, the InvalidParameter error will be thrown.

Throws:

CouchbaseLiteException

purge

public void purge(@NonNull
 Document document)
           throws CouchbaseLiteException

When purging a document, the collection instance of the document and this collection instance must be the same, otherwise, the InvalidParameter error will be thrown.

Throws:

CouchbaseLiteException

purge

public void purge(@NonNull
 String id)
           throws CouchbaseLiteException

Purge a document by id from the collection. If the document doesn't exist in the collection, the NotFound error will be thrown.

Throws:

CouchbaseLiteException

setDocumentExpiration

public void setDocumentExpiration(@NonNull
 String id,
 @Nullable
 Date expiration)
                           throws CouchbaseLiteException

Set an expiration date to the document of the given id. Setting a nil date will clear the expiration.

Throws:

CouchbaseLiteException

getDocumentExpiration

@Nullable
public Date getDocumentExpiration(@NonNull
 String id)
                           throws CouchbaseLiteException

Get the expiration date set to the document of the given id.

Throws:

CouchbaseLiteException

addChangeListener

@NonNull
public ListenerToken addChangeListener(@NonNull
 CollectionChangeListener listener)
                                throws CouchbaseLiteException

Add a change listener to listen to change events occurring to any documents in the collection. To remove the listener, call remove() function on the returned listener token.

Specified by:

addChangeListener in interface com.couchbase.lite.internal.Listenable<CollectionChange,CollectionChangeListener>

Parameters:

listener - the observer

Returns:

token used to cancel the listener

Throws:

IllegalStateException - if the default collection doesn’t exist.

CouchbaseLiteException

addChangeListener

@NonNull
public ListenerToken addChangeListener(@Nullable
 Executor executor,
 @NonNull
 CollectionChangeListener listener)

Add a change listener to listen to change events occurring to any documents in the collection. To remove the listener, call remove() function on the returned listener token. This listener will be executed on the passed executor

Specified by:

addChangeListener in interface com.couchbase.lite.internal.Listenable<CollectionChange,CollectionChangeListener>

Parameters:

executor - the executor on which to run the listener.

listener - the observer

Returns:

token used to cancel the listener

Throws:

IllegalStateException - if the default collection doesn’t exist.

addDocumentChangeListener

@NonNull
public ListenerToken addDocumentChangeListener(@NonNull
 String id,
 @NonNull
 DocumentChangeListener listener)

Add a change listener to listen to change events occurring to a document of the given document id. To remove the listener, call remove() function on the returned listener token.

addDocumentChangeListener

@NonNull
public ListenerToken addDocumentChangeListener(@NonNull
 String id,
 @Nullable
 Executor executor,
 @NonNull
 DocumentChangeListener listener)

Adds a change listener for the changes that occur to the specified document with an executor on which the changes will be posted to the listener. If the executor is not specified, the changes will be delivered on the UI thread for the Android platform and on an arbitrary thread for the Java platform.

getIndexes

@NonNull
public Set<String> getIndexes()
                       throws CouchbaseLiteException

Get a list of the names of indices in the collection.

Returns:

the list of index names

Throws:

CouchbaseLiteException - on failure

createIndex

public void createIndex(String name,
 IndexConfiguration config)
                 throws CouchbaseLiteException

Add an index to the collection.

Parameters:

name - index name

config - index configuration

Throws:

CouchbaseLiteException - on failure

createIndex

public void createIndex(String name,
 Index index)
                 throws CouchbaseLiteException

Add an index to the collection.

Parameters:

name - index name

index - index configuration

Throws:

CouchbaseLiteException - on failure

deleteIndex

public void deleteIndex(String name)
                 throws CouchbaseLiteException

Delete the named index from the collection.

Parameters:

name - name of the index to delete

Throws:

CouchbaseLiteException - on failure

close

public void close()

Specified by:

close in interface AutoCloseable

toString

@NonNull
public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object