When designing a sync strategy for your server, you can use the built-in Route Sync module or create a custom one. This section describes how to create a custom sync module.

This section describes the following topics:

For complete examples that use a custom sync module, see:

• Android Sync Sample App
• iOS Sync Sample App
• Cordova Sync Sample App

Overview

When the client app uses the persistence manager to perform a sync, the following occurs:

1. The client constructs an object that represents all of the changes that have occurred to the data in the persistent data store since the last successful sync. For Android and iOS, this object is an AKChangeSet object ( Android / iOS). For JavaScript clients, this object is a standard JavaScript object.   
2. The client uses the change set object to construct the request object and sends it up to the endpoint that is specified by the sync method.
3. The custom sync module processes the request based on its synchronization rules. 
4. The custom sync module constructs a response to send to the client.
5. The client updates its persistent data store with the server-side updates. 

As you can see from this process, the client-side work is performed automatically when the client app initiates the sync. However, on the server side, your custom sync module must process the request from the client. This request might contain data updates that your module must process. The module must also construct a properly-formatted response that contains server updates to send to the client.

You define a custom sync module for each object type that you want to synchronize. Therefore, if you want to synchronize data represented by a Customer class and data represented by a Sales class, create two different custom sync modules.

There are many ways to handle data synchronization on the server and many issues to consider. For example, when designing your module, consider conflict resolution, which can occur when two or more clients modify the same object. Or, consider how the module determines which server-side data changes to send back to the client. 

A custom sync module must extends the AKAbstractSyncModule class. In addition, you typically do the following in your Akula app scope for sync processing:

• Connect to your back end data store.
• Validate records sent up from the client.
• Implement logic for sending added, updated, and deleted records to the back end data store.
• Implement logic for getting added, updated, and deleted records from the back end data store.
• Serialize input and output messages.
• Implement an exception class for error handling.

Extending the AKAbstractSyncModule class

The AKAbstractSyncModule class is the abstract base class for custom sync modules. You must override all abstract methods in this class. These methods fall into the following categories:

• Core methods – The core methods are init() and process(). These methods serve the same purpose as the init() and process() methods of all custom modules. For more information, see Creating Custom Modules.
• Collect methods – The collect methods (collectFullSyncData(), collectPartialSyncUpdate(), collectPartialSyncDelete()) get data from the back end and add it to the context. This data is then returned to the client. 
• Validate methods – The validate methods (validateForAdd(), validateForUpdate(), validateForDelete()) can be used to check the incoming add, update, and delete requests from the client to ensure that they are valid. 
• Execute methods – The execute methods (executeAdd(), executeUpdate(), executeDelete()) process the adds, updates, and deletes on the back end based on the request from the client. 
• Utility methods – The getSyncServerToken() and getSyncServerKeys() methods provide information about the server sync token (typically, a time stamp) and primary keys used by the back end data store. 

Core methods

The core methods initialize and define the flow of the custom sync module.

The init() method is called when the module is first instantiated. In this method, you can access route parameters, if necessary.

The process() method processes the input message and prepares the output message. This method defines the flow of a call to the sync module. This method typically executes app-specific initialization and business logic. At a minimum, you should call super.process(exchange). 

Collect methods

The collect methods get data from the back end and add it to the context. This data is then returned to the client.

You must override the following collect methods in your custom sync module:

• collectFullSyncData() – Gets all records from the back end and adds a List of Maps to the context.
• collectPartialSyncUpdate() – Gets only the updated records from the back end and a List of Maps to the context.
• collectPartialSyncDelete() – Gets only the deleted records from the back end and adds a List of Maps to the context.

In the partial collect methods, you typically check the client's sync token (typically, a time stamp) against the server's sync token to only return records that were added, updated, or deleted based on an arbitrary comparison of tokens. This makes sync operations more efficient by not returning all data in the back end on every request, and only the change set. If you use a time stamp as the sync token, for example, then the server returns data that has been added, updated, or deleted since the last time the client performed a sync operation. 

The collect methods take the following argument:

• Context – The AKSyncContext object. This object contains all the inbound request data and outbound response data for the sync operation.

