iOS Tutorial - nothirst/TICoreDataSync GitHub Wiki
This tutorial walks through adding the TICoreDataSync framework to a very simple iOS application.
The example app uses Dropbox sync via TICoreDataSync’s built in DropboxSDK-based sync classes. The example app’s user interface is deliberately basic, “designed” to demonstrate the framework with minimal distractions.
This is the iOS equivalent of the Mac app developed in the Mac Tutorial.
The iOSNotebook application stores notes, which can be assigned tags:
The GitHub repository includes a vanilla version of the app (excluding any sync code) in Examples/Tutorial/iOSNotebook. Alternatively, feel free to use your own application.
The finished version is the same as the iOSNotebook example app, which can be found in Examples/iOSNotebook/.
As with the Mac tutorial, the first step is to add the TICoreDataSync-iOS.xcodeproj to the project, along with the Cocoa frameworks you’ll need later.
Right-click on the project, choose Add Files to “iOSNotebook”…, then choose the TICoreDataSync-iOS.xcodeproj project file from the TICoreDataSync directory (at the same level as the Examples directory):
The TICoreDataSync project includes a handful of supporting files that you will need to add directly to your project. Right-click on the project, choose Add Files to “iOSNotebook”…, and add the following files:
- TICoreDataSync/03 Internal Data Model/TICDSSyncChange.xcdatamodel
- TICoreDataSync/03 Internal Data Model/TICDSSyncChangeSet.xcdatamodeld
- TICoreDataSync/05 File Structure/deviceInfo.plist
- TICoreDataSync/05 File Structure/documentInfo.plist
- TICoreDataSync/05 File Structure/ReadMe.txt
To add a framework using Xcode 4, click the iOSNotebook project icon in the Project Navigator (⌘-1), select the iOSNotebook target, then the Summary tab, and click the + button under the Linked Frameworks and Libraries list:
Add the Security.framework, which is needed by the encryption code. Add QuartzCore.framework. Then add libz.dylib which is used by SSZipArchive to compress the whole store. Lastly add libTICoreDataSync-iOS.a.
Prior to building the iOSNotebook target the TICoreDataSync-iOS target needs to be built. Select the iOSNotebook target, then the Build Phases tab. Add TICoreDataSync-iOS under the Target Dependencies section.
The iOSNotebook project needs to know where to look for the TICoreDataSync header files. Select the iOSNotebook target, then the Build Settings tab and scroll down to the Header Search Paths entry. Double click to edit it and add a recursive entry for "$(SRCROOT)/../../..". This path assumes you've left the iOSNotebook project in the Examples/Tutorial directory.
The TICoreDataSync static library declares some categories on different Objective-C classes. To ensure that the iOSNotebook application can see these categories you'll need to add the -ObjC flag to the Other Linker Flags sections of iOSNotebook's Build Settings. Select the iOSNotebook target, then the Build Settings tab and scroll down to the Other Linker Flags entry. Double click to edit it and add an entry for -ObjC.
TICoreDataSync uses the nested managed object context feature that was added to Core Data in 10.7/iOS 5 (Core Data Release Notes for OS X v10.7 and iOS 5.0). As such, your application's main context must be of type NSMainQueueConcurrencyType. Additionally, in order for changes to be recognized, every managed object you wish to synchronize must be an instance of TICDSSynchronizedManagedObject and have a ticdsSyncID attribute.
If you've run iOSNotebook once already at this point it will have created a version of the data store that is incompatible with the changes you will make below. If you run it you'll get an error, The managed object model version used to open the persistent store is incompatible with the one that was used to create the persistent store.
To deal with that you can either blow away the data store created prior to this or add another version of the store:
- Add model version ("Notebook 2")
- Set Notebook 2 as the current model version
- Add the
ticdsSyncIDattribute to both entities in Notebook 2 following the sections below. - Change the code that initializes the persistent store coordinator to:
...
NSDictionary *options = [NSDictionary dictionaryWithObjectsAndKeys:
[NSNumber numberWithBool:YES], NSMigratePersistentStoresAutomaticallyOption,
[NSNumber numberWithBool:YES], NSInferMappingModelAutomaticallyOption, nil];
__persistentStoreCoordinator = [[NSPersistentStoreCoordinator alloc] initWithManagedObjectModel:mom];
if (![__persistentStoreCoordinator addPersistentStoreWithType:NSSQLiteStoreType configuration:nil URL:url options:options error:&error]) {
[[NSApplication sharedApplication] presentError:error];
[__persistentStoreCoordinator release], __persistentStoreCoordinator = nil;
return nil;
}Open the iOSNotebookAppDelegate.m and scroll down to the managedObjectContext method declaration. Modify the __managedObjectContext initialization like so:
...
__managedObjectContext = [[NSManagedObjectContext alloc] initWithConcurrencyType:NSMainQueueConcurrencyType];
[__managedObjectContext setPersistentStoreCoordinator:coordinator];
return __managedObjectContext;
}Open Notebook.xcdatamodeld and select the Note entity. Add a new String attribute called ticdsSyncID, and mark it as indexed:
Do the same for the Tag entity.
Both the Note and Tag entities are set to use custom subclasses rather than be plain NSManagedObjects.
Open the TINBNote.h file and change the @interface to inherit from TICDSSynchronizedManagedObject. You’ll need to import the TICoreDataSync.h file:
#import "TICoreDataSync.h"
@class TINBNote;
@interface TINBNote : TICDSSynchronizedManagedObject {
...Do the same for the TINBTag class description.
#import "TICoreDataSync.h"
@class TINBNote;
@interface TINBTag : TICDSSynchronizedManagedObject {Before you can do anything else with TICoreDataSync, your application will need to register an instance of an application sync manager. For this iOS tutorial, you’ll be using the DropboxSDK-based sync classes, which means that before you can register a sync manager, you’ll need to add support into the project for the DropboxSDK.
The DropboxSDK allows access to your Dropbox files via a rest client. The TICoreDataSync classes expect you to have set up a DBSession before calling any sync manager methods, so you’ll need to add code to the iOSNotebookAppDelegate.m file to configure a session, check if it has the necessary credentials, and if not, display the login navigator provided by the DropboxSDK.
Import the DropboxSDK.h file at the top of iOSNotebookAppDelegate.m, and modify the class extension declaration at the top of the file to indicate that it adopts the DBSessionDelegate protocol:
#import "DropboxSDK.h"
@interface iOSNotebookAppDelegate () <DBSessionDelegate>
@endYou’ll need your own Dropbox key and secret specific to your application before you can make connections with the DropboxSDK.
For the purposes of this tutorial, you’ll need to register a “Development” application via https://www.dropbox.com/developers/apps. Once you have your secret and key for the app, add the following #defines at the top of iOSNotebookAppDelegate.m:
#define kTICDDropboxSyncKey @"yourKey"
#define kTICDDropboxSyncSecret @"yourSecret"Find the application:didFinishLaunchingWithOptions: method. You’ll need to start by creating a DBSession, and setting it as the default session:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
...
DBSession *session = [[DBSession alloc] initWithAppKey:kTICDDropboxSyncKey appSecret:kTICDDropboxSyncSecret root:kDBRootDropbox];
session.delegate = self;
[DBSession setSharedSession:session];
[session release];
The DropboxSDK stores the login information once the user has logged in successfully. A DBSession object will respond YES to isLinked if it has the necessary credentials; if so, you’ll be able to continue by registering an Application Sync Manager. If this is the first time the user has launched the app, you’ll need to request a login:
...
if ([[DBSession sharedSession] isLinked]) {
[self registerSyncManager];
} else {
[[DBSession sharedSession] linkFromController:self.navigationController];
}
return YES;
}You’ll write the registerSyncManager method in the next main section.
The DropboxSDK delegate methods you need to implement will be called when the user logs in, cancels logging in, or if there is an authorization failure (because the stored Dropbox credentials are incorrect).
Start by implementing the DBSessionDelegate authorization challenge method to display the DropboxSDK login controller:
#pragma mark - DBSessionDelegate methods
- (void)sessionDidReceiveAuthorizationFailure:(DBSession *)session userId:(NSString *)userId
{
[[DBSession sharedSession] linkFromController:self.navigationController];
}
When the user enters their credentials and logs in successfully the DropboxSDK (or the Dropbox app if installed) will launch your app with the URL scheme db-yourKey. As such you will need to register for this URL scheme in the iOSNotebook-Info.plist file. Right-click on the iOSNotebook-Info.plist file in the Project Navigator and choose Open As > Source Code and add the following key above the tag:
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLSchemes</key>
<array>
<string>db-yourKey</string>
</array>
</dict>
</array>Implement the application:handleOpenURL: method thusly:
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url
{
if ([[DBSession sharedSession] handleOpenURL:url]) {
if ([[DBSession sharedSession] isLinked]) {
NSLog(@"App linked successfully!");
[self registerSyncManager];
}
return YES;
}
return NO;
}That’s it for the DropboxSDK implementation; next you’ll need to deal with the Application Sync Manager.
The TICDSApplicationSyncManager is responsible for creating the initial remote file hierarchy for your application, if necessary, as well as the hierarchy specific to each registered client device. Its delegate callbacks allow you to configure how synchronization works, including specifying whether to use encryption.
You’ll need to implement the registerSyncManager method you referenced above, as well as a few required delegate callbacks:
Change the @interface in iOSNotebookAppDelegate.h to indicate that the class adopts the TICDSApplicationSyncManagerDelegate protocol. You’ll need to import the TICoreDataSync.h file:
#import "TICoreDataSync.h"
@interface iOSNotebookAppDelegate () <..., TICDSApplicationSyncManagerDelegate>
@endThe protocol includes a few required methods, which you’ll implement later.
Request the defaultApplicationSyncManager via the correct sync manager type. For the DropboxSDK under iOS, this is the DropboxSDK-Based manager.
Start by implementing the registerSyncManager method like this:
#pragma mark - Local methods
- (void)registerSyncManager
{
TICDSDropboxSDKBasedApplicationSyncManager *manager = [TICDSDropboxSDKBasedApplicationSyncManager defaultApplicationSyncManager];Get the unique sync identifier for this client, and generate one if it doesn’t already exist:
NSString *clientUuid = [[NSUserDefaults standardUserDefaults] stringForKey:@"iOSNotebookAppSyncClientUUID"];
if (clientUuid == nil) {
clientUuid = [TICDSUtilities uuidString];
[[NSUserDefaults standardUserDefaults] setValue:clientUuid forKey:@"iOSNotebookAppSyncClientUUID"];
}Use the UIDevice class to find out the name of the current device running the application. This will be used as the device description (human readable information to help a user distinguish between multiple registered devices):
NSString *deviceDescription = [[UIDevice currentDevice] name];If, for some reason, you need to use a specific DBSession for sync other than the defaultSession, you would need to specify it as the manager’s dbSession property here. By default, the sync managers will use the defaultSession, which is fine for this tutorial.
Finally, register the sync manager and provide the information:
[manager registerWithDelegate:self
globalAppIdentifier:@"com.yourcompany.notebook"
uniqueClientIdentifier:clientUuid
description:deviceDescription
userInfo:nil];
}Note that the globalAppIdentifier parameter must be the same for every client, whether iOS or Mac.
The TICDSApplicationSyncManagerDelegate protocol includes three required methods; if you don’t implement these, you’ll get compiler warnings when you build the project. The first required method will be called the very first time the app is registered by any client, to determine whether to use encryption. Once this delegate method is called, the application registration process is paused so you can present UI to ask the user. If you’ve already followed the Mac version of this tutorial and have enabled encryption, you’ll need to specify the password here. Otherwise, continue registration without using encryption:
#pragma mark - TICDSApplicationSyncManagerDelegate methods
- (void)applicationSyncManagerDidPauseRegistrationToAskWhetherToUseEncryptionForFirstTimeRegistration:(TICDSApplicationSyncManager *)aSyncManager
{
[aSyncManager continueRegisteringWithEncryptionPassword:nil];
}- (void)applicationSyncManagerDidPauseRegistrationToRequestPasswordForEncryptedApplicationSyncData:(TICDSApplicationSyncManager *)aSyncManager
{
[aSyncManager continueRegisteringWithEncryptionPassword:nil];
}The third required method will be called when an existing, previously synchronized document is downloaded to a client. In a document-based application, you’d use this method to return a configured Document Sync Manager for that downloaded document, but since this is a non-document-based app, just return nil as this method won’t be called:
- (TICDSDocumentSyncManager *)applicationSyncManager:(TICDSApplicationSyncManager *)aSyncManager preConfiguredDocumentSyncManagerForDownloadedDocumentWithIdentifier:(NSString *)anIdentifier atURL:(NSURL *)aFileURL
{
return nil;
}Look at the ShoppingList example application to see how this method should be implemented in a document-based app. (Editor's note: This example app no longer exists but I need to resurrect it. It's in the git history.)
Once the application sync manager is registered, you’ll need to configure and register the document sync manager, responsible for synchronizing the application’s data.
The TICDSDocumentSyncManager is responsible for creating the remote hierarchy specific to a document, downloading and uploading the entire store, performing a sync, and cleaning up unneeded files.
In a document-based application, you have one document sync manager per document. Although the iOSNotebook application is a non-document-based application, you’ll need to think of it as being a document-based application that only ever has one document.
Typically, a document-based application would keep track of a unique document synchronization identifier for each document; the Shopping List application, for example, saves this identifier in the metadata of a document’s persistent store.
For a non-document-based application, this identifier can be hard-wired into the application. When the application sync manager has completed its registration, the document sync manager can fire up its registration.
Start by changing the @interface in iOSNotebookAppDelegate.h by adding yet another delegate protocol, TICDSDocumentSyncManagerDelegate:
@interface iOSNotebookAppDelegate : NSObject <... , TICDSDocumentSyncManagerDelegate> {
...Add a property declaration to the app delegate to keep track of the document sync manager:
@interface iOSNotebookAppDelegate : NSObject <...> {
...
}
...
@property (retain) TICDSDocumentSyncManager *documentSyncManager;
@endYou need to keep a reference to the document sync manager so that you can initiate future tasks like synchronization.
Implement applicationSyncManagerDidFinishRegistering: to mark our managedObjectContext as synchronized and to trigger the creation of the document sync manager when the application sync manager has registered:
- (void)applicationSyncManagerDidFinishRegistering:(TICDSApplicationSyncManager *)aSyncManager
{
self.managedObjectContext.synchronized = YES;
TICDSDropboxSDKBasedDocumentSyncManager *docSyncManager = [[TICDSDropboxSDKBasedDocumentSyncManager alloc] init];Again, if you need to use a different DBSession from the defaultSession, you should specify the docSyncManager’s dbSession here; the default behavior is fine for this tutorial, as before.
Register it, using a hard-wired document identifier:
[docSyncManager registerWithDelegate:self
appSyncManager:aSyncManager
managedObjectContext:[self managedObjectContext]
documentIdentifier:@"Notebook"
description:@"Application's data"
userInfo:nil];Finally, set the property (which will retain it) and release it to balance the alloc] init]:
[self setDocumentSyncManager:docSyncManager];
[docSyncManager release];
}There are four required document sync manager delegate methods. One is called if a conflict is found during the synchronization process. In a shipping app, you would probably want to ask the user how to proceed, but for this tutorial, just implement the method to continue synchronizing with the local change taking precedent:
#pragma mark - TICDSDocumentSyncManagerDelegate methods
- (void)documentSyncManager:(TICDSDocumentSyncManager *)aSyncManager didPauseSynchronizationAwaitingResolutionOfSyncConflict:(id)aConflict
{
[aSyncManager continueSynchronizationByResolvingConflictWithResolutionType:TICDSSyncConflictResolutionTypeLocalWins];
}Another is called to find out the location on disk of the store file to be uploaded:
- (NSURL *)documentSyncManager:(TICDSDocumentSyncManager *)aSyncManager URLForWholeStoreToUploadForDocumentWithIdentifier:(NSString *)anIdentifier description:(NSString *)aDescription userInfo:(NSDictionary *)userInfo
{
return [[self applicationFilesDirectory] URLByAppendingPathComponent:@"Notebook.storedata"];
}The delegate will be notified if syncing fails. For now just log the error:
- (void)documentSyncManager:(TICDSDocumentSyncManager *)aSyncManager didFailToSynchronizeWithError:(NSError *)anError
{
NSLog(@"%s %@", __PRETTY_FUNCTION__, anError);
}The final required delegate methods are called if the remote file structure doesn’t exist for the document at the time of registration, or if the document has previously been deleted. In a shipping application, you might want to ask the user what to do, at least if the document was deleted. For now, just implement both to tell the document sync manager to continue registration:
- (void)documentSyncManager:(TICDSDocumentSyncManager *)aSyncManager didPauseRegistrationAsRemoteFileStructureDoesNotExistForDocumentWithIdentifier:(NSString *)anIdentifier description:(NSString *)aDescription userInfo:(NSDictionary *)userInfo
{
[aSyncManager continueRegistrationByCreatingRemoteFileStructure:YES];
}
- (void)documentSyncManager:(TICDSDocumentSyncManager *)aSyncManager didPauseRegistrationAsRemoteFileStructureWasDeletedForDocumentWithIdentifier:(NSString *)anIdentifier description:(NSString *)aDescription userInfo:(NSDictionary *)userInfo
{
[aSyncManager continueRegistrationByCreatingRemoteFileStructure:YES];
}Don’t run the app yet, as you need to determine what happens the first time a client tries to register.
When a client registers, it should check whether it has existing data of its own. If not, it needs to download the most recent store that’s been uploaded by other registered clients, assuming such a store exists.
Start by adding a BOOL instance variable and property:
@interface iOSNotebookAppDelegate : NSObject <...> {
...
}
...
@property (nonatomic, assign, getter = shouldDownloadStoreAfterRegistering) BOOL downloadStoreAfterRegistering;
@endYou’ll need to add a check for existing data before the Core Data stack is set up. The easiest place to do this is just before the persistent store coordinator is created:
- (NSPersistentStoreCoordinator *) persistentStoreCoordinator
{
...
NSURL *storeURL = [[self applicationDocumentsDirectory] URLByAppendingPathComponent:@"Notebook.sqlite"];
/* Add the check for an existing store here... */
if ([[NSFileManager defaultManager] fileExistsAtPath:storeURL.path] == NO) {
self.downloadStoreAfterRegistering = YES;
}
NSError *error = nil;
__persistentStoreCoordinator = [[NSPersistentStoreCoordinator alloc] initWithManagedObjectModel:[self managedObjectModel]];
...
}If the store needs to be downloaded, this should be done just after the document sync manager finishes registering. If the store does not need to be downloaded then just kick off a synchronization.
- (void)documentSyncManagerDidFinishRegistering:(TICDSDocumentSyncManager *)aSyncManager
{
if (self.shouldDownloadStoreAfterRegistering) {
[aSyncManager initiateDownloadOfWholeStore];
} else {
[aSyncManager initiateSynchronization];
}
}If this is the very first time the app has been registered by any device, you won’t be able to download the store because no previous stores will exist.
As you saw earlier, one of the required delegate methods will be called by the document sync manager to find out what to do if no remote file structure exists for a document, or if the document has been deleted. Change your implementation of these methods to prevent the store download:
- (void)documentSyncManager:(TICDSDocumentSyncManager *)aSyncManager didPauseRegistrationAsRemoteFileStructureDoesNotExistForDocumentWithIdentifier:(NSString *)anIdentifier description:(NSString *)aDescription userInfo:(NSDictionary *)userInfo
{
self.downloadStoreAfterRegistering = NO;
[aSyncManager continueRegistrationByCreatingRemoteFileStructure:YES];
}
- (void)documentSyncManager:(TICDSDocumentSyncManager *)aSyncManager didPauseRegistrationAsRemoteFileStructureWasDeletedForDocumentWithIdentifier:(NSString *)anIdentifier description:(NSString *)aDescription userInfo:(NSDictionary *)userInfo
{
self.downloadStoreAfterRegistering = NO;
[aSyncManager continueRegistrationByCreatingRemoteFileStructure:YES];
}If another client has previously deleted this client from synchronizing with the document, the underlying helper files will automatically be removed, but you will need to initiate a store download to override the whole store document file you have locally (as it will be out of date compared to the available sets of sync changes).
In a shipping application, you may want to copy the old store elsewhere in case the user wishes to restore it. For now, just implement the client deletion delegate warning method to indicate that the store should be downloaded.
Note that the registration process cannot be stopped at this point, so you do not need to call any continueRegistration method:
- (void)documentSyncManagerDidDetermineThatClientHadPreviouslyBeenDeletedFromSynchronizingWithDocument:(TICDSDocumentSyncManager *)aSyncManager
{
self.downloadStoreAfterRegistering = YES;
}In order for other clients to be able to download the whole store, one client will obviously need to upload a copy of the store at some point.
The document sync manager will ask whether to upload the store during document registration. Implement this method to return YES, but only if this isn’t the first time this client has been registered:
- (BOOL)documentSyncManagerShouldUploadWholeStoreAfterDocumentRegistration:(TICDSDocumentSyncManager *)aSyncManager
{
return self.shouldDownloadStoreAfterRegistering == NO;
}In a shipping iOS application, you might wish to ask the user whether they want to upload the store every time they run the app. If the user is synchronizing with a Mac client, they may prefer that only the Mac client uploads the store to save iOS bandwidth and time. But, if they are synchronizing iOS to iOS without any Mac clients, one of those iOS clients will need to upload the store every so often.
If the store file is downloaded, it will replace any file that has been created on disk. You’ll need to implement two delegate methods to make sure the persistent store coordinator can cope with the file being removed.
First, implement the method called just before the store is replaced:
- (void)documentSyncManager:(TICDSDocumentSyncManager *)aSyncManager willReplaceStoreWithDownloadedStoreAtURL:(NSURL *)aStoreURL
{
NSError *anyError = nil;
BOOL success = [self.persistentStoreCoordinator removePersistentStore:[self.persistentStoreCoordinator persistentStoreForURL:aStoreURL] error:&anyError];
if (success == NO) {
NSLog(@"Failed to remove persistent store at %@: %@", aStoreURL, anyError);
}
}Second, the method called just after the store is replaced:
- (void)documentSyncManager:(TICDSDocumentSyncManager *)aSyncManager didReplaceStoreWithDownloadedStoreAtURL:(NSURL *)aStoreURL
{
NSError *anyError = nil;
id store = [self.persistentStoreCoordinator addPersistentStoreWithType:NSSQLiteStoreType configuration:nil URL:aStoreURL options:nil error:&anyError];
if (store == nil) {
NSLog(@"Failed to add persistent store at %@: %@", aStoreURL, anyError);
}
}The Mac version of this tutorial uses bindings to keep the interface updated when the underlying data is changed. In this iOS application, you’ll need to make changes to each of the primary view controllers to adjust the interface items.
The RootViewController displays a standard table view of notes, and uses a fetched results controller. When the persistent stores change, the FRC will need to perform a new fetch to update the table view.
Start by registering to receive notifications when the persistent store changes at the end of the viewDidLoad method in RootViewController.m:
- (void)viewDidLoad
{
[super viewDidLoad];
...
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(persistentStoresDidChange:) name:NSPersistentStoreCoordinatorStoresDidChangeNotification object:self.managedObjectContext.persistentStoreCoordinator];
}Unregister for this notification in viewDidUnload:
- (void)viewDidUnload
{
[[NSNotificationCenter defaultCenter] removeObserver:self name:NSPersistentStoreCoordinatorStoresDidChangeNotification object:self.managedObjectContext.persistentStoreCoordinator];
[super viewDidUnload];
}Implement the persistentStoresDidChange: method like this:
#pragma mark - NSPersistentStoreCoordinatorStoresDidChangeNotification method
- (void)persistentStoresDidChange:(NSNotification *)aNotification
{
NSError *anyError = nil;
BOOL success = [self.fetchedResultsController performFetch:&anyError];
if (success == NO) {
NSLog(@"Error fetching: %@", anyError);
}
[self.tableView reloadData];
}The NoteTagsViewController also displays a standard table view, but shows the list of available tags, with checkmarks against those applied to a note. It also uses a fetched results controller.
Make the same implementation changes as you did above for the RootViewController.
You’ll need to access the managedObjectContext via:
[[self note] managedObjectContext]
The NoteViewController displays a selected note, including its title, content and tags. Different controls are displayed depending on whether or not the user is editing a note.
Add similar methods to register for a notification when the persistent stores change:
- (void)viewDidLoad
{
[super viewDidLoad];
...
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(persistentStoresDidChange:) name:NSPersistentStoreCoordinatorStoresDidChangeNotification object:self.note.managedObjectContext.persistentStoreCoordinator];
}And unregister:
- (void)viewDidUnload
{
[[NSNotificationCenter defaultCenter] removeObserver:self name:NSPersistentStoreCoordinatorStoresDidChangeNotification object:self.note.managedObjectContext.persistentStoreCoordinator];
[super viewDidUnload];
}Each of the controls needs to be updated, but only if the user is not currently editing it:
#pragma mark - NSPersistentStoreCoordinatorStoresDidChangeNotification method
- (void)persistentStoresDidChange:(NSNotification *)aNotification
{
[self.note.managedObjectContext refreshObject:self.note mergeChanges:YES];
if (self.editingTextView.isFirstResponder == NO) {
self.editingTextView.text = self.note.content;
}
if ( self.titleTextField.isFirstResponder == NO) {
self.titleTextField.text = self.note.title;
}
[self updateTags];
}
TICoreDataSync can be extremely verbose when it comes to logging. Thankfully we've also provided logging levels so you can tune how much logging you wish to see from the framework. Set the log verbosity to TICDSLogVerbosityEveryStep so you can bask in the glory of the wall of text that TICDS will crit you with the next time it runs. Do this in the iOSNotebookAppDelegate's +initialize method:
+ (void)initialize
{
[TICDSLog setVerbosity:TICDSLogVerbosityEveryStep];
}At this point, you’re ready to run the application to test store upload and download behavior, if you wish.
The first time you run the app on any device, you’ll find a directory is created at the root of your Dropbox, called com.yourcompany.notebook. This contains all the remote files used by TICoreDataSync to synchronize clients’ data. The file structure is described further in the Remote File Hierarchy document.
What’s missing at this point, however, is the main reason for using TICoreDataSync—the ability to synchronize changes made after the initial store upload/download.
The first thing to add is a suitable UI element to initiate synchronization.
Open iOSNotebookAppDelegate.h and add the signature for an IBAction method:
@interface iOSNotebookAppDelegate : NSObject <...> {
...
}
...
- (IBAction)beginSynchronizing:(id)sender;
@endImplement the method in iOSNotebookAppDelegate.m, like this:
- (IBAction)beginSynchronizing:(id)sender
{
// Save the managed object context to cause sync change objects to be written
NSError *saveError = nil;
[self.managedObjectContext save:&saveError];
if (saveError != nil) {
NSLog(@"%s %@", __PRETTY_FUNCTION__, saveError);
}
[self.documentSyncManager initiateSynchronization];
}The easiest place to add a synchronize button is in the navigation bar of the root view controller.
Open RootViewController.m, and set the left button to be a refresh button, set to target the beginSynchronizing: method on the app delegate:
- (void)viewDidLoad
{
...
UIBarButtonItem *syncButton = [[UIBarButtonItem alloc] initWithBarButtonSystemItem:UIBarButtonSystemItemRefresh target:[[UIApplication sharedApplication] delegate] action:@selector(beginSynchronizing:)];
self.navigationItem.leftBarButtonItem = syncButton;
[syncButton release];
...
}When TICoreDataSync applies changes made by other clients, it does so in a background managed object context that is a child of the primary context (the one you supplied when you registered the document sync manager).
You’ll need to implement another delegate method in iOSNotebookAppDelegate.m to alert you when changes are made and saved from the background context, so that you can save your main context. This step isn't necessary but it does work around an existing known issue.
- (void)documentSyncManager:(TICDSDocumentSyncManager *)aSyncManager didMakeChangesToObjectsInBackgroundContextAndSaveWithNotification:(NSNotification *)aNotification
{
NSError *saveError = nil;
[self.managedObjectContext save:&saveError];
if (saveError != nil) {
NSLog(@"%s %@", __PRETTY_FUNCTION__, saveError);
}
}Build and run the application, add some notes and tags, then tap the sync button. When you sync iOSNotebook it initiates a save and TICoreDataSync jumps into action to create Sync Change objects to describe what’s been changed. These are stored in a separate, private managed object context.
During synchronization, any changes made by other clients are pulled down first. Any conflicts are fixed with the local, unpushed sync changes, then the local changes are pushed to the remote.
If you built the Mac tutorial, or test the iOS app on one or more devices as well as the simulator, make sure each client pulls down the changes correctly.
There are two other features you can implement to make synchronization appear more seamless.
Firstly, TICoreDataSync will ask whether it should initiate a synchronization whenever it detects that the primary context has been saved. If you respond with YES, synchronization will occur every time the user saves their data.
Secondly, the Document Sync Manager offers the ability to detect when other clients have pushed sync changes, at which point it will initiate a synchronization. In a sync environment of multiple devices this means that when one client saves, the changes will be pulled down by all the other synchronized clients in very short fashion.
Implement this document sync manager delegate method to return YES:
- (BOOL)documentSyncManager:(TICDSDocumentSyncManager *)aSyncManager shouldBeginSynchronizingAfterManagedObjectContextDidSave:(NSManagedObjectContext *)aMoc;
{
return YES;
}You’ll need to turn on remote change polling immediately after the document sync manager has finished registering, so add the following into the relevant delegate method:
- (void)documentSyncManagerDidFinishRegistering:(TICDSDocumentSyncManager *)aSyncManager
{
...
[aSyncManager beginPollingRemoteStorageForChanges];
}If your app is using the Dropbox API (as this iOS example app is) you'll notice that it takes longer for it to detect changes made by other clients. This is because the Dropbox folder is only polled once per minute for the DropboxSDK-based classes whereas the File Manager-based classes use a directory watcher implementation.
Test the application once more, if possible on multiple devices, to check that these features work as expected.
Any changes made by any other client will automagically be propagated to other on synchronized clients.
It would be nice if the interface could display an animated progress indicator whenever synchronization tasks were taking place.
TICoreDataSync offers two ways to implement progress indication. For task-specific progress, you could implement every didBegin, didFinish, and didFailTo delegate method, and display suitable progress updates. Alternatively, both application and document sync managers post notifications when they start and end a task.
Let’s take the easy approach, and use these notifications.
You’ll need to register for four notifications—two posted by the application sync manager, two by the document sync manager. These are intended to be used as indications when activity increases and decreases.
For the iOSNotebook app, it seems best to indicate both application and document activity by using the status bar activity indicator.
Start by adding an NSInteger property to keep track of the activity count:
@interface iOSNotebookAppDelegate : NSObject <...>
...
@property (nonatomic, assign) NSInteger activity;
@endThe status bar activity indicator needs to be hidden/shown according to the activity count.
Register for the application and document sync manager notifications just after the application finishes launching. In a shipping application you would want to register for notifications from the actual sync managers (especially in a document-based environment), but in this case we're just passing nil to the object: argument.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(activityDidIncrease:) name:TICDSApplicationSyncManagerDidIncreaseActivityNotification object:nil];
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(activityDidDecrease:) name:TICDSApplicationSyncManagerDidDecreaseActivityNotification object:nil];
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(activityDidIncrease:) name:TICDSDocumentSyncManagerDidIncreaseActivityNotification object:nil];
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(activityDidDecrease:) name:TICDSDocumentSyncManagerDidDecreaseActivityNotification object:nil];
...Add the following methods that will be called when notifications are posted:
#pragma mark - Sync Manager Activity Notification methods
- (void)activityDidIncrease:(NSNotification *)aNotification
{
self.activity++;
if (self.activity > 0) {
[[UIApplication sharedApplication] setNetworkActivityIndicatorVisible:YES];
}
}
- (void)activityDidDecrease:(NSNotification *)aNotification
{
if (self.activity > 0) {
self.activity--;
}
if (self.activity < 1) {
[[UIApplication sharedApplication] setNetworkActivityIndicatorVisible:NO];
}
}Test the application once again. The activity indicator should appear whenever activity is occurring.
TICoreDataSync can encrypt all important synchronization data before it is transferred to the remote. For the iOSNotebook application, this means that all synchronization files will be encrypted before they are uploaded to Dropbox by the REST client.
If you’ve previously followed the Mac tutorial, and enabled encryption, you can skip this section.
Encryption can only be enabled the first time any client registers to synchronize an application’s data. This means you’ll need to remove any existing remote sync data before continuing, either manually, or by asking the application sync manager to remove all data (not yet implemented in the framework).
If you’ve already launched the application and tested it by synchronizing data, you’ll need to quit the Notebook/iOSNotebook application on all clients, then delete the entire directory at ~/Dropbox/com.yourcompany.notebook from a desktop Mac, or via the Dropbox web interface.
You only need to modify two delegate methods to inform TICoreDataSync that it should encrypt all important data. The first method is called the first time any client registers to synchronize data for an application:
- (void)applicationSyncManagerDidPauseRegistrationToAskWhetherToUseEncryptionForFirstTimeRegistration:(TICDSApplicationSyncManager *)aSyncManager
{The existing implementation of this method continues registration by passing nil as the password, meaning that the data won’t be encrypted. In a shipping application, you’d obviously want to display suitable UI to ask the user whether they want their data encrypted, and if so what password to use, but for this tutorial, just hard-wire a password. Change the implementation of this method to specify a password:
[aSyncManager continueRegisteringWithEncryptionPassword:@"password"];
}The above method takes care of the first time an application is registered. For additional clients registering against existing data, the framework will detect if encryption is enabled, and request a password if necessary. Again, in a shipping application you’d need to display suitable UI to ask the user for the password (if they supply an incorrect password, this method will be called repeatedly), but for this tutorial, just hard-wire the same password. Change the implementation of the other encryption method to specify the password:
- (void)applicationSyncManagerDidPauseRegistrationToRequestPasswordForEncryptedApplicationSyncData:(TICDSApplicationSyncManager *)aSyncManager
{
[aSyncManager continueRegisteringWithEncryptionPassword:@"password"];
}Once again, test that the application behaves as expected. Nothing will appear to have changed from the user experience point of view, but if you try to open any of the files on the remote (i.e., in ~/Dropbox/com.yourcompany.notebook from a desktop Mac) such as a deviceInfo.plist file, you’ll find the content appears garbled and unreadable in a text editor.