com.couchbase.lite

Class Database

java.lang.Object

com.couchbase.lite.Database

public final class Database
extends Object

A Couchbase Lite database.

Field Summary

Fields

Modifier and Type	Field and Description
static Log	log Gets the logging controller for the Couchbase Lite library to configure the logging settings and add custom logging.

Constructor Summary

Constructors

Constructor and Description
Database(String name) Construct a Database with a given name and the default config.
Database(String name, DatabaseConfiguration config) Construct a AbstractDatabase with a given name and database config.

Method Summary

Modifier and Type	Method and Description
ListenerToken	addChangeListener(DatabaseChangeListener listener) Adds a change listener for the changes that occur in the database.
ListenerToken	addChangeListener(Executor executor, 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.
ListenerToken	addDocumentChangeListener(String id, DocumentChangeListener listener) Adds a change listener for the changes that occur to the specified document.
ListenerToken	addDocumentChangeListener(String id, Executor executor, 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.
void	close() Closes a database.
void	compact() Deprecated. Use Database.performMaintenance(MaintenanceType.COMPACT)
static void	copy(File path, String name, DatabaseConfiguration config) Make a copy of a database in a new location.
void	createIndex(String name, Index idx)
void	delete() Deletes a database.
void	delete(Document document) Deletes a document from the database.
boolean	delete(Document document, ConcurrencyControl concurrencyControl) Deletes a document from the database.
static void	delete(String name, File directory) Deletes a database of the given name in the given directory.
void	deleteIndex(String name)
static boolean	exists(String name, File directory) Checks whether a database of the given name exists in the given directory or not.
DatabaseConfiguration	getConfig() Returns a READONLY config object which will throw a runtime exception when any setter methods are called.
long	getCount() The number of documents in the database.
Document	getDocument(String id) Gets an existing Document object with the given ID.
Date	getDocumentExpiration(String id) Returns the expiration time of the document.
List<String>	getIndexes()
String	getName() Return the database name
String	getPath() Return the database's path.
void	inBatch(Runnable runnable) Runs a group of database operations in a batch.
boolean	performMaintenance(MaintenanceType type)
void	purge(Document document) Purges the given document from the database.
void	purge(String id) Purges the given document id for the document in database.
void	removeChangeListener(ListenerToken token) Removes the change listener added to the database.
void	save(MutableDocument document) Saves a document to the database.
boolean	save(MutableDocument document, ConcurrencyControl concurrencyControl) Saves a document to the database.
boolean	save(MutableDocument document, ConflictHandler conflictHandler) Saves a document to the database.
void	setDocumentExpiration(String id, Date expiration) Sets an expiration date on a document.
static void	setLogLevel(LogDomain domain, LogLevel level) Deprecated. As of 2.5 because it is being replaced with the getConsole method from the log property. This method will eventually be replaced with a no-op to preserve API compatibility. Until it is, its interactions with other logging maybe be fairly unpredictable.
String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

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.

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

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.

setLogLevel

@Deprecated
public static void setLogLevel(@NonNull
                                           LogDomain domain,
                                           @NonNull
                                           LogLevel level)

Deprecated. As of 2.5 because it is being replaced with the getConsole method from the log property. This method will eventually be replaced with a no-op to preserve API compatibility. Until it is, its interactions with other logging maybe be fairly unpredictable.

Set log level for the given log domain.

Parameters:

domain - The log domain

level - The log level

getName

@NonNull
public String getName()

Return the database name

Returns:

the database's name

getPath

public String getPath()

Return the database's path. If the database is closed or deleted, null value will be returned.

Returns:

the database's path.

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 READONLY config object which will throw a runtime exception when any setter methods are called.

Returns:

the READONLY copied config object

getDocument

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

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 void inBatch(@NonNull
                    Runnable runnable)
             throws CouchbaseLiteException

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:

runnable - the action which is implementation of Runnable interface

Throws:

CouchbaseLiteException - Throws an exception if any error occurs during the operation.

compact

@Deprecated
public void compact()
                         throws CouchbaseLiteException

Deprecated. Use Database.performMaintenance(MaintenanceType.COMPACT)

Compacts the database file by deleting unused attachment files and vacuuming the SQLite database

Throws:

CouchbaseLiteException

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.

getIndexes

@NonNull
public List<String> getIndexes()
                                 throws CouchbaseLiteException

Throws:

CouchbaseLiteException

createIndex

public void createIndex(@NonNull
                        String name,
                        @NonNull
                        Index idx)
                 throws CouchbaseLiteException

Throws:

CouchbaseLiteException

deleteIndex

public void deleteIndex(@NonNull
                        String name)
                 throws CouchbaseLiteException

Throws:

CouchbaseLiteException

performMaintenance

public boolean performMaintenance(MaintenanceType type)
                           throws CouchbaseLiteException

Throws:

CouchbaseLiteException

toString

@NonNull
public String toString()

Overrides:

toString in class Object