com.couchbase.lite

Class Database

java.lang.Object

com.couchbase.lite.Database

public final class Database
extends Object

A Couchbase Lite database.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Database.LogDomain Log domain.
static class	Database.LogLevel Log level.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
ListenerToken	addChangeListener(DatabaseChangeListener listener) Set the given DatabaseChangeListener to the this database.
ListenerToken	addChangeListener(Executor executor, DatabaseChangeListener listener)
ListenerToken	addDocumentChangeListener(String id, DocumentChangeListener listener) Add the given DocumentChangeListener to the specified document.
ListenerToken	addDocumentChangeListener(String id, Executor executor, DocumentChangeListener listener)
void	close() Closes a database.
void	compact() Compacts the database file by deleting unused attachment files and vacuuming the SQLite database
static void	copy(File path, String name, DatabaseConfiguration config)
void	createIndex(String name, com.couchbase.lite.Index index)
void	delete() Deletes a database.
void	delete(Document document) Delete the givin document.
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.
int	getCount() The number of documents in the database.
Document	getDocument(String id) Gets an existing Document object with the given ID.
List<String>	getIndexes()
String	getName() Return the database name
File	getPath() Return the database's path.
void	inBatch(Runnable runnable) Runs a group of database operations in a batch.
void	purge(Document document) Purges the given document from the database.
void	removeChangeListener(ListenerToken token) Remove the given DatabaseChangeListener from the this database.
Document	save(MutableDocument document) Saves the given document to the database.
void	setEncryptionKey(EncryptionKey encryptionKey) Changes the database's encryption key, or removes encryption if the new key is null.
static void	setLogLevel(Database.LogDomain domain, Database.LogLevel level)
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

Database

public Database(String name,
                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, Note: null config parameter is not allowed with Android platform

Throws:

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

Method Detail

getName

public String getName()

Return the database name

Returns:

the database's name

getPath

public File 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 int getCount()

The number of documents in the database.

Returns:

the number of documents in the database, 0 if database is closed.

getConfig

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(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 Document save(MutableDocument document)
              throws CouchbaseLiteException

Saves the given document to the database. If the document in the database has been updated since it was read by this Document, a conflict occurs, which will be resolved by invoking the conflict handler. This can happen if multiple application threads are writing to the database, or a pull replication is copying changes from a server.

Parameters:

document -

Throws:

CouchbaseLiteException

delete

public void delete(Document document)
            throws CouchbaseLiteException

Delete the givin document. All properties are removed, and subsequent calls to getDocument(String) will return null. Deletion adds a special "tombstone" revision to the database, as bookkeeping so that the change can be replicated to other databases. Thus, it does not free up all of the disk space occupied by the document. To delete a document entirely (but without the ability to replicate this), use purge(Document).

Parameters:

document -

Throws:

CouchbaseLiteException

purge

public void purge(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 -

Throws:

CouchbaseLiteException

inBatch

public void inBatch(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

public void compact()
             throws CouchbaseLiteException

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

Throws:

CouchbaseLiteException

addChangeListener

public ListenerToken addChangeListener(DatabaseChangeListener listener)

Set the given DatabaseChangeListener to the this database.

Parameters:

listener -

addChangeListener

public ListenerToken addChangeListener(Executor executor,
                                       DatabaseChangeListener listener)

removeChangeListener

public void removeChangeListener(ListenerToken token)

Remove the given DatabaseChangeListener from the this database.

Parameters:

token -

addDocumentChangeListener

public ListenerToken addDocumentChangeListener(String id,
                                               DocumentChangeListener listener)

Add the given DocumentChangeListener to the specified document.

addDocumentChangeListener

public ListenerToken addDocumentChangeListener(String id,
                                               Executor executor,
                                               DocumentChangeListener listener)

close

public void close()
           throws CouchbaseLiteException

Closes a database.

Throws:

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

delete

public void delete()
            throws CouchbaseLiteException

Deletes a database.

Throws:

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

setEncryptionKey

public void setEncryptionKey(EncryptionKey encryptionKey)
                      throws CouchbaseLiteException

Changes the database's encryption key, or removes encryption if the new key is null.

Parameters:

encryptionKey - The encryption key

Throws:

CouchbaseLiteException

getIndexes

public List<String> getIndexes()
                        throws CouchbaseLiteException

Throws:

CouchbaseLiteException

createIndex

public void createIndex(String name,
                        com.couchbase.lite.Index index)
                 throws CouchbaseLiteException

Throws:

CouchbaseLiteException

deleteIndex

public void deleteIndex(String name)
                 throws CouchbaseLiteException

Throws:

CouchbaseLiteException

delete

public static void delete(String name,
                          File directory)
                   throws CouchbaseLiteException

Deletes a database of the given name in the given directory.

Parameters:

name - the database's name

directory - the path where the database is located.

Throws:

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

exists

public static boolean exists(String name,
                             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

public static void copy(File path,
                        String name,
                        DatabaseConfiguration config)
                 throws CouchbaseLiteException

Throws:

CouchbaseLiteException

setLogLevel

public static void setLogLevel(Database.LogDomain domain,
                               Database.LogLevel level)

toString

public String toString()

Overrides:

toString in class Object