Couchbase Lite
Objective-C API for iOS and Mac OS
Instance Methods | Class Methods | Properties | List of all members
CBLManager Class Reference

Top-level CouchbaseLite object; manages a collection of databases as a CouchDB server does. More...

#import <CBLManager.h>

Inheritance diagram for CBLManager:

Instance Methods

(instancetype) - init
 Default initializer. More...
 
(instancetype) - initWithDirectory:options:error:
 Initializes a CouchbaseLite manager that stores its data at the given path. More...
 
(instancetype) - copy
 Creates a copy of this CBLManager, which can be used on a different thread. More...
 
(void) - close
 Releases all resources used by the CBLManager instance and closes all its databases. More...
 
(CBLDatabase *) - databaseNamed:error:
 Returns the database with the given name, creating it if it didn't already exist. More...
 
(CBLDatabase *) - existingDatabaseNamed:error:
 Returns the database with the given name, or nil if it doesn't exist. More...
 
(CBLDatabase *) - objectForKeyedSubscript:
 Same as -existingDatabaseNamed:. More...
 
(BOOL) - replaceDatabaseNamed:withDatabaseFile:withAttachments:error:
 Replaces or installs a database from a file. More...
 
(void) - doAsync:
 Runs the block asynchronously on the database manager's dispatch queue or thread. More...
 
(void) - backgroundTellDatabaseNamed:to:
 Asynchronously dispatches a block to run on a background thread. More...
 

Class Methods

(instancetype) + sharedInstance
 A shared per-process instance. More...
 
(BOOL) + isValidDatabaseName:
 Returns YES if the given name is a valid database name. More...
 
(NSString *) + defaultDirectory
 The default directory to use for a CBLManager. More...
 
(void) + enableLogging:
 Enables Couchbase Lite logging of the given type, process-wide. More...
 

Properties

NSString * directory
 The root directory of this manager (as specified at initialization time.) More...
 
NSArray * allDatabaseNames
 An array of the names of all existing databases. More...
 
dispatch_queue_t dispatchQueue
 The dispatch queue used to serialize access to the database manager (and its child objects.) Setting this is optional: by default the objects are bound to the thread on which the database manager was instantiated. More...
 
NSURL * internalURL
 The base URL of the database manager's REST API. More...
 
NSMutableDictionary * customHTTPHeaders
 

Detailed Description

Top-level CouchbaseLite object; manages a collection of databases as a CouchDB server does.

A CBLManager and all the objects descending from it may only be used on a single thread. To work with databases on another thread, copy the database manager (by calling -copy) and use the copy on the other thread.

Method Documentation

+ (instancetype) sharedInstance

A shared per-process instance.

This should only be used on the main thread.

+ (BOOL) isValidDatabaseName: (NSString *)  name

Returns YES if the given name is a valid database name.

(Only the characters in "abcdefghijklmnopqrstuvwxyz0123456789_$()+-/" are allowed.)

+ (NSString*) defaultDirectory

The default directory to use for a CBLManager.

This is in the Application Support directory.

- (instancetype) init

Default initializer.

Stores databases in the default directory.

- (instancetype) initWithDirectory: (NSString *)  directory
options: (const CBLManagerOptions *)  options
error: (NSError **)  outError 

Initializes a CouchbaseLite manager that stores its data at the given path.

Parameters
directoryPath to data directory. If it doesn't already exist it will be created.
optionsIf non-NULL, a pointer to options (read-only and no-replicator).
outErrorOn return, the error if any.
- (instancetype) copy

Creates a copy of this CBLManager, which can be used on a different thread.

- (void) close

Releases all resources used by the CBLManager instance and closes all its databases.

- (CBLDatabase*) databaseNamed: (NSString *)  name
error: (NSError **)  outError 

Returns the database with the given name, creating it if it didn't already exist.

Multiple calls with the same name will return the same CBLDatabase instance. NOTE: Database names may not contain capital letters!

- (CBLDatabase*) existingDatabaseNamed: (NSString *)  name
error: (NSError **)  outError 

Returns the database with the given name, or nil if it doesn't exist.

Multiple calls with the same name will return the same CBLDatabase instance.

- (CBLDatabase*) objectForKeyedSubscript: (NSString *)  key

Same as -existingDatabaseNamed:.

Enables "[]" access in Xcode 4.4+

- (BOOL) replaceDatabaseNamed: (NSString *)  databaseName
withDatabaseFile: (NSString *)  databasePath
withAttachments: (NSString *)  attachmentsPath
error: (NSError **)  outError 

Replaces or installs a database from a file.

This is primarily used to install a canned database on first launch of an app, in which case you should first check .exists to avoid replacing the database if it exists already. The canned database would have been copied into your app bundle at build time.

Parameters
databaseNameThe name of the database to replace.
databasePathPath of the database file that should replace it.
attachmentsPathPath of the associated attachments directory, or nil if there are no attachments.
outErrorIf an error occurs, it will be stored into this parameter on return.
Returns
YES if the database was copied, NO if an error occurred.
- (void) doAsync:

Runs the block asynchronously on the database manager's dispatch queue or thread.

Unlike the rest of the API, this can be called from any thread, and provides a limited form of multithreaded access to Couchbase Lite.

- (void) backgroundTellDatabaseNamed: (NSString *)  dbName
to: (CBLDatabase *)  block 

Asynchronously dispatches a block to run on a background thread.

The block will be given a CBLDatabase instance to use; it must use that database instead of any CBL objects that are in use on the surrounding code's thread. Otherwise thread-safety will be violated, and Really Bad Things that are intermittent and hard to debug can happen. (Note: Unlike most of the API, this method is thread-safe.)

+ (void) enableLogging: (NSString *)  type

Enables Couchbase Lite logging of the given type, process-wide.

A partial list of types is here: http://docs.couchbase.com/couchbase-lite/cbl-ios/#useful-logging-channels It's usually more convenient to enable logging via command-line args, as discussed on that same page; but in some environments you may not have access to the args, or may want to use other criteria to enable logging.

Property Documentation

- (NSString*) directory
readatomicassign

The root directory of this manager (as specified at initialization time.)

- (NSArray*) allDatabaseNames
readatomicassign

An array of the names of all existing databases.

- (dispatch_queue_t) dispatchQueue
readwriteatomicstrong

The dispatch queue used to serialize access to the database manager (and its child objects.) Setting this is optional: by default the objects are bound to the thread on which the database manager was instantiated.

By setting a dispatch queue, you can call the objects from within that queue no matter what the underlying thread is, and notifications will be posted on that queue as well.

- (NSURL*) internalURL
readatomicassign

The base URL of the database manager's REST API.

You can access this URL within this process, using NSURLConnection or other APIs that use that (such as XMLHTTPRequest inside a WebView), but it isn't available outside the process. This method is only available if you've linked with the CouchbaseLiteListener framework.

- (NSMutableDictionary*) customHTTPHeaders
readnonatomicassign

The documentation for this class was generated from the following file: