For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.


Objective-C API examples

We can use JSONStore for MobileFirst applications.

The following sections contain example implementations for iOS devices with JSONStore APIs. Other helpful topics include:


Initialize and open connections, get an Accessor, and add data

// Create the collections object that will be initialized. JSONStoreCollection* people = [[JSONStoreCollection alloc] initWithName:@"people"]; [people setSearchField:@"name" withType:JSONStore_String]; [people setSearchField:@"age" withType:JSONStore_Integer]; // Optional options object. JSONStoreOpenOptions* options = [JSONStoreOpenOptions new]; [options setUsername:@"carlos"]; //Optional username, default 'jsonstore' [options setPassword:@"123"]; //Optional password, default no password // This object will point to an error if one occurs. NSError* error = nil; // Open the collections. [[JSONStore sharedInstance] openCollections:@[people] withOptions:options error:&error]; // Add data to the collection NSArray* data = @[ @{@"name" : @"carlos", @"age": @10} ]; int newDocsAdded = [[people addData:data andMarkDirty:YES withOptions:nil error:&error] intValue];


Initialize with a secure random token from the server

[WLSecurityUtils getRandomStringFromServerWithBytes:32 timeout:1000 completionHandler:^(NSURLResponse *response, NSData *data, NSError *connectionError) { // You might want to see the response and the connection error // before moving forward. // Get the secure random string by using the data that is // returned from the generator on the server. NSString* secureRandom = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]; JSONStoreCollection* ppl = [[JSONStoreCollection alloc] initWithName:@"people"]; [ppl setSearchField:@"name" withType:JSONStore_String]; [ppl setSearchField:@"age" withType:JSONStore_Integer]; // Optional options object. JSONStoreOptions* options = [JSONStoreOptions new]; [options setUsername:@"carlos"]; //Optional username, default 'jsonstore' [options setPassword:@"123"]; //Optional password, default no password [options setSecureRandom:secureRandom]; //Optional, default one will be generated locally // This points to an error if one occurs. NSError* error = nil; [[JSONStore sharedInstance] openCollections:@[ppl] withOptions:options error:&error]; // Other JSONStore operations (e.g. add, remove, replace, etc.) go here. }];


Find - locate documents inside the Store

// Get the accessor to an already initialized collection. JSONStoreCollection* people = [[JSONStore sharedInstance] getCollectionWithName:@"people"]; // This object will point to an error if one occurs. NSError* error = nil; // Add additional find options (optional). JSONStoreQueryOptions* options = [JSONStoreQueryOptions new]; [options setLimit:@10]; // Returns a maximum of 10 documents, default no limit. [options setOffset:@0]; // Skip 0 documents, default no offset. // Search fields to return, default: ['_id', 'json']. [options filterSearchField:@"_id"]; [options filterSearchField:@"json"]; // How to sort the returned values , default no sort. [options sortBySearchFieldAscending:@"name"]; [options sortBySearchFieldDescending:@"age"]; // Find all documents that match the query part. JSONStoreQueryPart* queryPart1 = [[JSONStoreQueryPart alloc] init]; [queryPart1 searchField:@"name" equal:@"carlos"]; [queryPart1 searchField:@"age" lessOrEqualThan:@10]; NSArray* results = [people findWithQueryParts:@[queryPart1] andOptions:options error:&error]; // results = @[ @{@"_id" : @1, @"json" : @{ @"name": @"carlos", @"age" : @10}} ]; for (NSDictionary* result in results) { NSString* name = [result valueForKeyPath:@"json.name"]; // carlos. int age = [[result valueForKeyPath:@"json.age"] intValue]; // 10 NSLog(@"Name: %@, Age: %d", name, age); }


Replace - change the documents that are already stored inside a Collection

// Get the accessor to an already initialized collection. JSONStoreCollection* people = [[JSONStore sharedInstance] getCollectionWithName:@"people"]; // Find all documents that match the queries. NSArray* docs = @[ @{@"_id" : @1, @"json" : @{ @"name": @"carlitos", @"age" : @99}} ]; // This object will point to an error if one occurs. NSError* error = nil; // Perform the replacement. int docsReplaced = [[people replaceDocuments:docs andMarkDirty:NO error:&error] intValue];


Remove - delete all documents that match the query

// Get the accessor to an already initialized collection. JSONStoreCollection* people = [[JSONStore sharedInstance] getCollectionWithName:@"people"]; // This object will point to an error if one occurs. NSError* error = nil; // Find document with _id equal to 1 and remove it. int docsRemoved = [[people removeWithIds:@[@1] andMarkDirty:NO error:&error] intValue];


Count - gets the total number of documents that match a query

// Get the accessor to an already initialized collection. JSONStoreCollection* people = [[JSONStore sharedInstance] getCollectionWithName:@"people"]; // Count all documents that match the query. // The default query is @{} which will // count every document in the collection. JSONStoreQueryPart *queryPart = [[JSONStoreQueryPart alloc] init]; [queryPart searchField:@"name" equal:@"carlos"]; // This object will point to an error if one occurs. NSError* error = nil; // Perform the count. int countResult = [[people countWithQueryParts:@[queryPart] error:&error] intValue];


Destroy - wipes data for all users, destroys the internal storage, and clears security artifacts

// This object will point to an error if one occurs. NSError* error = nil; // Perform the destroy. [[JSONStore sharedInstance] destroyDataAndReturnError:&error];


Security - close access to all opened Collections for the current user

// This object will point to an error if one occurs. NSError* error = nil; // Close access to all collections in the store. [[JSONStore sharedInstance] closeAllCollectionsAndReturnError:&error];


Security - change the password that is used to access a Store

// The password should be user input. // It is hardcoded in the example for brevity. NSString* oldPassword = @"123"; NSString* newPassword = @"456"; NSString* username = @"carlos"; // This object will point to an error if one occurs. NSError* error = nil; // Perform the change password operation. [[JSONStore sharedInstance] changeCurrentPassword:oldPassword withNewPassword:newPassword forUsername:username error:&error]; // Remove the passwords from memory. oldPassword = nil; newPassword = nil;


Push - get all documents that are marked as dirty, send them to a MobileFirst adapter, and mark them clean

// Get the accessor to an already initialized collection. JSONStoreCollection* people = [[JSONStore sharedInstance] getCollectionWithName:@"people"]; // This object will point to an error if one occurs NSError* error = nil; // Return all documents marked dirty NSArray* dirtyDocs = [people allDirtyAndReturnError:&error]; // ACTION REQUIRED: Handle the dirty documents here // (e.g. send them to a MobileFirst Adapter). // Mark dirty documents as clean int numCleaned = [[people markDocumentsClean:dirtyDocs error:&error] intValue];


Pull - get new data from a MobileFirst adapter

// Get the accessor to an already initialized collection. JSONStoreCollection* people = [[JSONStore sharedInstance] getCollectionWithName:@"people"]; // This object will point to an error if one occurs. NSError* error = nil; // ACTION REQUIRED: Get data (e.g. MobileFirst Adapter). // For this example, it is hardcoded. NSArray* data = @[ @{@"id" : @1, @"ssn": @"111-22-3333", @"name": @"carlos"} ]; int numChanged = [[people changeData:data withReplaceCriteria:@[@"id", @"ssn"] addNew:YES markDirty:NO error:&error] intValue];


Check whether a document is dirty

// Get the accessor to an already initialized collection. JSONStoreCollection* people = [[JSONStore sharedInstance] getCollectionWithName:@"people"]; // This object will point to an error if one occurs. NSError* error = nil; // Check if document with _id '1' is dirty. BOOL isDirtyResult = [people isDirtyWithDocumentId:1 error:&error];


Check the number of dirty documents

// Get the accessor to an already initialized collection. JSONStoreCollection* people = [[JSONStore sharedInstance] getCollectionWithName:@"people"]; // This object will point to an error if one occurs. NSError* error = nil; // Check if document with _id '1' is dirty. int dirtyDocsCount = [[people countAllDirtyDocumentsWithError:&error] intValue];


Remove a Collection

// Get the accessor to an already initialized collection. JSONStoreCollection* people = [[JSONStore sharedInstance] getCollectionWithName:@"people"]; // This object will point to an error if one occurs. NSError* error = nil; // Remove the collection. [people removeCollectionWithError:&error];


Clear all data that is inside a Collection

// Get the accessor to an already initialized collection. JSONStoreCollection* people = [[JSONStore sharedInstance] getCollectionWithName:@"people"]; // This object will point to an error if one occurs. NSError* error = nil; // Remove the collection. [people clearCollectionWithError:&error];


Start a transaction, add some data, remove a document, commit the transaction and roll back the transaction if there is a failure

// Get the accessor to an already initialized collection. JSONStoreCollection* people = [[JSONStore sharedInstance] getCollectionWithName:@"people"]; // These objects will point to errors if they occur. NSError* error = nil; NSError* addError = nil; NSError* removeError = nil; // We can call every JSONStore API method inside a transaction except: // open, destroy, removeCollection and closeAll. [[JSONStore sharedInstance] startTransactionAndReturnError:&error]; [people addData:@[ @{@"name" : @"carlos"} ] andMarkDirty:NO withOptions:nil error:&addError]; [people removeWithIds:@[@1] andMarkDirty:NO error:&removeError]; if (addError != nil || removeError != nil) { // Return the store to the state before start transaction was called. [[JSONStore sharedInstance] rollbackTransactionAndReturnError:&error]; } else { // Commit the transaction thus ensuring atomicity. [[JSONStore sharedInstance] commitTransactionAndReturnError:&error]; }


Get file information

// This object will point to an error if one occurs NSError* error = nil; // Returns information about files JSONStore uses to persist data. NSArray* results = [[JSONStore sharedInstance] fileInfoAndReturnError:&error]; // => [{@"isEncrypted" : @(true), @"name" : @"carlos", @"size" : @3072}]

Parent topic: JSONStore examples