Inherits from NSObject
Declared in JDBDatabase.h

Overview

JDBDatabase is the entry point of JsonDB.

It gives acces to the set of collection (JDBCollection).

Example

// Create a file path where to open/save the database (here, on iOS, in the application's Document directory)
NSString *dbPath = [[NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject] stringByAppendingPathComponent:@"/main.jsondb"];

// Create/open a database at the specified path
JDBDatabase *database = [JDBDatabase databaseAtPath:dbPath];

// Create/get a collection of document
JDBCollection *collection = [database collection:@"GameScore"];

// Insert schema less JSON documents into the collection
[collection save:@{@"playerName": @"Sean Plott", @"score": @1337, @"cheatMode": @NO}];
[collection save:@{@"playerName": @"John Smith", @"score": @9001, @"cheatMode": @NO}];
[collection save:@{@"playerName": @"John Appleseed", @"score": @1234, @"cheatMode": @YES}];

// Find who is cheating (this will returns an array of document)
NSArray *cheaters = [[collection find:@{@"cheatMode": @YES}] all];
expect(cheaters).to.haveCountOf(1);
expect(cheaters[0][@"playerName"]).to.equal(@"John Appleseed");

// Find the Johns ordered alphabetically
NSArray *johns = [[collection find:@{@"playerName": @{@"$like": @"John %"}} sort:@[@"playerName"]] all];
expect(johns).to.haveCountOf(2);
expect(cheaters[0][@"playerName"]).to.equal(@"John Appleseed");

// Find the first one with a score over 9000, flag it as a cheater and return the old document
NSDictionary *over9000 = [[collection find:@{@"score": @{@"$gt": @9000}}] firstAndModify:^JDBModifyOperation(NSMutableDictionary *document) {
    document[@"cheatMode"] = @YES;
    return JDBModifyOperationUpdate | JDBModifyOperationReturnOld;
}];
expect(over9000[@"cheatMode"]).to.equal(NO);

Thread safety

All JDBDatabase instances, also its JDBCollection, JDBView and JDBQuery are thread safe.

Many thread can use those objects to read and write to the database at the same time.

But you have to keep in mind that:

  • all write operations (save, modify and remove) are performed sequencially in their transaction.
  • all read operations (find, count) are performed in parrallel and see what is commited only.

Mutability

When a non mutable object is expected in a method signature or returns by the method, the library actually expect it to not be mutated, no defensive copy are made.

Tasks

Other Methods

Database creation

Collections access

Properties

errorHandler

@property (copy) JDBErrorHandler errorHandler
Discussion

The global error handler (JDBErrorHandler). Defaults to JDBErrorHandlerDefault wich is implemented with only a simple NSLog to the console.

Declared In

JDBDatabase.h

identifierFactory

@property (copy) JDBIdentifierFactory identifierFactory
Discussion

The global identifier factory (JDBIdentifierFactory). Defaults to JDBIdentifierFactoryDefault wich is implemented with a return [[NSUUID UUID] UUIDString];.

Declared In

JDBDatabase.h

Class Methods

databaseAtPath:

+ (instancetype)databaseAtPath:(NSString *)path
Discussion

Alloc and init an persistent JDBDatabase with default option values.

Parameters

path

The file path where to save the database

Return Value

A new persistent JDBDatabase

Declared In

JDBDatabase.h

databaseAtPath:withOptions:

+ (instancetype)databaseAtPath:(NSString *)path withOptions:(NSDictionary *)options
Discussion

Alloc and init an persistent JDBDatabase with default option values.

Parameters

path

The file path where to save the database

Return Value

A new persistent JDBDatabase

Declared In

JDBDatabase.h

databaseInMemory

+ (instancetype)databaseInMemory
Discussion

Alloc and init an in memory JDBDatabase with default option values.

Return Value

A new in mempry JDBDatabase

Declared In

JDBDatabase.h

databaseInMemoryWithOptions:

+ (instancetype)databaseInMemoryWithOptions:(NSDictionary *)options
Discussion

Alloc and init an in memory JDBDatabase with default option values.

Return Value

A new in mempry JDBDatabase

Declared In

JDBDatabase.h

Instance Methods

cleanup

- (void)cleanup

collection:

- (JDBCollection *)collection:(NSString *)name
Discussion

Get (after creating it if not already created) a collection of document given its name.

Parameters

name

The name of the collection

Return Value

Declared In

JDBDatabase.h

collectionNames

The collection’s name managed by this database.

- (NSArray *)collectionNames

Return Value

The collection’s name managed by this database.

Declared In

JDBDatabase.h