Jan 2009
Blog | Aug 2008

Cocoa network persistence

09/01/09 12:47 Filed in: Watershed

Persisting NSDictionary ‘documents’ into the multi–user CouchDB store across the network

Apache CouchDB is a distributed, fault-tolerant and schema-free document-oriented database. CouchDB does support data structures within the document but deep hierarchies are best served using a relational database.

Document elements are stored in a JSON representation within a document. There is a natural “impedance match” between JSON and Cocoa’s Property List objects with the exception of NSDate. Dates will need to be serialised into strings.

Collections of documents are grouped in Views, specified by Map Reduce functions written in Javascript.

CouchDB has a low barrier to entry. CouchDB’s most beneficial feature to Watershed’s situation now is the casual integration with all categories of applications and the ease with which sophisticated shared storage is possible from application resource–sensitive client environments such as Cocoa on the iPhone and Javascript applications.

NSMutableDictionary Category

Persistence is achieved in Cocoa by using NSMutableDictionary as the container for each document. Each document can be identified by the identifer and the revision, stored in the dictionary using the NSString keys _id and _rev. The documents are mutable to track revisions over time. The persistence is implemented using a category on NSMutableDictionary. We haven’t done much work here—just assembled the pieces Lego style. Most of the hard work is done by json-framework which will need to be included in the project.

The category, composing of two methods, is partially listed below:

  1. #define COUCHDB_ID_KEY @"_id"
  2. #define COUCHDB_REV_KEY @"_rev"
  3. #define HTTP_METHOD_POST @"POST"
  4. #define HTTP_METHOD_PUT @"PUT"
  7. @implementation NSMutableDictionary (NSDictionary_FBTFCouchDB)
  10. + (id)dictionaryFromDocumentStore:(NSURL *)storeURL withIdentifier:(NSString *)identifer {
  11. if (!storeURL || !identifer) return nil;
  12. NSURLRequest *request = [NSURLRequest requestWithURL:[NSURL URLWithString:identifer relativeToURL:storeURL] cachePolicy:NSURLRequestUseProtocolCachePolicy timeoutInterval:30.0];
  13. NSError *error = nil;
  14. NSURLResponse *response = nil;
  15. NSData *responseData = [NSURLConnection sendSynchronousRequest:request returningResponse:&response error:&error];
  16. if (error) {
  17. NSLog(@"Network Connection Error: %@", [error localizedDescription]);
  18. return nil;
  19. }
  21. // Couch uses UTF8 encoding for transfers
  22. NSString *jsonString = [[NSString alloc] initWithData:responseData encoding:NSUTF8StringEncoding];
  23. if (!jsonString) return nil;
  25. error = nil;
  26. SBJSON *jsonParser = [[SBJSON alloc] init];
  27. id result = [jsonParser objectWithString:jsonString allowScalar:YES error:&error];
  29. [jsonString release];
  30. [jsonParser release];
  32. if (error) {
  33. NSLog(@"JSON Parse Error: %@", [error localizedDescription]);
  34. return nil;
  35. }
  36. return result;
  37. }
  40. - (BOOL)persistInDocumentStore:(NSURL *)storeURL {
  41. // We do both inserts and updates in this method
  42. NSString *methodName;
  43. NSURL *requestURL;
  44. if ([self objectForKey:COUCHDB_ID_KEY]) {
  45. // this dictionary originated from the document database so update by including ID in URL
  46. methodName = HTTP_METHOD_PUT;
  47. requestURL = [NSURL URLWithString:[self objectForKey:COUCHDB_ID_KEY] relativeToURL:storeURL];
  48. } else {
  49. // This is a new Dictionary so we are inserting
  50. methodName = HTTP_METHOD_POST;
  51. requestURL = storeURL;
  52. }
  54. NSMutableURLRequest *aRequest = [[NSMutableURLRequest alloc] initWithURL:requestURL];
  55. [aRequest setHTTPMethod:methodName];
  57. NSError *error = nil;
  58. SBJSON *jsonParser = [[SBJSON alloc] init];
  59. NSString *argsData = [jsonParser stringWithObject:self allowScalar:NO error:&error];
  61. if (error) {
  62. NSLog(@"JSON Serialisation Error: %@", [error localizedDescription]);
  63. return NO;
  64. }
  66. // Finish setting up the request and send to document store
  67. [aRequest setHTTPBody: [argsData dataUsingEncoding:NSUTF8StringEncoding]];
  68. NSURLResponse *response = nil;
  69. error = nil;
  70. NSData *responseData = [NSURLConnection sendSynchronousRequest:aRequest returningResponse:&response error:&error];
  71. [aRequest release];
  73. // Now parse the results
  74. NSString *result = [[NSString alloc] initWithData:responseData encoding:NSUTF8StringEncoding];
  75. error = nil;
  76. NSDictionary *results = [jsonParser objectWithString:result allowScalar:NO error:&error];
  77. if (error || [results objectForKey:@"error"]) {
  79. // Something went wrong. report, clean up and return
  80. if (error) {
  81. NSLog(@"Can not parse results: %@", [error localizedDescription]);
  82. } else {
  83. NSLog(@"Database Error: %@", [results valueForKey:@"reason"]);
  84. }
  85. [jsonParser release];
  86. [result release];
  87. return NO;
  88. } else {
  90. // update the revision and the id (in case this is an insertion we do both)
  91. [self setValue:[results valueForKey:@"id"] forKey:COUCHDB_ID_KEY];
  92. [self setValue:[results valueForKey:@"rev"] forKey:COUCHDB_REV_KEY];
  93. [jsonParser release];
  94. [result release];
  95. return YES;
  96. }
  97. }
  100. @end

Other Possibilities & Further Development

The next step will be creating a database co–ordinator or connection proxy to manage persistence in a more sophisticated fashion. This can support features such as authentication & authorisation, revisions, rollback & merging of documents and the efficient storage & retrieval of collections.

Whilst CouchDB is not an object database and doesn’t encourage deep hierarchies, we’ve experimented recently combining CouchDB documents with Core Data’s NSManagedObjects by keeping document identifiers in managed objects and merging at display time. In the other direction, NSManagedObjects’ snapshots can easily be included in documents in the store when the NSManagedObject is saved in the context.

CouchDB is a peer-based distributed database system, it allows for users and servers to access and update the same shared data while disconnected and then bi-directionally replicate those changes later. We’d like to look into the possibility of using Couch, embedded in the desktop application bundle, locally and then allow CouchDB to replicate and sync between different instances as they appear on the network.

Tags: ,

|

odds&ends…
Benjamin Miller