Resumable Synchronization API

Resume an interrupted synchronization where partial data has been downloaded to the device.

Syntax

To resume a pending synchronization, call:

[DB resumePendingSynchronization]

The application can also determine when to cancel synchronization. For example, you could add logic to the application that sets a max retry resume to cancel the pending synchronization when the application reaches the max setting. The cancel pending synchronization API also unlocks the locked synchronization queue first, but instead of sending a synchronization request, it rolls back any partial data that has already downloaded to the device. To not resume the pending synchronization, call:

[DB cancelPendingSynchronization];

When the system is in a pending synchronization state, waiting for either a resume pending synchronization request by calling resumePendingSynchronization API or a cancellation request by calling cancelPendingSynchronization, the synchronization queue is locked. Any other new blocking or non-blocking synchronization requests are not permitted. Making such a synchronization call raises an exception with the SYNC_QUEUE_FROZEN error code.
If partial data has not downloaded to the device when the interruption occurs, for example, the device is uploading data to the server, or the server is still fetching data from the EIS, the synchronization request terminates immediately and the client reverts to standard behavior. If the interruption is due to:
- Environmental changes – instead of receiving a SUPSynchronizationStatus_INTERRUPTED_WITH_PARTIAL_DATA status, SUPSynchronizationStatus_ERROR and the exception in the sync context is returned.
- Application code disables or cancels the synchronization for any reason – a SUPSynchronizationAction_CANCEL status is returned.
The UltraLite® database runs with default isolation of read committed by default. Therefore, when interruption occurs and the application is in pending synchronization mode, the partially downloaded data is not visible to the application until resume synchronization completes the download.

Examples

Sample code for submitting non-blocking synchronization –

…
…
…
//turn on the resume synchronization option
[[TestCRUDTestCRUDDB getSynchronizationProfile] setResumeSynchronization:YES];
    

MyCallbackHandlerForResumeSync *callback = 
   [MyCallbackHandlerForResumeSync myCallbackHandlerForResumeSync];

[TestCRUDTestCRUDDB registerCallbackHandler:callback];
    
MyResumeSyncStatusListener *listener = [[MyResumeSyncStatusListener alloc] init];
    
SUPObjectList *groups = [SUPObjectList getInstance];
[groups add:[TestCRUDTestCRUDDB getSynchronizationGroup:@"default"]];

//submit a non-blocking sync request
[TestCRUDTestCRUDDB beginSynchronize:groups withContext:nil
   withUploadOnly:NO withSyncStatusListener:listener];
…
…
…

CallbackHandler sample code in receiving SUPSynchronizationStatus_INTERRUPTED_WITH_PARTIAL_DATA status –

 
//in the implementation of SUPDefaultCallbackHandler class
…
…
…
- (SUPSynchronizationActionType)onSynchronize:(SUPObjectList *)
   syncGroupList withContext:(SUPSynchronizationContext *)context
   {
    //sending a NOTE_CALLBACK_ONSYNC_TRIGGERED notification with the synchronization context object
    NSNotification *note = 
      [NSNotification notificationWithName:NOTE_CALLBACK_ONSYNC_TRIGGERED object:context];
      [self performSelectorOnMainThread:@selector(notify:) withObject:note waitUntilDone:NO];

    
    switch (context.status)
    {
       …
       case SUPSynchronizationStatus_INTERRUPTED_WITH_PARTIAL_DATA:
	   self.isInterruptedWithPartialData = YES;

    // By returning continue, the system waits for a request to resume or cancel the pending synchronization.  
    // The synchronization queue is locked and disallows accepting any new incoming synchronization requests.
    // If returning SUPSynchronizationAction _CANCEL instead, the system automatically cancels the pending synchronization.  
    // Application cannot resume the synchronization.  
    // The synchronization queue is not locked and starts to accept new synchronization requests.

	   return SUPSynchronizationAction_CONTINUE;
	   break;
    }

}

Sample code for resuming or canceling synchronization on sync callback status changed notification for the “NOTE_CALLBACK_ONSYNC_TRIGGERED” in previous sample –

