Package com.couchbase.lite

Class Database

java.lang.Object
com.couchbase.lite.BaseDatabase
com.couchbase.lite.Database
All Implemented Interfaces:
AutoCloseable
public final class Database extends BaseDatabase
A Couchbase Lite database.

  • Field Details

    • prediction

      @NonNull public static final Prediction prediction
      ENTERPRISE EDITION API

      The predictive model manager for registering and unregistering predictive models.

    • config

      @NonNull protected final com.couchbase.lite.internal.ImmutableDatabaseConfiguration config

  • Constructor Details

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

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

    • getDatabase

      @NonNull protected Database getDatabase()

    • 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, @Nullable 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.

    • copy

      protected static void copy(@NonNull File path, @NonNull String name, @NonNull String dbDir, int algorithm, byte[] encryptionKey) throws CouchbaseLiteException
      Throws:
      CouchbaseLiteException

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

    • performMaintenance

      public boolean performMaintenance(MaintenanceType type) throws CouchbaseLiteException
      Throws:
      CouchbaseLiteException

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

    • getDefaultScope

      @NonNull public final Scope getDefaultScope() throws CouchbaseLiteException
      Get the default scope.
      Throws:
      CouchbaseLiteException

    • createCollection

      @NonNull public final Collection createCollection(@NonNull 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 String collectionName, @Nullable 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 Set<Collection> getCollections() throws CouchbaseLiteException
      Get all collections in the default scope.
      Throws:
      CouchbaseLiteException

    • getCollections

      @NonNull public final Set<Collection> getCollections(@Nullable 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 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 String collectionName, @Nullable 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

      @NonNull public final Collection getDefaultCollection() throws CouchbaseLiteException
      Get the default collection.
      Returns:
      the default collection.
      Throws:
      CouchbaseLiteException

    • deleteCollection

      public final void deleteCollection(@NonNull String name) throws CouchbaseLiteException
      Delete a collection by name in the default scope. If the collection doesn't exist, the operation will do nothing. Note: the default collection cannot be deleted.
      Parameters:
      name - the collection to be deleted
      Throws:
      CouchbaseLiteException - on failure

    • deleteCollection

      public final void deleteCollection(@NonNull String collectionName, @Nullable String scopeName) throws CouchbaseLiteException
      Delete a collection by name in the specified scope. If the collection doesn't exist, the operation will do nothing. Note: the default collection cannot be deleted.
      Parameters:
      collectionName - the collection to be deleted
      scopeName - the scope from which to delete the collection
      Throws:
      CouchbaseLiteException - on failure

    • inBatch

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

    • createQuery

      @NonNull public Query createQuery(@NonNull String query) throws CouchbaseLiteException
      Create a SQL++ query.
      Parameters:
      query - a valid SQL++ query
      Returns:
      the Query object
      Throws:
      CouchbaseLiteException

    • 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 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.
      Parameters:
      props - blob properties

    • getConfig

      @NonNull public DatabaseConfiguration getConfig()
      Returns a copy of the database configuration. Mutating the copy will not affect the configuration of the database
      Returns:
      a copy of the database configuration

    • toString

      @NonNull public String toString()
      Overrides:
      toString in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • finalize

      protected void finalize() throws Throwable
      Overrides:
      finalize in class Object
      Throws:
      Throwable