Using UIManagedDocument and iCloud together presents some challenges because they don’t play nicely together without some additional work.

One of the main issues that has to be addressed is how to deal with moving documents to and from iCloud in response to the user changing their iCloud preference settings.

Core Data documents don’t really get moved into iCloud, even though we use this terminology. What really happens with an iCloud enabled Core Data document is that change logs get shared via iCloud and peer devices import these change logs into their own local database.  The UIManagedDocument class provides a wrapper that makes creating the Core Data stack easy, but unfortunately UIManagedDocument does not work well with iCloud even though it inherits from UIDocument, which is supposed to work with iCloud.

In this article we will show how one can create a DocumentManager subclass that will make migration to and from iCloud easier.  See the following link for a video demonstrating the iCloud enabled UIManagedDocument in action.

Understanding Core Data and Data Replication

Core Data uses log shipping to replicate database changes between devices.  Each device has it’s own unique database and, when used with the iCloud options, Core Data writes transaction logs each time something gets changed. These transaction logs are replicated to other devices using iCloud’s file replication.

On the receiving device the transaction logs are imported into the local database.  Normal database integrity constraints are applied so it is possible that integrity of the database can be corrupted if the user performs simultaneous transactions on two connected devices.  Ensuring that data integrity is maintain is the responsibility of the application which will need to apply rules that are application for the business domain.

The diagram below shows a typical standalone application that uses Core Data. The application accesses objects in the database via a managedObjectContext.

When we refer to moving a UIManagedDocument to iCloud we do not mean moving the actual database file to iCloud and sharing it that way, we mean opening with iCloud options such that change logs are written to the shared iCloud container.

We can share the actual database file itself in iCloud but this is not an efficient way to replicate data for most applications because any small change will result in the entire file being replicated, whereas log shipping means only the changes are replicated. However this does mean that each peer needs to have its own copy of the database into which they can import these changes.

Note that for applications that continuously make updates to the same data it might be more efficient to replicate the entire database file rather than replicating the change logs.

One of the main challenges with the transaction logs synchronisation approach arises when we have an existing database that we want to now share via iCloud.  We can’t just turn on log shipping because peers would then only receive changes from this point – we need some way of generating transaction logs that will allow peers to recreate the entire database from scratch.  With Core Data this is know as migrating the store with iCloud options, and essentially requires building a new local store such that during the building of this store transaction logs are generated in iCloud that allow peer devices to build a copy from scratch too. Core Data proves an API for migrating stores (store is a Core Data term used to describe the actual database file).

To further complicate matters iOS provides UIManagedDocument which is meant to make using Core Data easier, however use of UIManagedDocument with iCloud is poorly documented, and it’s not at all clear when one should be using a native Core Data stack or when one should be using UIManagedDocuments.

Multi-Document vs Library Style Apps

Our aim is to show how it is possible to support both document based and library style applications using UIManagedDocument and iCloud.  Firstly we are going to show how create a document based application and then we will show how to support a library style application using a subset of the functions developed for the document based application.

Each style has a unique set of requirements:

• Document based applications need mechanisms to detect new files created by peers and files that have been removed by peers.
• Library style apps needs ways to handle the creation and merging of seed data, particularly when two peers have each built their own copy of the initial database (if you are happy just using the native Core Data stock then see here for a sample iOS library style Core Data app with iCloud integration).

Note the following:

1. We use a file naming convention as follows:

• local files are named using the user entered FILENAME
• iCloud files are named using the user entered FILENAME+”_UUID_”+uuid

2. We use the same iCloud filename for the ubiquityNameKey. We also use this naming convention to tell whether a document is shared via iCloud or not.  We can’t tell if a file is in iCloud by looking in iCloud if the user has logged out of iCloud.

3. We are also always using ROLLBACK journal mode because of strange things that have been encountered when using the default WAL mode.

4. We always store documents in the local app /Documents directory. We never put the UIManagedDocument package in the ubiquity container.

5. We support the creation of multiple documents in the app. Apps which only use a single document will probably not need to use the UUID and can use a hardcoded filename and set some additional attributes in the documents metadata to tell if its shared in iCloud or not.

6. We strip off the “_UUID_”+uuid when we display the filename to the user.

7. We scan the ubiquity containers /CoreData subdirectory which contains a subdirectory for each ubiquityNameKey representing each document shared via iCloud. These subdirectories contain the transaction log files used to replicate data.

Implementation

Two classes are primarily used to manage documents under iOS.  OSDocumentManager and OSManagedDocument, a UIManagedDocument subclass.  Two additional classes are involved in the process.  OSDocumentManager initiates the relocation of files in response to changes to the app settings detected when the AppDelegate class triggers a check or when it received a notification that the iCloud account has changed.

OSDocumentManager initiates removal of an iCloud store once it has been migrated to a local store using Core Data APIs, and then removes the local copy of the iCloud store once it detects that Core Data has removed the iCloud data associated with the document. [diagram needs to be updated to reflect recent changes].

