Class Database

    • Field Detail

      • prediction

        @NonNull
        public static final Prediction prediction
        ENTERPRISE EDITION API

        The predictive model manager for registering and unregistering predictive models. This is part of the Public API. (which is unfortunate, because we can't change it to Java standards)

      • log

        @NonNull
        public static final Log log
        Gets the logging controller for the Couchbase Lite library to configure the logging settings and add custom logging.

    • Constructor Detail

      • Database

        public Database​(@NonNull
                        java.lang.String name)
                 throws CouchbaseLiteException
        Construct a Database with a given name and the default config. If the database does not yet exist it will be created.
        Parameters:
        name - The name of the database: May NOT contain capital letters!
        Throws:
        CouchbaseLiteException - if any error occurs during the open operation.
      • Database

        public Database​(@NonNull
                        java.lang.String name,
                        @NonNull
                        DatabaseConfiguration config)
                 throws CouchbaseLiteException
        Construct a Database with a given name and database config. If the database does not yet exist, it will be created, unless the `readOnly` option is used.
        Parameters:
        name - The name of the database: May NOT contain capital letters!
        config - The database config.
        Throws:
        CouchbaseLiteException - Throws an exception if any error occurs during the open operation.
    • Method Detail

      • copy

        public static void copy​(@NonNull
                                java.io.File path,
                                @NonNull
                                java.lang.String name,
                                @NonNull
                                DatabaseConfiguration config)
                         throws CouchbaseLiteException
        Make a copy of a database in a new location. It is recommended that this method not be used on an open database.
        Parameters:
        path - path to the existing db file
        name - the name of the new DB
        config - a config with the new location
        Throws:
        CouchbaseLiteException - on copy failure
      • changeEncryptionKey

        public void changeEncryptionKey​(EncryptionKey encryptionKey)
                                 throws CouchbaseLiteException
        ENTERPRISE EDITION API

        Changes the database's encryption key, or removes encryption if the new key is null.

        Parameters:
        encryptionKey - The encryption key
        Throws:
        CouchbaseLiteException - on error
      • delete

        public static void delete​(@NonNull
                                  java.lang.String name,
                                  @Nullable
                                  java.io.File directory)
                           throws CouchbaseLiteException
        Deletes a database of the given name in the given directory.
        Parameters:
        name - the database's name
        directory - the directory containing the database: the database's parent directory.
        Throws:
        CouchbaseLiteException - Throws an exception if any error occurs during the operation.
      • exists

        public static boolean exists​(@NonNull
                                     java.lang.String name,
                                     @Nullable
                                     java.io.File directory)
        Checks whether a database of the given name exists in the given directory or not.
        Parameters:
        name - the database's name
        directory - the path where the database is located.
        Returns:
        true if exists, false otherwise.
      • getName

        @NonNull
        public java.lang.String getName()
        Return the database name
        Returns:
        the database's name
      • getPath

        @Nullable
        public java.lang.String getPath()
        The database's absolute path
        Returns:
        the database's path or null if the database is closed.
      • close

        public void close()
                   throws CouchbaseLiteException
        Closes a database. Closing a database will stop all replicators, live queries and all listeners attached to it.
        Specified by:
        close in interface java.lang.AutoCloseable
        Throws:
        CouchbaseLiteException - Throws an exception if any error occurs during the operation.
      • delete

        public void delete()
                    throws CouchbaseLiteException
        Deletes a database. Deleting a database will stop all replicators, live queries and all listeners attached to it. Although attempting to close a closed database is not an error, attempting to delete a closed database is.
        Throws:
        CouchbaseLiteException - Throws an exception if any error occurs during the operation.
      • getScopes

        @NonNull
        public final java.util.Set<Scope> getScopes()
                                             throws CouchbaseLiteException
        Get scope names that have at least one collection. Note: the default scope is exceptional as it will always be listed even though there are no collections under it.
        Throws:
        CouchbaseLiteException
      • getScope

        @Nullable
        public final Scope getScope​(@NonNull
                                    java.lang.String name)
                             throws CouchbaseLiteException
        Get a scope object by name. As the scope cannot exist by itself without having a collection, the hull value will be returned if there are no collections under the given scope’s name. Note: The default scope is exceptional, and it will always be returned.
        Throws:
        CouchbaseLiteException
      • createCollection

        @NonNull
        public final Collection createCollection​(@NonNull
                                                 java.lang.String name)
                                          throws CouchbaseLiteException
        Create a named collection in the default scope. If the collection already exists, the existing collection will be returned.
        Parameters:
        name - the scope in which to create the collection
        Returns:
        the named collection in the default scope
        Throws:
        CouchbaseLiteException - on failure
      • createCollection

        @NonNull
        public final Collection createCollection​(@NonNull
                                                 java.lang.String collectionName,
                                                 @Nullable
                                                 java.lang.String scopeName)
                                          throws CouchbaseLiteException
        Create a named collection in the specified scope. If the collection already exists, the existing collection will be returned.
        Parameters:
        collectionName - the name of the new collection
        scopeName - the scope in which to create the collection
        Returns:
        the named collection in the default scope
        Throws:
        CouchbaseLiteException - on failure
      • getCollections

        @NonNull
        public final java.util.Set<Collection> getCollections​(@Nullable
                                                              java.lang.String scopeName)
                                                       throws CouchbaseLiteException
        Get all collections in the named scope.
        Parameters:
        scopeName - the scope name
        Returns:
        the collections in the named scope
        Throws:
        CouchbaseLiteException
      • getCollection

        @Nullable
        public final Collection getCollection​(@NonNull
                                              java.lang.String name)
                                       throws CouchbaseLiteException
        Get a collection in the default scope by name. If the collection doesn't exist, the function will return null.
        Parameters:
        name - the collection to find
        Returns:
        the named collection or null
        Throws:
        CouchbaseLiteException
      • getCollection

        @Nullable
        public final Collection getCollection​(@NonNull
                                              java.lang.String collectionName,
                                              @Nullable
                                              java.lang.String scopeName)
                                       throws CouchbaseLiteException
        Get a collection in the specified scope by name. If the collection doesn't exist, the function will return null.
        Parameters:
        collectionName - the collection to find
        scopeName - the scope in which to create the collection
        Returns:
        the named collection or null
        Throws:
        CouchbaseLiteException
      • getDefaultCollection

        @Nullable
        public final Collection getDefaultCollection()
                                              throws CouchbaseLiteException
        Get the default collection. If the default collection has been deleted the function will return null.
        Returns:
        the default collection or null if it does not exist.
        Throws:
        CouchbaseLiteException
      • deleteCollection

        public final void deleteCollection​(@NonNull
                                           java.lang.String name)
                                    throws CouchbaseLiteException
        Delete a collection by name in the default scope. If the collection doesn't exist, the operation will be no-ops. Note: the default collection can be deleted but cannot be recreated.
        Parameters:
        name - the collection to be deleted
        Throws:
        CouchbaseLiteException - on failure
      • deleteCollection

        public final void deleteCollection​(@NonNull
                                           java.lang.String collectionName,
                                           @Nullable
                                           java.lang.String scopeName)
                                    throws CouchbaseLiteException
        Delete a collection by name in the specified scope. If the collection doesn't exist, the operation will be no-ops. Note: the default collection can be deleted but cannot be recreated.
        Parameters:
        collectionName - the collection to be deleted
        scopeName - the scope from which to delete the collection
        Throws:
        CouchbaseLiteException - on failure
      • inBatch

        public <T extends java.lang.Exception> void inBatch​(@NonNull
                                                            UnitOfWork<T> work)
                                                     throws CouchbaseLiteException,
                                                            T extends java.lang.Exception
        Runs a group of database operations in a batch. Use this when performing bulk write operations like multiple inserts/updates; it saves the overhead of multiple database commits, greatly improving performance.
        Parameters:
        work - a unit of work that may terminate abruptly (with an exception)
        Throws:
        CouchbaseLiteException - Throws an exception if any error occurs during the operation.
        T extends java.lang.Exception
      • createQuery

        @NonNull
        public Query createQuery​(@NonNull
                                 java.lang.String query)
        Create a SQL++ query.
        Parameters:
        query - a valid SQL++ query
        Returns:
        the Query object
      • saveBlob

        @Internal("This method is not part of the public API")
        public void saveBlob​(@NonNull
                             Blob blob)
        (UNCOMMITTED) Use this API if you are developing Javascript language bindings. If you are developing a native app, you must use the Blob API.
        Parameters:
        blob - a blob
      • getBlob

        @Internal("This method is not part of the public API")
        @Nullable
        public Blob getBlob​(@NonNull
                            java.util.Map<java.lang.String,​java.lang.Object> props)
        (UNCOMMITTED) Use this API if you are developing Javascript language bindings. If you are developing a native app, you must use the Blob API.
        Parameters:
        props - blob properties
      • toString

        @NonNull
        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
      • getCount

        @Deprecated
        public long getCount()
        Deprecated.
        Use getDefaultCollection().getCount()
        The number of documents in the default collection.
        Returns:
        the number of documents in the database, 0 if database is closed.
      • getConfig

        @NonNull
        public DatabaseConfiguration getConfig()
        Returns a copy of the database configuration.
        Returns:
        the READONLY copied config object
      • getDocument

        @Deprecated
        @Nullable
        public Document getDocument​(@NonNull
                                    java.lang.String id)
        Deprecated.
        Use getDefaultCollection().getDocument()
        Gets an existing Document with the given ID from the default collection. If the document with the given ID doesn't exist in the default collection, the method will return null. If the default collection does not exist or if the database is closed, the method will throw an IllegalStateException
        Parameters:
        id - the document ID
        Returns:
        the Document object or null
        Throws:
        java.lang.IllegalStateException - when the database is closed or the default collection has been deleted
      • save

        @Deprecated
        public void save​(@NonNull
                         MutableDocument document)
                  throws CouchbaseLiteException
        Deprecated.
        Use getDefaultCollection().save
        Saves a document to the default collection. When write operations are executed concurrently, the last writer will overwrite all other written values. Calling this method is the same as calling save(MutableDocument, ConcurrencyControl.LAST_WRITE_WINS)
        Parameters:
        document - The document.
        Throws:
        CouchbaseLiteException - on error
      • save

        @Deprecated
        public boolean save​(@NonNull
                            MutableDocument document,
                            @NonNull
                            ConcurrencyControl concurrencyControl)
                     throws CouchbaseLiteException
        Deprecated.
        Use getDefaultCollection().save()
        Saves a document to the default collection. When used with LAST_WRITE_WINS concurrency control, the last write operation will win if there is a conflict. When used with FAIL_ON_CONFLICT concurrency control, save will fail when there is a conflict and the method will return false
        Parameters:
        document - The document.
        concurrencyControl - The concurrency control.
        Returns:
        true if successful. false if the FAIL_ON_CONFLICT concurrency
        Throws:
        CouchbaseLiteException - on error
      • save

        @Deprecated
        public boolean save​(@NonNull
                            MutableDocument document,
                            @NonNull
                            ConflictHandler conflictHandler)
                     throws CouchbaseLiteException
        Deprecated.
        Use getDefaultCollection().save
        Saves a document to the default collection. Conflicts will be resolved by the passed ConflictHandler
        Parameters:
        document - The document.
        conflictHandler - A conflict handler.
        Returns:
        true if successful. false if the FAIL_ON_CONFLICT concurrency
        Throws:
        CouchbaseLiteException - on error
      • delete

        @Deprecated
        public void delete​(@NonNull
                           Document document)
                    throws CouchbaseLiteException
        Deprecated.
        Use getDefaultCollection().delete
        Deletes a document from the default collection. When write operations are executed concurrently, the last writer will overwrite all other written values. Calling this function is the same as calling delete(Document, ConcurrencyControl.LAST_WRITE_WINS)
        Parameters:
        document - The document.
        Throws:
        CouchbaseLiteException - on error
      • delete

        @Deprecated
        public boolean delete​(@NonNull
                              Document document,
                              @NonNull
                              ConcurrencyControl concurrencyControl)
                       throws CouchbaseLiteException
        Deprecated.
        Use getDefaultCollection().delete
        Deletes a document from the default collection. When used with lastWriteWins concurrency control, the last write operation will win if there is a conflict. When used with FAIL_ON_CONFLICT concurrency control, delete will fail and the method will return false.
        Parameters:
        document - The document.
        concurrencyControl - The concurrency control.
        Throws:
        CouchbaseLiteException - on error
      • purge

        @Deprecated
        public void purge​(@NonNull
                          Document document)
                   throws CouchbaseLiteException
        Deprecated.
        Use getDefaultCollection().purge
        Purges the passed document from the default collection. This is more drastic than delete(Document): it removes all local traces of the document. Purges will NOT be replicated to other databases.
        Parameters:
        document - the document to be purged.
        Throws:
        CouchbaseLiteException
      • purge

        @Deprecated
        public void purge​(@NonNull
                          java.lang.String id)
                   throws CouchbaseLiteException
        Deprecated.
        Use getDefaultCollection().purge
        Purges the document with the passed id from default collection. This is more drastic than delete(Document), it removes all local traces of the document. Purges will NOT be replicated to other databases.
        Parameters:
        id - the document ID
        Throws:
        CouchbaseLiteException
      • setDocumentExpiration

        @Deprecated
        public void setDocumentExpiration​(@NonNull
                                          java.lang.String id,
                                          @Nullable
                                          java.util.Date expiration)
                                   throws CouchbaseLiteException
        Deprecated.
        Use getDefaultCollection().setDocumentExpiration
        Sets an expiration date for a document in the default collection. The document will be purged from the database at the set time.
        Parameters:
        id - The ID of the Document
        expiration - Nullable expiration timestamp as a Date, set timestamp to null to remove expiration date time from doc.
        Throws:
        CouchbaseLiteException - Throws an exception if any error occurs during the operation.
      • getDocumentExpiration

        @Deprecated
        @Nullable
        public java.util.Date getDocumentExpiration​(@NonNull
                                                    java.lang.String id)
                                             throws CouchbaseLiteException
        Deprecated.
        Use getDefaultCollection().getDocumentExpiration
        Returns the expiration time of the document. If the document has no expiration time set, the method will return null.
        Parameters:
        id - The ID of the Document
        Returns:
        Date a nullable expiration timestamp of the document or null if time not set.
        Throws:
        CouchbaseLiteException - Throws an exception if any error occurs during the operation.
      • addChangeListener

        @Deprecated
        @NonNull
        public ListenerToken addChangeListener​(@NonNull
                                               DatabaseChangeListener listener)
        Deprecated.
        Use getDefaultCollection().addChangeListener
        Adds a change listener for the changes that occur in the database. The changes will be delivered on the UI thread for the Android platform and on an arbitrary thread for the Java platform. When developing a Java Desktop application using Swing or JavaFX that needs to update the UI after receiving the changes, make sure to schedule the UI update on the UI thread by using SwingUtilities.invokeLater(Runnable) or Platform.runLater(Runnable) respectively.
        Specified by:
        addChangeListener in interface com.couchbase.lite.internal.Listenable<DatabaseChange,​DatabaseChangeListener>
        Parameters:
        listener - callback
      • addChangeListener

        @Deprecated
        @NonNull
        public ListenerToken addChangeListener​(@Nullable
                                               java.util.concurrent.Executor executor,
                                               @NonNull
                                               DatabaseChangeListener listener)
        Deprecated.
        Use getDefaultCollection().addChangeListener
        Adds a change listener for the changes that occur in the database 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.
        Specified by:
        addChangeListener in interface com.couchbase.lite.internal.Listenable<DatabaseChange,​DatabaseChangeListener>
        Parameters:
        listener - callback
      • addDocumentChangeListener

        @Deprecated
        @NonNull
        public ListenerToken addDocumentChangeListener​(@NonNull
                                                       java.lang.String docId,
                                                       @NonNull
                                                       DocumentChangeListener listener)
        Deprecated.
        Use getDefaultCollection().addDocumentChangeListener
        Adds a change listener for the changes that occur to the specified document, in the default collection. On the Android platform changes will be delivered on the UI thread. On other Java platforms changes will be delivered on an arbitrary thread. When developing a Java Desktop application using Swing or JavaFX for a UI that will be updated in response to a change, make sure to schedule the UI update on the UI thread by using SwingUtilities.invokeLater(Runnable) or Platform.runLater(Runnable) respectively.
      • addDocumentChangeListener

        @Deprecated
        @NonNull
        public ListenerToken addDocumentChangeListener​(@NonNull
                                                       java.lang.String docId,
                                                       @Nullable
                                                       java.util.concurrent.Executor executor,
                                                       @NonNull
                                                       DocumentChangeListener listener)
        Deprecated.
        Use getDefaultCollection().addDocumentChangeListener
        Adds a change listener for the changes that occur to the specified document, in the default collection. Changes will be posted to the listener on the passed executor on which. 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.
      • removeChangeListener

        @Deprecated
        public void removeChangeListener​(@NonNull
                                         ListenerToken token)
        Deprecated.
        Use ListenerToken.remove
        Removes a change listener added to the default collection.
        Parameters:
        token - returned by a previous call to addChangeListener or addDocumentListener.
      • getIndexes

        @Deprecated
        @NonNull
        public java.util.List<java.lang.String> getIndexes()
                                                    throws CouchbaseLiteException
        Deprecated.
        Use getDefaultCollection().getIndexes
        Get a list of the names of indices on the default collection.
        Returns:
        the list of index names
        Throws:
        CouchbaseLiteException - on failure
      • createIndex

        @Deprecated
        public void createIndex​(@NonNull
                                java.lang.String name,
                                @NonNull
                                Index index)
                         throws CouchbaseLiteException
        Deprecated.
        Use getDefaultCollection().createIndex
        Add an index to the default collection.
        Parameters:
        name - index name
        index - index description
        Throws:
        CouchbaseLiteException - on failure
      • createIndex

        @Deprecated
        public void createIndex​(@NonNull
                                java.lang.String name,
                                @NonNull
                                IndexConfiguration config)
                         throws CouchbaseLiteException
        Deprecated.
        Use getDefaultCollection().createIndex
        Add an index to the default collection.
        Parameters:
        name - index name
        config - index configuration
        Throws:
        CouchbaseLiteException - on failure
      • deleteIndex

        @Deprecated
        public void deleteIndex​(@NonNull
                                java.lang.String name)
                         throws CouchbaseLiteException
        Deprecated.
        Use getDefaultCollection().deleteIndex
        Delete the named index from the default collection.
        Parameters:
        name - name of the index to delete
        Throws:
        CouchbaseLiteException - on failure