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
ACollection
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 constantScope.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 anIllegalStateException
. 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 anIllegalStateException
to be thrown.Collection
s areAutoCloseable
. 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 String
DEFAULT_NAME
-
Method Summary
All Methods Instance Methods Concrete Methods 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()
protected Document
createFilterDocument(String docId, String revId, com.couchbase.lite.internal.fleece.FLDict body)
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 nameScope
getScope()
Get scopeint
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()
-
-
-
Field Detail
-
DEFAULT_NAME
public static final String DEFAULT_NAME
- See Also:
- Constant Field Values
-
-
Method Detail
-
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 interfacecom.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 interfacecom.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 nameconfig
- 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 nameindex
- 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 interfaceAutoCloseable
-
-