The collect methods do not return anything. Instead, they add the results of their operations to the context.

The following example gets all records from the database that meet some basic criteria and adds them to the context:

Validate methods

The validate methods can be used to check the incoming add, update, and delete requests from the client to ensure that they are valid before they are executed on the back end data store. These methods are where you implement the business logic for your back end. For example, you might check that a Customer has at least a first name and last name defined, and that the email address uses the appropriate format.

You must implement the following validate methods in your custom sync module:

• validateForAdd() – Called for each ADD operation that is sent from the client.
• validateForDelete() – Called for each DELETE operation that is sent from the client.
• validateForUpdate() – Called for each UPDATE operation that is sent from the client.

You can also use the validate methods to check for duplicate keys and perform other tasks prior to executing the add, update, and delete.

The validate methods take the following arguments:

• Context – The AKSyncContext object. This object contains all the inbound request data and outbound response data for the sync operation.
• Index – The index of the ADD, UPDATE, or DELETE record in the client sync request. Because Akula calls the validate methods once for each ADD, UPDATE, and DELETE operation, the index is necessary to find the record on the context.
• Record – The record to be added, updated, or deleted. For ADD and DELETE operations, this is a Map<String, Object> of objects, where each String is the field name (or column name) and each Object is value for that field. For UPDATE operations, this is a List of Maps, the first Map<String, Object> of objects is the field name/value pairs for the new record and the second Map<String, Object> is for the original record's values.

The validate methods do not return anything, unless the validation fails. In this case, the validate methods throw an exception.

The Akula Server calls the validate methods for each sync type. If the validate method does not throw an exception, the Akula Server then calls the execute method for that sync type. For example, if the client sends a new record, Akula calls validateForAdd(). If this method does not throw an exception, the Akula Server then calls the executeAdd() method.

To validate fields in a record, you extract the record from the Map and process it. The following example creates a new Customer object and does some simple validation:

If the validateForAdd() method throws an exception, then the executeAdd() method does not get called for that record.

Execute methods

The execute methods process the adds, updates, and deletes on the back end based on the request from the client. For a SQL-based back end, this is where you define the SQL statements and execute them against the data store. 

You must implement the following execute methods in your custom sync module:

• executeAdd() – Adds a record to the back end data store.
• executeDelete() – Removes a record from the back end data store.
• executeUpdate() – Updates a record in the back end data store.

Each time an execute method is called, it processes a single record. For example, if there are three records to add to the back end, the executeAdd() method is called three times, once for each record to add.

The execute methods are called only after the validate methods are called. For example, if the client requests an ADD operation, the validateForAdd() method is called first. If no exceptions are thrown, then the executeAdd() method is called to add that new record.

The execute methods take the following arguments:

• Context – The AKSyncContext object. This object contains all the inbound request data and outbound response data for the sync operation. 
• Index – The index of the ADD, UPDATE, or DELETE record in the client sync request. Because Akula calls the execute methods once for each ADD, UPDATE, and DELETE operation, the index is necessary to find the record on the context. 
• Record – The record to add, update, or delete. For ADD and DELETE operations, this is a Map<String, Object> of objects, where the String is the field name (or column name) and the Object is the value of the field. For UPDATE operations, this is a List of Maps, the first Map<String, Object> contains the field name/value pairs for the new record and the second Map<String, Object> contains the data for the original record. 

For UPDATE and DELETE operations, the execute methods do not return anything. For ADD operations, the execute method (executeAdd()) returns a Map<String, Object> of the record that was added. This is because ADD operations generate a new server key that must be sent back to the client.

The following example deletes a record from the back end data store:

When you add a new record to the back end, the executeAdd() method returns an AddResult object. This object contains the new record's primary key and a Map of the new object's values. 

The following example builds the AddResult object:

Utility methods

You must implement the following utility methods in your custom sync module:

• getSyncServerToken() – Gets the current server sync token. Most commonly, this is a time stamp, but the token can be any string you want. This method returns a String. This method can be as simple as creating a new Date object and returning it as a String.
• getSyncServerKeys() – Gets a list of primary keys that the back end data store has defined for the data you are synchronizing. This method returns a List<String>.