The iOS 5 Developer's Cookbook: iCloud Basics

This chapter is from the book

iOS 5 Developer's Cookbook, The: The Additional Recipes: Additional Recipes Found Only in the Expanded Electronic Edition

Learn More Buy

This chapter is from the book

This chapter is from the book 

iOS 5 Developer's Cookbook, The: The Additional Recipes: Additional Recipes Found Only in the Expanded Electronic Edition

Learn More Buy

Recipe: UIManagedDocument and Core Data

The UIManagedDocument class allows you to work with ubiquitous Core Data stores with iCloud. This class integrates data with the cloud. It offers all the built-in services you need for a Core Data–compliant managed model object and extends those services to ubiquitous files. At the time this chapter was written, support for this new class was just coming online. Keep that preliminary nature in mind as you read this section as details have likely changed.

Although the class is derived from UIDocument, there are basic differences between the way you use UIManagedDocument and UIDocument:

• You may want to use the data container, and not Documents—That’s because the default Core Data store created by UIManagedDocument (i.e., not a standard SQLite store) contains a rather complex file structure. Moving out of the Documents folder allows you to handle those items as a single unit rather than expose the individual files to the end user in his or her iCloud preferences.
• Listen for persistent store content changes—In addition to document state changes, your application needs to listen for persistent store updates. NSPersistentStoreDidImportUbiquitousContentChangesNotification indicates your application should merge iCloud changes into your managed context.
• Merge external changes—Use a method similar to the one discussed in this recipe to integrate inserted, modified, or deleted objects into your data store.
• Do not save your changes—Unlike UIDocument, where you can save both early and often, you only save a UIManagedDocument on creation—and you do so there in a rather tricky fashion, as you’ll see in the steps that follow.

Keep these differences in mind as you move forward to the following how-to write-up.

Remove All Context Saves

The first iCloud refactoring step involves removing all context saves from your application. Any time you see code like this,

NSError *error = nil;
if (![context save:&error])
    NSLog(@"Error: %@", [error localizedDescription]);

go ahead and comment it out. UIManagedDocument handles all context saves for you.

Establish Your Identifiers and URLs

Your application should establish two key identifiers that you will use throughout your managed document implementation. They include

• A real-world ready name that your new file will use when it is saved to the sandbox (e.g., “ToDo”)
• A unique name to use when saving the managed store to the cloud. Use a standard reverse-domain style for this private identifier, according to Apple standards.

Here’s how those identifiers might look in your source file:

#define SharedFileName   @"ToDo"
#define PrivateName     @"com.sadun.CloudLearning.storage"

Next, create two key URLs that build on these identifiers. The first is a local URL. It points to the sandbox and uses the real-world file name. The second is a cloud URL. It points to the data storage area of your ubiquitous container and uses the private reverse domain identifier.

NSURL *localURL = [CloudHelper localFileURL:SharedFileName];
NSURL *cloudURL = [CloudHelper ubiquityDataFileURL:PrivateName];

The local and cloud URLs work as a pair. The local item points to a sandbox shell. The managed document links that shell to the persistent store, which is located in the ubiquitous container at the cloud URL.

Establish the Document

Create a new managed document object by allocating it and pointing it to the sandbox URL. Your UIManagedDocument instance should always point to the sandbox item and not to the ubiquitous persistent store. Here’s how you can set up the object with the local URL:

// Establish the document by pointing to the local sandbox
document = [[UIManagedDocument alloc] initWithFileURL:localURL];

The document’s persistent store options declare the content name and include a pointer to the cloud URL. They also should establish that the store migrates its data automatically and use an inferred mapping model. Set the options like this:

// Set the persistent store options to point to the cloud
NSDictionary *options = [NSDictionary dictionaryWithObjectsAndKeys:
    PrivateName, NSPersistentStoreUbiquitousContentNameKey,
    cloudURL, NSPersistentStoreUbiquitousContentURLKey,
    [NSNumber numberWithBool:YES],
        NSMigratePersistentStoresAutomaticallyOption,
    [NSNumber numberWithBool:YES],
        NSInferMappingModelAutomaticallyOption,
    nil];
document.persistentStoreOptions = options;

Once you’re done setting the store options, you’re ready to read in the file if it exists or create it. Allocating a document and setting its URL does not open the file; it merely creates an instance of the class. You must use that instance to save or open the file.