The AppDelegate detects these changes to iCloud settings through one of the following delegate methods:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions;

- (void)applicationWillEnterForeground:(UIApplication *)application;

In practice the settings can only be changed by the user if they switch to the Settings app so we think all cases are covered by the two delegate methods.  But then if the app ran in the background things might be different, or if the device could log the user out of iCloud when they still running the app.

Changes to the iCloud settings triggers the following:

• iCloud Account is active and Data & Documents is ON
• Changes to the user preference turning OFF the ‘Use iCloud’ setting prompts the user to indicate whether they want to keep local copies, delete the iCloud files or keep using iCloud.
• Changes to the user preference turning ‘Use iCloud’ ON does not prompt the user but results in OSDocumentManager automatically migrating local files to iCloud
• iCloud is turned OFF (log out or turn Data & Documents OFF)
• The user if given a message indicating that iCloud files will not be accessible and to turn iCloud on if they wish to access the iCloud files again
• iCloud is turned ON (logged in or turned Data & Documents ON)
• If the app is first run (user preference has not been set previously) then the user is asked if they would like to Use iCloud and the user preference is saved
• If the user selects YES then new files are created in iCloud and local copies are created from any existing iCloud files (continuous scan for new or removed iCloud files)

If the user selects to keep the files locally then OSDocumentManager iterates over all the iCloud files, creates an OSManagedDocument for the file and tells it to migrate to a local file, creating the local file this is done synchronously and if it returns successfully OSDocumentManager deletes the iCloud store and the associated UIManagedDocument package.

OSManagedDocument migrates local files to iCloud by first creating a new UIManagedDocument using the local filename convention and then removing the UIManagedDocument’s store from the persistentStoreCoordinator, adding the store from the local file and migrating this store to the same fileURL as the removed store.  Creating the UIManagedDocument is done asynchronously so we have a callback to OSDocumentManager that gets called when the migration is done and the file is closed.  OSDocumentManager then removes the local file.

To create local files from iCloud files is basically exactly the same except we remove all iCloud options when creating the new store. Once the new store is build in the new UIManagedDocument package the OSDocumentManager call back is called and OSDocumentManager then removes the iCloud store and the local UIManagedDocument is removed by the FileListViewController when it detects the removal of the iCloud document.

To complicate matters further we use a File Browser (FileListViewController) that continuously scans for new or removed iCloud files and initiates building or removing local copies.  Because the creation of local and iCloud files does not happen simultaneously we have to block the scans while we are creating or removing files, otherwise it might detect a new file in iCloud and think that because there is not yet a local file it needs to create one.

Library Style Apps
For library style apps that use only a single document the following approach should be used:

• Use two UIManagedDocuments called DB and DB_ICLOUD (or similar) and migrate between them depending on the users Use iCloud preference setting.
• In the UIManagedDocument subclass – (void)moveDocumentToICloud method use the following code to create the document name

      // Create the new iCloud filename
      NSString *documentName = [NSString stringWithFormat:@“%@_ICLOUD”,[sourceDocumentURL lastPathComponent]];

• In the – (void)moveDocumentToLocal method use this line of code

      // Create the new local filename
      NSString *documentName = [[[sourceDocumentURL lastPathComponent] componentsSeparatedByString:@“_ICLOUD”] objectAtIndex:0];

And then change the code in OSDocumentManager to look for a file with or without _ICLOUD in the name and migrate the file if required. Once that’s done set self.managedDocument = DB or DB_ICLOUD depending on the selected preference.

The AppDelegate Methods

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
	    [[OSDocumentManager sharedManager] checkUserICloudPreferenceAndSetupIfNecessary];

}
- (void)applicationWillEnterForeground:(UIApplication *)application
{
	    [[OSDocumentManager sharedManager] performApplicationWillEnterForegroundCheck];

}
- (void)applicationDidEnterBackground:(UIApplication *)application
{

    [[OSDocumentManager sharedManager] saveDocument];

}
- (void)applicationWillTerminate:(UIApplication *)application
{

    [[OSDocumentManager sharedManager] closeDocument];

}

The OSDocumentManager Methods

- (void)checkUserICloudPreferenceAndSetupIfNecessary
{
    // Check preferences and take action as required
}
- (void)performApplicationWillEnterForegroundCheck
{
    // Check preferences and take action as required
}
- (void)promptUserAboutICloudDocumentStorage
{
    // Create alert asking user what action to take
}

