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>
,java.lang.AutoCloseable
public final class Database extends BaseDatabase
A Couchbase Lite database.
-
-
Field Summary
Fields Modifier and Type Field Description static Log
log
Gets the logging controller for the Couchbase Lite library to configure the logging settings and add custom logging.static Prediction
prediction
ENTERPRISE EDITION API
-
Constructor Summary
Constructors Constructor Description Database(java.lang.String name)
Construct a Database with a given name and the default config.Database(java.lang.String name, DatabaseConfiguration config)
Construct a Database with a given name and database config.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description ListenerToken
addChangeListener(DatabaseChangeListener listener)
Deprecated.Use getDefaultCollection().addChangeListenerListenerToken
addChangeListener(java.util.concurrent.Executor executor, DatabaseChangeListener listener)
Deprecated.Use getDefaultCollection().addChangeListenerListenerToken
addDocumentChangeListener(java.lang.String docId, DocumentChangeListener listener)
Deprecated.Use getDefaultCollection().addDocumentChangeListenerListenerToken
addDocumentChangeListener(java.lang.String docId, java.util.concurrent.Executor executor, DocumentChangeListener listener)
Deprecated.Use getDefaultCollection().addDocumentChangeListenervoid
changeEncryptionKey(EncryptionKey encryptionKey)
ENTERPRISE EDITION APIvoid
close()
Closes a database.static void
copy(java.io.File path, java.lang.String name, DatabaseConfiguration config)
Make a copy of a database in a new location.Collection
createCollection(java.lang.String name)
Create a named collection in the default scope.Collection
createCollection(java.lang.String collectionName, java.lang.String scopeName)
Create a named collection in the specified scope.void
createIndex(java.lang.String name, Index index)
Deprecated.Use getDefaultCollection().createIndexvoid
createIndex(java.lang.String name, IndexConfiguration config)
Deprecated.Use getDefaultCollection().createIndexQuery
createQuery(java.lang.String query)
Create a SQL++ query.void
delete()
Deletes a database.void
delete(Document document)
Deprecated.Use getDefaultCollection().deleteboolean
delete(Document document, ConcurrencyControl concurrencyControl)
Deprecated.Use getDefaultCollection().deletestatic void
delete(java.lang.String name, java.io.File directory)
Deletes a database of the given name in the given directory.void
deleteCollection(java.lang.String name)
Delete a collection by name in the default scope.void
deleteCollection(java.lang.String collectionName, java.lang.String scopeName)
Delete a collection by name in the specified scope.void
deleteIndex(java.lang.String name)
Deprecated.Use getDefaultCollection().deleteIndexboolean
equals(java.lang.Object o)
static boolean
exists(java.lang.String name, java.io.File directory)
Checks whether a database of the given name exists in the given directory or not.Blob
getBlob(java.util.Map<java.lang.String,java.lang.Object> props)
(UNCOMMITTED) Use this API if you are developing Javascript language bindings.Collection
getCollection(java.lang.String name)
Get a collection in the default scope by name.Collection
getCollection(java.lang.String collectionName, java.lang.String scopeName)
Get a collection in the specified scope by name.java.util.Set<Collection>
getCollections()
Get all collections in the default scope.java.util.Set<Collection>
getCollections(java.lang.String scopeName)
Get all collections in the named scope.DatabaseConfiguration
getConfig()
Returns a copy of the database configuration.long
getCount()
Deprecated.Use getDefaultCollection().getCount()Collection
getDefaultCollection()
Get the default collection.Scope
getDefaultScope()
Get the default scope.Document
getDocument(java.lang.String id)
Deprecated.Use getDefaultCollection().getDocument()java.util.Date
getDocumentExpiration(java.lang.String id)
Deprecated.Use getDefaultCollection().getDocumentExpirationjava.util.List<java.lang.String>
getIndexes()
Deprecated.Use getDefaultCollection().getIndexesjava.lang.String
getName()
Return the database namejava.lang.String
getPath()
The database's absolute pathScope
getScope(java.lang.String name)
Get a scope object by name.java.util.Set<Scope>
getScopes()
Get scope names that have at least one collection.int
hashCode()
<T extends java.lang.Exception>
voidinBatch(UnitOfWork<T> work)
Runs a group of database operations in a batch.boolean
performMaintenance(MaintenanceType type)
void
purge(Document document)
Deprecated.Use getDefaultCollection().purgevoid
purge(java.lang.String id)
Deprecated.Use getDefaultCollection().purgevoid
removeChangeListener(ListenerToken token)
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
saveBlob(Blob blob)
(UNCOMMITTED) Use this API if you are developing Javascript language bindings.void
setDocumentExpiration(java.lang.String id, java.util.Date expiration)
Deprecated.Use getDefaultCollection().setDocumentExpirationjava.lang.String
toString()
-
-
-
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 filename
- the name of the new DBconfig
- 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 namedirectory
- 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 namedirectory
- 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.
-
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 interfacejava.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
-
getDefaultScope
@NonNull public final Scope getDefaultScope() throws CouchbaseLiteException
Get the default scope.- 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 collectionscopeName
- 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() throws CouchbaseLiteException
Get all collections in the default scope.- Throws:
CouchbaseLiteException
-
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 findscopeName
- 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 deletedscopeName
- 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 theBlob
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 theBlob
API.- Parameters:
props
- blob properties
-
toString
@NonNull public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
equals
public boolean equals(java.lang.Object o)
- Overrides:
equals
in classjava.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().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 public void delete(@NonNull Document document) throws CouchbaseLiteException
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 public void purge(@NonNull Document document) throws CouchbaseLiteException
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 public void purge(@NonNull java.lang.String id) throws CouchbaseLiteException
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 java.lang.String id, @Nullable java.util.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 java.util.Date getDocumentExpiration(@NonNull java.lang.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 java.util.concurrent.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 java.lang.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 java.lang.String docId, @Nullable java.util.concurrent.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 public void removeChangeListener(@NonNull ListenerToken token)
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 @NonNull public java.util.List<java.lang.String> getIndexes() throws CouchbaseLiteException
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 java.lang.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 java.lang.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 public void deleteIndex(@NonNull java.lang.String name) throws CouchbaseLiteException
Deprecated.Use getDefaultCollection().deleteIndexDelete the named index from the default collection.- Parameters:
name
- name of the index to delete- Throws:
CouchbaseLiteException
- on failure
-
-