Package com.couchbase.lite
Class Database
java.lang.Object
com.couchbase.lite.BaseDatabase
com.couchbase.lite.Database
- All Implemented Interfaces:
com.couchbase.lite.internal.Listenable<DatabaseChange,
,DatabaseChangeListener> AutoCloseable
A Couchbase Lite database.
-
Field Summary
Modifier and TypeFieldDescriptionprotected final com.couchbase.lite.internal.ImmutableDatabaseConfiguration
static final Log
Gets the logging controller for the Couchbase Lite library to configure the logging settings and add custom logging.static final Prediction
ENTERPRISE EDITION API -
Constructor Summary
ConstructorDescriptionConstruct a Database with a given name and the default config.Database
(String name, DatabaseConfiguration config) Construct a Database with a given name and database config. -
Method Summary
Modifier and TypeMethodDescriptionaddChangeListener
(DatabaseChangeListener listener) Deprecated.Use getDefaultCollection().addChangeListeneraddChangeListener
(Executor executor, DatabaseChangeListener listener) Deprecated.Use getDefaultCollection().addChangeListeneraddDocumentChangeListener
(String docId, DocumentChangeListener listener) Deprecated.Use getDefaultCollection().addDocumentChangeListeneraddDocumentChangeListener
(String docId, Executor executor, DocumentChangeListener listener) Deprecated.Use getDefaultCollection().addDocumentChangeListenervoid
changeEncryptionKey
(EncryptionKey encryptionKey) ENTERPRISE EDITION APIvoid
close()
Closes a database.static void
copy
(File path, String name, DatabaseConfiguration config) Make a copy of a database in a new location.protected static void
final Collection
createCollection
(String name) Create a named collection in the default scope.final Collection
createCollection
(String collectionName, String scopeName) Create a named collection in the specified scope.void
createIndex
(String name, Index index) Deprecated.Use getDefaultCollection().createIndexvoid
createIndex
(String name, IndexConfiguration config) Deprecated.Use getDefaultCollection().createIndexcreateQuery
(String query) Create a SQL++ query.void
delete()
Deletes a database.void
Deprecated.Use getDefaultCollection().deleteboolean
delete
(Document document, ConcurrencyControl concurrencyControl) Deprecated.Use getDefaultCollection().deletestatic void
Deletes a database of the given name in the given directory.final void
deleteCollection
(String name) Delete a collection by name in the default scope.final void
deleteCollection
(String collectionName, String scopeName) Delete a collection by name in the specified scope.void
deleteIndex
(String name) Deprecated.Use getDefaultCollection().deleteIndexboolean
static boolean
Checks whether a database of the given name exists in the given directory or not.protected void
finalize()
(UNCOMMITTED) Use this API if you are developing Javascript language bindings.final Collection
getCollection
(String name) Get a collection in the default scope by name.final Collection
getCollection
(String collectionName, String scopeName) Get a collection in the specified scope by name.final Set<Collection>
Get all collections in the default scope.final Set<Collection>
getCollections
(String scopeName) Get all collections in the named scope.Returns a copy of the database configuration.long
getCount()
Deprecated.Use getDefaultCollection().getCount()protected Database
final Collection
Get the default collection.final Scope
Get the default scope.getDocument
(String id) Deprecated.Use getDefaultCollection().getDocument()Deprecated.Use getDefaultCollection().getDocumentExpirationDeprecated.Use getDefaultCollection().getIndexesgetName()
Return the database namegetPath()
The database's absolute pathfinal Scope
Get a scope object by name.Get scope names that have at least one collection.int
hashCode()
<T extends Exception>
voidinBatch
(UnitOfWork<T> work) Runs a group of database operations in a batch.boolean
void
Deprecated.Use getDefaultCollection().purgevoid
Deprecated.Use getDefaultCollection().purgevoid
Deprecated.Use ListenerToken.removevoid
save
(MutableDocument document) Deprecated.Use getDefaultCollection().saveboolean
save
(MutableDocument document, ConcurrencyControl concurrencyControl) Deprecated.Use getDefaultCollection().save()boolean
save
(MutableDocument document, ConflictHandler conflictHandler) Deprecated.Use getDefaultCollection().savevoid
(UNCOMMITTED) Use this API if you are developing Javascript language bindings.void
setDocumentExpiration
(String id, Date expiration) Deprecated.Use getDefaultCollection().setDocumentExpirationtoString()
Methods inherited from class com.couchbase.lite.BaseDatabase
assertOpenChecked, assertOpenUnchecked, getBlobStore, getC4DbOrThrowLocked, getDbLock, getDbPath, getOpenC4DbLocked, isOpen, isOpenLocked, setC4DatabaseLocked
-
Field Details
-
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
Gets the logging controller for the Couchbase Lite library to configure the logging settings and add custom logging. -
config
@NonNull protected final com.couchbase.lite.internal.ImmutableDatabaseConfiguration config
-
-
Constructor Details
-
Database
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 filename
- the name of the new DBconfig
- a config with the new location- Throws:
CouchbaseLiteException
- on copy failure
-
changeEncryptionKey
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
-
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 namedirectory
- the directory containing the database: the database's parent directory.- Throws:
CouchbaseLiteException
- Throws an exception if any error occurs during the operation.
-
exists
Checks whether a database of the given name exists in the given directory or not.- Parameters:
name
- the database's namedirectory
- 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
Return the database name- Returns:
- the database's name
-
getPath
The database's absolute path- Returns:
- the database's path or null if the database is closed.
-
performMaintenance
- Throws:
CouchbaseLiteException
-
close
Closes a database. Closing a database will stop all replicators, live queries and all listeners attached to it.- Specified by:
close
in interfaceAutoCloseable
- Throws:
CouchbaseLiteException
- Throws an exception if any error occurs during the operation.
-
delete
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
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
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
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 collectionscopeName
- the scope in which to create the collection- Returns:
- the named collection in the default scope
- Throws:
CouchbaseLiteException
- on failure
-
getCollections
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
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 findscopeName
- the scope in which to create the collection- Returns:
- the named collection or null
- Throws:
CouchbaseLiteException
-
getDefaultCollection
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
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 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 be no-ops. Note: the default collection can be deleted but cannot be recreated.- Parameters:
collectionName
- the collection to be deletedscopeName
- 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
Create a SQL++ query.- Parameters:
query
- a valid SQL++ query- Returns:
- the Query object
-
saveBlob
(UNCOMMITTED) Use this API if you are developing Javascript language bindings. If you are developing a native app, you must use theBlob
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 theBlob
API.- Parameters:
props
- blob properties
-
toString
-
hashCode
public int hashCode() -
equals
-
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
Returns a copy of the database configuration.- Returns:
- the READONLY copied config object
-
getDocument
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:
IllegalStateException
- when the database is closed or the default collection has been deleted
-
save
Deprecated.Use getDefaultCollection().saveSaves 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().saveSaves 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.Use getDefaultCollection().deleteDeletes 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().deleteDeletes 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.Use getDefaultCollection().purgePurges 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.Use getDefaultCollection().purgePurges 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 String id, @Nullable Date expiration) throws CouchbaseLiteException Deprecated.Use getDefaultCollection().setDocumentExpirationSets 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 Documentexpiration
- 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 Date getDocumentExpiration(@NonNull String id) throws CouchbaseLiteException Deprecated.Use getDefaultCollection().getDocumentExpirationReturns 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().addChangeListenerAdds 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 interfacecom.couchbase.lite.internal.Listenable<DatabaseChange,
DatabaseChangeListener> - Parameters:
listener
- callback
-
addChangeListener
@Deprecated @NonNull public ListenerToken addChangeListener(@Nullable Executor executor, @NonNull DatabaseChangeListener listener) Deprecated.Use getDefaultCollection().addChangeListenerAdds 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 interfacecom.couchbase.lite.internal.Listenable<DatabaseChange,
DatabaseChangeListener> - Parameters:
listener
- callback
-
addDocumentChangeListener
@Deprecated @NonNull public ListenerToken addDocumentChangeListener(@NonNull String docId, @NonNull DocumentChangeListener listener) Deprecated.Use getDefaultCollection().addDocumentChangeListenerAdds 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 String docId, @Nullable Executor executor, @NonNull DocumentChangeListener listener) Deprecated.Use getDefaultCollection().addDocumentChangeListenerAdds 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.Use ListenerToken.removeRemoves a change listener added to the default collection.- Parameters:
token
- returned by a previous call to addChangeListener or addDocumentListener.
-
getIndexes
Deprecated.Use getDefaultCollection().getIndexesGet 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 String name, @NonNull Index index) throws CouchbaseLiteException Deprecated.Use getDefaultCollection().createIndexAdd an index to the default collection.- Parameters:
name
- index nameindex
- index description- Throws:
CouchbaseLiteException
- on failure
-
createIndex
@Deprecated public void createIndex(@NonNull String name, @NonNull IndexConfiguration config) throws CouchbaseLiteException Deprecated.Use getDefaultCollection().createIndexAdd an index to the default collection.- Parameters:
name
- index nameconfig
- index configuration- Throws:
CouchbaseLiteException
- on failure
-
deleteIndex
Deprecated.Use getDefaultCollection().deleteIndexDelete the named index from the default collection.- Parameters:
name
- name of the index to delete- Throws:
CouchbaseLiteException
- on failure
-
finalize
-