…
…
//that’s if the observer is added for “NOTE_CALLBACK_ONSYNC_TRIGGERED”
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(onSyncCallbackStatusChanged:) 
name:NOTE_CALLBACK_ONSYNC_TRIGGERED object:nil];
…
…
…
- (void)onSyncCallbackStatusChanged:(NSNotification *)notification
{
    SUPSynchronizationContext *context = (SUPSynchronizationContext *)notification.object;
    …
    …
    …
    if (context.status == SUPSynchronizationStatus_INTERRUPTED_WITH_PARTIAL_DATA)
    {
    // cancel the pending synchronization when the interrupted status count reaches 
    // the max as the application does not want to keep on trying to resume.  
	// MAX_INTERRUPTED_STATUS number defined by the application code can be set to 
    // a very a large number.

        if (MAX_INTERRUPTED_STATUS == self.interruptedStatusCount)
        {
            [self cancelPendingSync];
            self.label.text = [NSString stringWithFormat:@"Resume sync is canceled.
            \n\tInterrupted status count reached the max: %d.", MAX_INTERRUPTED_STATUS];
        }
        else
        {
            self.isInterruptedWithPartialData = YES;
            self.interruptedStatusCount++;
            //interrupted status received is not due to sync being disable – say by calling [DB disableSync] 
            //in applicationDidEnterBackground.
            if (!self.isSyncDisabled)
            {
                NSDate *beginTime = [NSDate date];
                
                // Provide your own logic in “isDeviceConnectedToInternet“ to use Reachability 
                // API to check network connectivity before resumption attempt
                while(![self isDeviceConnectedToInternet] )
                {
                    NSDate *now = [[NSDate alloc] initWithTimeIntervalSinceNow:0.0];
                    // TIMEOUT defined by the application code to determine when the 
                    // application should stop checking for network connectivity in 
                    // case network connectivity never comes back.
                    if ([now timeIntervalSinceDate:beginTime] >TIMEOUT)
                    {
			           NSLog(@"There is no network connection %d minute(s)", timeout/60]);
                       [now release];
                       break;
                    }
                    [NSThread sleepForTimeInterval:1.0];
                    [now release];
                }
                if ([self isDeviceConnectedToInternet])
                {
                    [self resumeSync];
                }
                else
                {
                    [self cancelPendingSync];
                    self.label.text = @"Resume sync is canceled.\n\tthere's no network connectivity for too long.";
                }
            }
        }
…
…
…
- (void)cancelPendingSync
{    
    NSLog(@"going to cancel pending sync...");
    if (![TestCRUDTestCRUDDB cancelPendingSynchronization])
    {
        NSLog(@”\tfailed to cancel pending syn");
    }
    else
    {
	   NSLog(@"\tpending sync has been cancelled.");
    }
}

- (void)resumeSync
{
    if (!self.isInterruptedWithPartialData)
    {
	   NSLog(@"no resume as there is no interrupted with partiald data");
       return;
    }
    NSLog(@"going to resume sync...");
    
    BOOL resumed = [TestCRUDTestCRUDDB resumePendingSynchronization];
    self.isInterruptedWithPartialData = NO;
    if (!resumed)
    {
	NSLog(@"\tfailed to resume pending syn");
    }
    else
    {
       self.resumeSyncCount++;
       NSLog(@"\tresume sync count: %d", self.resumeSyncCount)];
    }
    
}
…
…
…

Sample code for AppDelegate to disable synchronization and enable synchronization in the background/foreground –

…
…
…
- (void)applicationDidEnterBackground:(UIApplication *)application
{
   NSLog(@"AppDelegate: did eneter background and about to disableSync");
   [TestCRUDTestCRUDDB disableSync];
    
   // Notify the observer that the application disables/interrupts the synchronization.
   // If it receives the SUPSynchronizationStatus_INTERRUPTED_WITH_PARTIAL_DATA status 
   // from callback onSynchronize call later, do not try to resume immediately.
   
   NSNotification *n = [NSNotification notificationWithName:NOTE_SYNC_DISABLED object:nil];
   [self performSelectorOnMainThread:@selector(notify:) withObject:n waitUntilDone:NO];
    
   if([SUPApplication connectionStatus] == SUPConnectionStatus_CONNECTED ||
      [SUPApplication connectionStatus] == SUPConnectionStatus_CONNECTING)
    {
        [SUPApplication stopConnection:0];
    }
}

- (void)applicationWillEnterForeground:(UIApplication *)application
{  
    dispatch_queue_t queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_HIGH, 0);
    dispatch_async(queue, ^
    {
       @try
       {
         // Enable the synchronization. This does not resume the pending synchronization.  
         // Instead it just sets the internal syncEnabled flag to true so that the synchronization 
         // later on process would not be interrupted or canceled.

         [TestCRUDTestCRUDDB enableSync];
         NSNotification *n = [NSNotification notificationWithName:NOTE_SYNC_ENABLED object:nil];
         [self performSelectorOnMainThread:@selector(notify:) withObject:n waitUntilDone:NO];
         [SUPApplication startConnection:30];
       }
       @catch (NSException *ee)
           {
              // log an error or alert user via notification
           }
    }
}
….
….
….

- (void)onSyncDisabled:(NSNotification *)notification
{
    self.isSyncDisabled = YES;
}

- (void)onSyncEnabled:(NSNotification *)notification
{
    self.isSyncDisabled = NO;
    [self resumeSync];    
}