Introduction   |  Smart Sync Tutorial  |  Smart Sync Admin Tools  |  Smart Sync Development Tools

 

In - Out-bound Delta Data Handling

Introduction

SmartSync handles the in- out-bound delta data transmission with the backend. This process is transparent to the application. The SmartSync API provides methods that allow the application to access and specify the processing type for the in- out-bound delta data.

General Process

General description

A synchronization process is started by application triggers from an application or MEHome with the synchronizeWithBackend method in package com.sap.ip.me.api.sync.SyncManager. A synchronization process cycle has two steps in the order:

  1. Outbound data processing.
  2. Inbound data processing.

The outbound data is generated on the client, and uploaded to the backend. Outbound data includes SyncBoOutDeltaData and SyncBoRequest. A SyncBoOutDeltaData is used to apply changed SyncBo data of the client to the backend. SmartSync generates and manages the delta data for every change to a SyncBo on the client. A SyncBoRequest is a request message going to the backend, which includes a download request and reset request.

The inbound data is generated on the backend and downloaded to the client. Inbound data includes SyncBoInDeltaData and MessageReply. A SyncBoInDeltaData is used to apply changed SyncBo data from backend to the client. The SyncBoInDeltaData may be either delta data changed by a SyncBo either by the backend / other devices or a response to previous uploaded client SyncBoOutDeltaData. Between backend and client, also inside the SmartSync-layer, SmartSync uses MessageReply to inform the application about the synchronization status, including errors.

In any case, SmartSync guarantees that there is no in- out-bound data lost during synchronization. SmartSync guarantees every inbound data to be handled in-order and without duplication. SmartSync guarantees that all SyncBoOutDeltaData are handled according to their dependency, for example, the sequence of SyncBo structures, which have been constructed in the Meta-XML file. SmartSync guarantees that the data on the client and the backend is consistent. SmartSync informs client applications to reset its data store to keep the consistency between client data and the backend data.

Synchronization

SmartSync uses the Mobile Infrastructure (MI)-Synclayer for the synchronization. SmartSync constructs an outbound data inside an outbound sync-container and passes it to the MI-Synclayer. Vice versa, SmartSync extracts an inbound data from an inbound sync-container, which is comes from the MI-Synclayer.

The MI-Synclayer guarantees that the sync-container handed "in the right order" and without duplication.
The MI-Synclayer keeps a sync-container until SmartSync has processed it completely. This is a transaction process.

SmartSync persists SyncBoOutDeltaData using the MI persistence layer. It is not required that SyncBoRequest, SyncBoInDeltaData, and MessageReply are persistent. In some cases however the application has to persist the SyncBo data, which corresponds to a SyncBoInDeltaData.

Process Description

When application triggers the synchronization, either by calling com.sap.ip.me.api.sync.SyncManager.synchronizeWithBackend( ) or by clicking on to the Sync button on MEHome, SmartSync conducts the following sequence steps to process the synchronization.

When the inbound data is SyncBoInDeltaData, the following information can be retrieved from the SyncBoInDelta.

SyncBoRequest

A SyncBoRequest is a request message used to retrieve delta data from the backend. The client has to send SyncBoRequest in order to get the delta data from the backend.

As default, SmartSync sends the SyncBoRequests for all SyncBo descriptors.

Applications can access/ modify the SyncBoRequest using the SmartSync API. The API allows applications to:

Necessary APIs are:

Example: Disable a SyncBo request being sent to backend.

SmartSyncRuntime.getSyncBoDeltaRequestFacade( VisibilityType. USER_SHARED ).getSyncBoDeltaRequest(syncBoDescriptor).
                 setProcessing(SyncBoDeltaRequestType.NO_REQUEST)
SmartSync resets the SyncBoDeltaRequest value back to default value after synchronization with the backend.

 

SyncReply Handling

SyncReply is constructed inside a SyncBoInDeltaData instance and contains the backend handling status information for the previous uploaded SyncBoOutDeltaData.

