Package com.couchbase.lite

Class Database

  • public final class Database
extends BaseDatabase
    A Couchbase Lite 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.

      • 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
                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
                String name,
                @NonNull
                DatabaseConfiguration config)
         throws CouchbaseLiteException
        Construct a AbstractDatabase 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
                        File path,
                        @NonNull
                        String name,
                        @NonNull
                        DatabaseConfiguration config)
                 throws CouchbaseLiteException
        Make a copy of a database in a new location. NOTE: This method will copy the database without changing the encryption key of the original database: the encryption key specified in the given config is the encryption key used for both the original and copied database. To change or add the encryption key for the copied database, call Database.changeEncryptionKey(key) for the copy.
        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
                          String name,
                          @Nullable
                          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
                             String name,
                             @NonNull
                             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 String getName()
        Return the database name
        Returns:
        the database's name

      • getPath

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

      • getCount

        public long getCount()
        The number of documents in the database.
        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

        @Nullable
public Document getDocument​(@NonNull
                            String id)
        Gets an existing Document object with the given ID. If the document with the given ID doesn't exist in the database, the value returned will be null.
        Parameters:
        id - the document ID
        Returns:
        the Document object

      • save

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

      • save

        public boolean save​(@NonNull
                    MutableDocument document,
                    @NonNull
                    ConcurrencyControl concurrencyControl)
             throws CouchbaseLiteException
        Saves a document to the database. 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 with false value
        Parameters:
        document - The document.
        concurrencyControl - The concurrency control.
        Returns:
        true if successful. false if the FAIL_ON_CONFLICT concurrency
        Throws:
        CouchbaseLiteException - on error

      • save

        public boolean save​(@NonNull
                    MutableDocument document,
                    @NonNull
                    ConflictHandler conflictHandler)
             throws CouchbaseLiteException
        Saves a document to the database. 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

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

      • delete

        public boolean delete​(@NonNull
                      Document document,
                      @NonNull
                      ConcurrencyControl concurrencyControl)
               throws CouchbaseLiteException
        Deletes a document from the database. 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 with 'false' value returned.
        Parameters:
        document - The document.
        concurrencyControl - The concurrency control.
        Throws:
        CouchbaseLiteException - on error

      • purge

        public void purge​(@NonNull
                  Document document)
           throws CouchbaseLiteException
        Purges the given document from the database. This is more drastic than delete(Document), it removes all traces of the document. The purge will NOT be replicated to other databases.
        Parameters:
        document - the document to be purged.
        Throws:
        CouchbaseLiteException

      • purge

        public void purge​(@NonNull
                  String id)
           throws CouchbaseLiteException
        Purges the given document id for the document in database. This is more drastic than delete(Document), it removes all traces of the document. The purge will NOT be replicated to other databases.
        Parameters:
        id - the document ID
        Throws:
        CouchbaseLiteException

      • setDocumentExpiration

        public void setDocumentExpiration​(@NonNull
                                  String id,
                                  @Nullable
                                  Date expiration)
                           throws CouchbaseLiteException
        Sets an expiration date on a document. After this time, the document will be purged from the database.
        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

        @Nullable
public Date getDocumentExpiration​(@NonNull
                                  String id)
                           throws CouchbaseLiteException
        Returns the expiration time of the document. null will be returned if there is no expiration time set
        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.

      • inBatch

        public <T extends Exception> void inBatch​(@NonNull
                                          UnitOfWork<T> work)
                                   throws CouchbaseLiteException,
                                          T extends 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 Exception

      • addChangeListener

        @NonNull
public ListenerToken addChangeListener​(@NonNull
                                       DatabaseChangeListener listener)
        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.
        Parameters:
        listener - callback

      • addChangeListener

        @NonNull
public ListenerToken addChangeListener​(@Nullable
                                       Executor executor,
                                       @NonNull
                                       DatabaseChangeListener listener)
        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.
        Parameters:
        listener - callback

      • removeChangeListener

        public void removeChangeListener​(@NonNull
                                 ListenerToken token)
        Removes the change listener added to the database.
        Parameters:
        token - returned by a previous call to addChangeListener or addDocumentListener.

      • addDocumentChangeListener

        @NonNull
public ListenerToken addDocumentChangeListener​(@NonNull
                                               String id,
                                               @NonNull
                                               DocumentChangeListener listener)
        Adds a change listener for the changes that occur to the specified document. 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.

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

      • close

        public void close()
           throws CouchbaseLiteException
        Closes a database. Closing a database will stop all replicators, live queries and all listeners attached to it.
        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.

      • saveBlob

        @Internal("This method is not part of the public API: it is for internal use only")
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 -

      • getBlob

        @Internal("This method is not part of the public API: it is for internal use only")
@Nullable
public Blob getBlob​(@NonNull
                    Map<String,​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.
        Returns:
        Blob