- (void)setIsCloudEnabled:(BOOL)isCloudEnabled
{

    [self migrateFilesIfRequired];

}
- (void)migrateFilesIfRequired
{

        // If iCloud has been ENABLED migrate local files to iCloud
        [self migrateLocalFilesToICloud];

        // If iCloud has been DISABLED migrate iCloud files to local
        [self migrateLocalFilesToLocal];

}
- (void)migrateICloudFilesToLocal
{

        // We do them one at a time otherwise the app hangs
        // Once the FileListViewController deletes the local copy
        // migrateFilesIfRequired will get called again to get the next one

        [self migrateICloudFileToLocal:fileURL];

}
- (void)migrateICloudFileToLocal:(NSURL*)fileURL
{

            OSManagedDocument *document = [[OSManagedDocument alloc] initWithFileURL:fileURL];
            document.delegate = self;

            [document moveDocumentToLocal];

}
- (void)migrateLocalFilesToICloud
{

    // App seems to be OK if we just loop through them all without waiting
    for (NSURL *fileURL in docs) {

        [self migrateLocalFileToiCloud:fileURL];

    }

}
- (void)migrateLocalFileToiCloud:(NSURL*)fileURL
{

        OSManagedDocument *document = [[OSManagedDocument alloc] initWithFileURL:fileURL];
        document.delegate = self;
        [document moveDocumentToICloud];

}
- (void)fileMigrated:(NSURL*)migratedURL success:(bool)success
{

        // If it is a local file then delete it
        NSFileManager* fileManager = [[NSFileManager alloc] init];
        NSError *er;
        bool res = [fileManager removeItemAtURL:migratedURL error:&er];
        [self postFileUpdateNotification];

        // If it is an iCloud file then remove the store and iCloud data
        // Our iCloud scanner will then detect this removal and remove the local
        // copy
        [self deleteDocumentAtURL:migratedURL];

}
- (void)deleteDocumentAtURL:(NSURL*)fileURL
{

        // Open UIManagedDocument
        UIManagedDocument *doc = [[UIManagedDocument alloc] initWithFileURL:fileURL];

        [doc openWithCompletionHandler:^(BOOL success){
                if (success) {
                	[self removeDocStoresAndClose:doc];
		        }
            }];

}
- (void)removeDocStoresAndClose:(UIManagedDocument *)aDoc
{

        NSURL *storeURL = [[[aDoc managedObjectContext] persistentStoreCoordinator] URLForPersistentStore:store];

        NSError *error;
        NSString *fileName = [[fileURL URLByDeletingPathExtension] lastPathComponent];

        result = [NSPersistentStoreCoordinator removeUbiquitousContentAndPersistentStoreAtURL:storeURL

}
- (void)deleteLocalCopyOfiCloudDocumentAtURL:(NSURL*)fileURL
{
    // When async file delete is completed then call
    [self migrateFilesIfRequired];

}

The UIManagedDocument Methods

- (void)moveDocumentToICloud
{

    // Create a new UIManagedDocument
    OSManagedDocument *newDocument = [[OSManagedDocument alloc] initWithFileURL:destinationURL];

    // Save it and in the completion handler migrate the old store
    [newDocument saveToURL:destinationURL forSaveOperation:UIDocumentSaveForCreating completionHandler:^(BOOL success){

        // Now that we have created a new OSManagedDocument remove the store that was created by UIManagedDocument and migrate the local store to the same location

        NSPersistentStore *store = [[psc persistentStores] objectAtIndex:0];
        // get the store URL
        NSURL *storesURL = store.URL;

        // Now remove the existing store
        [pscForSave removePersistentStore:store error:&removeStoreError];

        // Add the local store
        id sourceStore = [pscForSave addPersistentStoreWithType:NSSQLiteStoreType configuration:nil URL:sourceStoreURL options:localOptions error:nil];

        // Migrate the local store
        id migrationSuccess = [pscForSave migratePersistentStore:sourceStore toURL:storesURL options:ubiquityOptions withType:NSSQLiteStoreType error:&error];

        // Close it and when done tell the delegate you are done migrating
        [newDocument closeWithCompletionHandler:^(BOOL success){

            // Async callback to CloudManager to tell it we are done migrating
            [self.delegate fileMigrated:sourceDocumentURL success:moveSuccess];

        }];

    }];

}
- (void)moveDocumentToLocal
{
    // Create a new UIManagedDocument
    // Now remove the existing store
    // Add the iCloud store
    // Close it and tell the delegate when done

}
- (NSURL*)storeFileURL
{
    // Search for store file by name ‘persistentStore’
}
- (NSURL*)storeFileURL2
{
    // If document is open get the store file URL from the NSPersistentStore itself
}

Code Listings

• AppDelegate Code Listing
• Document Manager Code Listing
• OSManagedDocument Code Listing
• File Browser Code Listing

Related Articles

• Enabling and Updating the User Interface
• Integrating OS X and iOS Apps using Core Data and iCloud
• Integrating UITextView and NSTextView with Core Data and iCloud
• Sample iOS Core Data Library Style App with iCloud Integration

If there is enough demand I will create sample Library and Document based apps and post the XCode projects. Post a message if you are interested.