A SyncBoInDeltaData must not necessarily contain a SyncReply. For example, the initial data does not have a SyncReply. However, it must have a SyncReply when the SyncBoInDeltaData is a response message to a previous uploaded SyncBoOutDeltaData.

SyncReply contains information on the status of the initiated modification by the client. If the modification was not successful, the SyncBoInDeltaData with the SyncReply instance is related to the orginal SyncBo and contains rollback information that reverts the initial client change.

Cases regarding SyncReply and their usage:


MessageReply Handling

MessageReply is used to describe the communication status. Backend and client can send a MessageReply message. Cases for MessageReply and their usage:


InboxNotifer & SyncBoOutDeltaNotifier

General Description

SmartSync uses the Notifier/Observer design pattern for applications to access the in-/ out- box.

By using the InboxNotifier, with SyncBoInDeltaObserver and MessageReplyObserver interfaces, applications can:

By using the SyncBoOutDeltaNotifier, with SyncBoOutDeltaObserver interface, applications can:

SyncBoInDeltaObserver, MessageReplyObserver, and SyncBoOutDeltaObserver are interfaces. SmartSync does not provide any abstract class or concrete class for these interfaces. Applications need to implement them, and register to the corresponding Notifier.

During the synchronization, SmartSync calls SyncBoOutDeltaObserver when SmartSync finds a SyncBoOutDeltaData, and has created a sync-container of it. SmartSync calls the SyncBoInDeltaObserver when a SyncBoInDeltaData comes in, and posts the SyncBoInDeltaData to be stored on the client before. SmartSync calls the MessageReplyObserver when a MessageReply has been sent.

This interface has to be implemented for any class observing the SyncBO inbound delta. It has to specify for which SyncBO inbound delta it is notified, by specifying the SyncBO types it is obeserving. When receiving SyncBO inbound delta data for one of the specified SyncBO types, method syncBoInDeltaReceived is called. This observer is called before modification takes place. It is only used for SyncBo delta from the backend, not the client.


API Usage

For details about the API please refer to the SmartSync API JavaDoc.

Necessary APIs are:

Example: Methods for retrieving InboxNotifier and SyncBoOutDeltaNotifier

  SmartSyncRuntime.getInboxNotifier()
  SmartSyncRuntime.getSyncBoOutDeltaNotifier()

  SyncBoOutDeltaNotifier.registerSyncBoOutDeltaObserver(myOutDeltaObserver)

Example: Implementing an application SyncBoOutDeltaObserver.

Click here to view the coding

 

 

Synchronous Synchronization

General Description

The default synchronization is an asynchronous process. SmartSync gives control to the application to set the synchronization to a synchronous synchronization. With a synchronous synchronization the client application gets response within one synchronization cycle.

On the backend SmartSync keeps a work-list (queue) for each device. On the backend SmartSync handles the incoming messages of the work-list sequentially one by one. Basically the handler is asynchronous with the receiver (incoming message handling process).

When a message, which has been marked as "synchronous" from the SmartSync client, comes in, it requires that the message is handled synchronized within SmartSync backend receiver. A handler, named "S-handler", handles the process. In order to keep the consistency of all incoming messages on the backend, the S-handler does not handle the incoming message with "synchronous" mode prior to other messages that are in the work-list waiting. The S-handler still handles all the messages in work-list sequentially until it is the turn of the "synchronous" message.

Because the S-handler is synchronized with the SmartSync backend receiver, the client connection to the backend has to be established until the backend has handled all messages in the work-list and sends the backend outbox messages back to the client.

API Usage

Application may enable the "synchronous" mode to either a SyncBoRequest or a SyncBoOutDeltaData.

For a SyncBoRequest, the "synchronous" mode can be enabled either at runtime or at design time. However for a SyncBoOutDeltaData, it can only be enabled at runtime.

Enable SyncBoRequest as Synchronous Sync at Design Time

There is an attribute "reqDirectSync" of SyncBo element in an application XML-Meta file, the default value for this attribute is "false", set the attribute value to "true" can enable the "synchronous" mode of SyncBoRequest at design time. Enable the "reqDirectSync" attribute means whenever synchronization to backend, SyncBoRequest for the SyncBo requires synchronous synchronization, however using SmartSync API can switch the mode at runtime.