Opening the Document

Here’s a basic rule of thumb: When the sandbox item exists, you can assume that the ubiquitous store it links to exists as well. The converse is not true. A ubiquitous store created on another device might not have a local shell component. In that case, you can create one.

Test for the sandbox file using NSFileManager and the local URL. If the file exists, open it and perform a first fetch on its data. You’re then ready to start operating as you normally do.

if ([helper isLocal:SharedFileName])

{
    NSLog(@"Attempting to open existing file");
    [document openWithCompletionHandler:^(BOOL success){
        if (!success) {NSLog(@"Error opening file"); return;}
        NSLog(@"File opened");
        [self performFetch];;
    }];
}

When the file is not available, create it in the sandbox. Do this regardless of whether the ubiquitous file exists or not. If it exists, the sandbox shell links to it. If it does not, both “files” are created at the same time.

This snippet creates the file, closes it, and then opens it up again. This is probably overkill, but I found that it works consistently in my testing and, when skipping these steps, it does not. Your mileage is sure to vary, especially after the beta period for this new release is over and this book goes live. When the ubiquitous portion does not yet exist, UIManagedDocument automatically creates the persistent store component in the location you specified in its options. In the end, the document exists in two places on each device: the store in the cloud and the wrapper in the sandbox.

{

    NSLog(@"Creating file.");
    // 1. save it out, 2. close it, 3. read it back in.
    // You probably can get away with doing less
    [document saveToURL:localURL
       forSaveOperation:UIDocumentSaveForCreating
       completionHandler:^(BOOL success){
           if (!success) { NSLog(@"Error creating file"); return; }
           NSLog(@"File created");
           [document closeWithCompletionHandler:^(BOOL success){
               NSLog(@"Closed new file: %@", success ?
                   @"Success" : @"Failure");
               [document openWithCompletionHandler:^(BOOL success){
                    if (!success) {
                        NSLog(@"Error opening file for reading.");
                           return;}
                        NSLog(@"File opened for reading.");
                        [self performFetch];;
           }];

         }];
    }];
}

Start Observing

Edits on each device are propagated out via iCloud updates. You need to listen for persistent store updates to respond to these changes, so subscribe in your setup to the following notification:

[[NSNotificationCenter defaultCenter]addObserver:self
    selector:@selector(documentContentsDidUpdate:)
    name:NSPersistentStoreDidImportUbiquitousContentChangesNotification
    object:nil];

Implement a cloud-updated method (the name is arbitrary, although documentContentsDidUpdate: is typical) to match the notification selector. The following method relays the notification data to an asynchronous method that merges the update with the current store:

- (void) documentContentsDidUpdate: (NSNotification *) notification
{
  NSDictionary* userInfo = [notification userInfo];
  [context performBlock:^{
    [self mergeiCloudChanges:userInfo forContext:context];}];
}

From here, it’s up to the mergeiCloudChanges:forContext: method, which you can read through in Recipe 18-4, to manage those merges. This code is again adapted from Apple sample code. It iterates through the updated, refreshed, and invalidated objects and applies those changes to the local managed context.

The merging rounds out the updates made to the standard Core Data application. All other elements of your app can remain as they were prior to iCloud integration.

Recipe 18-4 Ubiquitous Core Data

#pragma mark Initialize the Core Data Stores

