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 Details

  • 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
    • createFilterDocument

      @NonNull protected Document createFilterDocument(@NonNull String docId, @NonNull String revId, @NonNull com.couchbase.lite.internal.fleece.FLDict body)
      Specified by:
      createFilterDocument in class com.couchbase.lite.internal.BaseCollection