Enable SyncBoRequest as Synchronous Sync at Run Time

The following steps demonstrate how to enable a SyncBoRequest as "synchronous" mode using SmartSync APIs.

These steps have to be processed every time before the synchronization starts. After the synchronization, SmartSync resets the SyncBoDeltaRequestType back to the default value.

Enable SyncBoOutDeltaData as Synchronous Sync

It is necessary to register an Outbox listener in order to enable a specific SyncBoOutDeltaData to be sent in synchronous mode.

The following steps demonstrate how to enable a SyncBoRequest in"synchronous" mode using SmartSync APIs.

The above steps need to be processed every time before the synchronization starts. After synchronization, SmartSync resets the SyncBoDeltaRequestType back to the default value.


Application Data Reset

SmartSync provides the function to reset data. It allows an application to clean up the application data on the client, and then download the data from the backend.

General Description

The sequence number is not reset in the reset process.


API Usage

Example: Reset data and submit existing SyncBoOutData before the resetting.

SmartSyncRuntime.getSyncBoDeltaRequestFacade( VisibilityType. USER_SHARED ).setGlobalResetProcessing(GlobalResetProcessing.RESET)

Example: Reset data and destroy the existing SyncBoOutDeltaData.

SmartSyncRuntime.getSyncBoDeltaRequestFacade( VisibilityType. USER_SHARED ).setGlobalResetProcessing(GlobalResetProcessing.DELETE_OUT_DELTA_AND_RESET)

 

Handle SyncBoInDeltaData With "ERROR" SyncReply

General Description

When the backend cannot post an uploaded delta data message - SyncBoOutDeltaData of SmartSync client, the backend returns a data delta message with a reverse action of the original upload delta data - SyncBoInDeltaData of SmartSync client, as well as a SyncReply, which contains an "ERROR" SyncReply type and error text.

SmartSync client posts the SyncBoInDeltaData - rollback operation, in order to keep the data consistency between client application data and the backend data.

During synchronization, the application can register a SyncBoInDeltaObserver to monitor the SyncBoInDeltaData status by checking the SyncReply. It can backup the original SyncBo before the SyncBo data is rolled back. The application cannot modify the SyncBo data during the synchronization., It is only allowed to copy the original SyncBo to an unlinked SyncBo by using SyncBo.createUnlinkedCopy in case the action of the SyncBoInDeltaData is "insert", "modify", or "replace". SyncBo.createInitialCopy handles the "delete" action of the SyncBoInDeltaData.

After synchronization, the application may use of the copied unlinked SyncBo, for example to edit it, and use the "replace" or "insert" API functions to commit/store the change on the client. SmartSync takes care of the delta data management, and sends the edited SyncBo delta data to the backend during next synchronization.

SmartSync has no API to persist an unlinked SyncBo. Applications have to manage the copied unlinked SyncBo itself, such as keeping it in a memory stack, or persist it using the persistence layer API.

 

An Use Case

An item is added on the client to a SyncBo instance of "customer order" - meanwhile this customer order has been changed in the backend since the last synchronization. The change on the backend is in that way that no more items can be appended to the customer order.

What is done

First, the client sends the "insert" modification information to the backend. The backend however cannot post this new item accordingly and therefore returns a "delete" to the client for this "customer order" item. This delete is now the reverting action, bringing the client database back to the same state as the backend. Logically, it can be seen as the information that is necessary to perform a rollback operation.

Now the application can rescue the data of the new order item before rollback -for example, create a new customer order and append this item to the new customer order. In this case, after being notified by SyncBoNotifier, the registered SyncBoInDeltaObserver could read the information, that the deletion of this order item is a "rollback" of the initiated client change, by checking the contents of the SyncReply instance. This instance is accessible via the SyncBoInDeltaData instance.

As one possible solution to this conflict, the SyncBoInDeltaObserver could, if implemented by the application, create a new customer order, copy the order item that has to be deleted and then assign this copied item to the new customer order after synchronization.