Data Containers  |  Wrapper functions   |  Generic Sync Example

 

Generic Sync API

The Generic Sync API lets you create and process data containers as well as get information about the synchronization process - that means registering for events during synchronization or read the synchronization log. Synchronization settings are stored in the MI configuration.

In this chapter, we'll cover each of these aspects of the API separately:

For an example of the Generic Sync API, consult the Generic Sync example.

Data container handling

The Generic Sync API reflects very closely the data container processing cycle:

  1. Creating data containers
    Outbound containers are created via the factory class OutboundContainerFactory. As the OutboundContainerFactory is implemented as a singleton, your call would look something like this:
    OutboundContainer yourOutboundContainer = OutboundContainerFactory.getInstance().create…
    There are several create methods to get your OutboundContainer. The method has got different parameters. One of these is a VisibilityType. This parameter is responsible for the visibility of your data container. One value is VisibilityType.SEPARATED. With this parameter the data is completely separated per user and application. The other value is VisibilityType.USER_SHARED. With this parameter the data is separated per application but shared between all users on this device.

  2. Filling data containers
    The outbound container instance is then filled via the methods furnished by the interface OutboundContainer.
    You add line items to the outbound container and eventually close it. Closing the data container adds it to the outbound queue and ensures that it will be sent to the WebAS on next synchronization.

  3. Synchronization
    Synchronization is always triggered from the MI client, never from the WebAS. Typically, the end user of the mobile device starts synchronization by manually pressing the sync button . Applications can also start synchronization by calling the SyncManager. Implemented as a singleton, you first get the singleton instance via getInstance and then call synchronizeWithBackend to start synchronization. By default, only data container with VisibilityType SEPARATED for the current user and all containers with VisibilityType USER_SHARED are synchronized, that means data containers belonging to other than the current user will not be synchronized by default. Applications can override the default by calling
    SyncManager.getInstance().synchronizeWithBackend(VisibilityType.USER_SHARED);
    It is also possible to synchronize via disk instead of via http. In that case, the entire sync queue is saved on disk. The disk content can later be uploaded to the WebAS via the Web Console.
  1. Inbound processing
    After processing all data containers from the mobile device, the Web AS sends the entire queue of data containers for the current user back as http response. The framework loops through the "inbound" containers and notifies theInboundProcessor that is registered for the "inbound" container.

    There is always one inbound processor class for every back end method. The getMethodName the inbound processor identifies, which data containers it is responsible for. The implemented InboundProcessor class needs to be registered with the InboundProcessorRegistry. This needs to happen only once and typically happens in the doInitalize method of the servlet implementing the AbstractMEHttpServlet.

    The implementing class of InboundProcessor has to implement java.io.Serializable. Example for an InboundProcessor class:
    public class MyInboundProcessor implements InboundProcessor, Serializable {
    
    
        private String methodName = "MDK_USER_INFO_READ";
    
        public String getMethodName(){
            return this.methodName;
        }
    
        public void process(InboundContainer inboundContainer){
    // This method implements what to do with incoming container. This method is called by the inbound processor whenever a container
    // is found that is registered for this inbound processor.
        }
    }
    
    Hint: "MDK_USER_INFO_READ" is the name of the backend method.

    If the framework identifies that a data container is processed by a given InboundProcessor, it calls its process method and passes the InboundContainer to the InboundProcessor. The InboundProcessor can then access all header data (status, method, owner, send date, etc.) or read all InboundContainerElements. For each InboundContainerElement it can request field name and field value. Typically an application would store this information for later via the Persistence API.

Synchronization events

During the synchronization process, the framework fires SyncEvents that applications can register for. This gives the applications control over the synchronization process. Typical applications for the SyncEvents are for example, adding outbound data containers before the synchronization starts or do some cleanup work at the end of synchronization. To register for SyncEvents, an application class implementing the SyncEventListener interface needs to call the SyncEventRegistry.

Synchronization log

The synchronization process is logged extensively by the framework. This log can be accessed by applications via the class SyncLog.

Synchronization Settings

The Synchronization settings for user, language, web gateway etc. govern the synchronization process. They are maintained manually by the user in the My settings dialog. You can read and write these settings via the corresponding properties in the Configuration API.