- (void) initCoreData
{
    NSURL *localURL = [CloudHelper localFileURL:SharedFileName];
    NSURL *cloudURL = [CloudHelper ubiquityDataFileURL:PrivateName];

    // Create the document pointing to the local sandbox
    document = [[UIManagedDocument alloc] initWithFileURL:localURL];

    // Set the persistent store options to point to the cloud
    NSDictionary *options = [NSDictionary dictionaryWithObjectsAndKeys:
        PrivateName,
            NSPersistentStoreUbiquitousContentNameKey,
        cloudURL,
            NSPersistentStoreUbiquitousContentURLKey,
        [NSNumber numberWithBool:YES],
            NSMigratePersistentStoresAutomaticallyOption,
        [NSNumber numberWithBool:YES],
            NSInferMappingModelAutomaticallyOption,
  nil];
    document.persistentStoreOptions = options;
    context = document.managedObjectContext;

    // Register as presenter
    coordinator = [[NSFileCoordinator alloc]
        initWithFilePresenter:document];
    [NSFileCoordinator addFilePresenter:document];

    // Check at the local sandbox
    if ([helper isLocal:SharedFileName])
    {
      NSLog(@"Attempting to open existing file");
        [document openWithCompletionHandler:^(BOOL success){
            if (!success) {NSLog(@"Error opening file"); return;}
            NSLog(@"File opened");

            [self performFetch];;
        }];
  }
  else
  {
        NSLog(@"Creating file.");
        // 1. save it out, 2. close it, 3. read it back in.
        // You probably can get away with doing less
        [document saveToURL:localURL
           forSaveOperation:UIDocumentSaveForCreating
         completionHandler:^(BOOL success){
             if (!success) { NSLog(@"Error creating file"); return; }
             NSLog(@"File created");
            [document closeWithCompletionHandler:^(BOOL success){
                NSLog(@"Closed new file: %@", success ?
                    @"Success" : @"Failure");
            [document openWithCompletionHandler:^(BOOL success){
                   if (!success) {
                      NSLog(@"Error opening file for reading.");
                      return;}
                   NSLog(@"File opened for reading.");

                   [self performFetch];;
         }];
       }];
     }];
  }

  // Register to be notified of changes to the persistent store
  [[NSNotificationCenter defaultCenter]addObserver:self
        selector:@selector(documentStateChanged:)
        name: NSPersistentStoreDidImportUbiquitousContentChangesNotification
        object:nil];
}

#pragma mark Courtesy of Apple. Thank you Apple
// Merge the iCloud changes into the managed context
- (void)mergeiCloudChanges: (NSDictionary*)userInfo
    forContext: (NSManagedObjectContext*)managedObjectContext
{
  @autoreleasepool

  {
        NSMutableDictionary *localUserInfo =
          [NSMutableDictionary dictionary];

        // Handle the invalidations
        NSSet* allInvalidations =
            [userInfo objectForKey:NSInvalidatedAllObjectsKey];
        NSString* materializeKeys[] = { NSDeletedObjectsKey,
               NSInsertedObjectsKey };
        if (nil == allInvalidations)
        {
            int c = (sizeof(materializeKeys) / sizeof(NSString*));
            for (int i = 0; i < c; i++)
            {
        NSSet* set = [userInfo objectForKey:materializeKeys[i]];
        if ([set count] > 0)
        {
          NSMutableSet* objectSet = [NSMutableSet set];
          for (NSManagedObjectID* moid in set)
              [objectSet addObject:[managedObjectContext
                  objectWithID:moid]];
         [localUserInfo setObject:objectSet
              forKey:materializeKeys[i]];
        }
      }
            // Handle the updated and refreshed Items
            NSString* noMaterializeKeys[] = { NSUpdatedObjectsKey,
                NSRefreshedObjectsKey, NSInvalidatedObjectsKey };
            c = (sizeof(noMaterializeKeys) / sizeof(NSString*));

            for (int i = 0; i < 2; i++)
            {
                NSSet* set = [userInfo objectForKey:noMaterializeKeys[i]];
                if ([set count] > 0)
                {
                    NSMutableSet* objectSet = [NSMutableSet set];
                    for (NSManagedObjectID* moid in set)
                    {
                         NSManagedObject* realObj =
                            [managedObjectContext
                                objectRegisteredForID:moid];
                         if (realObj)
                            [objectSet addObject:realObj];
          }
          [localUserInfo setObject:objectSet
              forKey:noMaterializeKeys[i]];
        }
      }
      // Fake a save to merge the changes
      NSNotification *fakeSave = [NSNotification
        notificationWithName:
            NSManagedObjectContextDidSaveNotification
        object:self userInfo:localUserInfo];
      [managedObjectContext
          mergeChangesFromContextDidSaveNotification:fakeSave];
    }
    else
      [localUserInfo setObject:allInvalidations
          forKey:NSInvalidatedAllObjectsKey];

    [managedObjectContext processPendingChanges];
    [self performSelectorOnMainThread:@selector(performFetch)
      withObject:nil waitUntilDone:NO];
  }
}

// When notified about a cloud update, start merging changes
- (void) documentContentsDidUpdate: (NSNotification *) notification
{
  NSLog(@"Cloud has been updated.");
  NSDictionary* userInfo = [notification userInfo];
  [context performBlock:^{
      [self mergeiCloudChanges:userInfo forContext:context];}];
}