Offline Data Synchronization Using IBM Worklight JSON Store

Introduction:

                This blog provides an overview of JSONStore for offline data synchronization using Apache Cordova integrated IBM Worklight mobile platform for enterprise solutions.

Why JSONStore:

          While creating mobile applications the important thing that comes into picture is handling client side data Storage. There are number of ways to handle the local storage. A couple of them are HTML5 local storage and JSON. HTML5 local storage has a drawback in storing complex data structures like objects. It can store only text keys and strings and it has a storage limit of 5Mb. This problem can be solved by using JSON instead of HTML local storage. JSON is capable of handling more complex data structures like objects in database.  IBM Worklight comes up with JSONStore API that supports offline mode, client-server synchronization and encryption. Currently JSONStore is available for Android and iOS platforms.

Overview of JSONStore:

           JSONStore is an application’s data that have been saved locally and on request, pushed to the back-end service via an adapter.  The local data can be secured by using password-based encryption.  A password based encryption can be done by specifying a password using usePassword() method.  JSONStore enables to search, update and delete the new and existing data without network connectivity

JSONStore feature makes it easy to write applications that work with a client side cache (optionally encrypted) of server side data, and synchronize with the server as connectivity allows. It all starts with the Adapter. An adapter is simply a transport layer used to connect to various backend services.  The application specific data is saved locally in JSONStore on the device. JSONStore communicates with the adapter to perform user actions. The adapter reflects the changes in the data in the backend server. In the same way to retrieve from the   backend the adapter talks to the backend server and gets the data and stores it in JSONStore. The JSONStore stores the data in a file in device’s internal storage. JSON Store doesn’t possess any storage limit like local storage. It takes the available space on the device. On android device the data residing in JSON Store can be found at

/data/data/com.[app-name]/databases/wljsonstore/jsonstore.sqlite

The data residing in the JSONStore can be deleted, updated, added etc. A newly created document stores the data locally. To store it in the backend server user has to push the data by using push method of the adapter. A set of documents can also be pushed at a time by using push method. The documents that are unpushed can also be obtained by calling getPushRequired() method. The documents updating can be done by calling replace() method.  Similarly a particular document can be removed by calling remove() method. 

Creating Adapter:

To create a new adapter Right click on adapter folder

                     Right Click > New > Worklight Adapter

 A new wizard appears where the user can choose his/her own adapter type. Procedures for JSON offline store can be automatically created by selecting the checkbox provided in the wizard.

Deploying Adapter:

 To deploy the Worklight adapter

  Right Click > Run As > Deploy Worklight Adapter

 Then the adapter will be deployed on the Worklight server.

Invoking Adapter:

 Adapters can also be directly invoked by following this procedure

           Right Click on adapter name > Run As > Invoke Worklight Procedure

 A new wizard appears where the procedure to be invoked can be selected. But make sure the input format provided by the user should match the input format expected by the web service. If the adapter call is success it will display JSON formatted output with is Successful field set to true and false if the adapter invocation has failed.

Linking Collection to an Adapter:

 Linking a collection to an adapter allows JSONStore to:

• Send data from a collection to an IBM Worklight Adapter.
• Get data from an IBM Worklight Adapter into a collection.

Those  two  can also be achieved using functions  like  WL.Client.invokeProcedure() to transmit and receive data, and getPushRequired()  to get the changes. The collection can be initialized as follows:

usersCollection = WL.JSONStore.initCollection(               “array”,               usersSearchFields,               {adapter: usersAdapterOptions,               onSuccess: initCollectionSuccessCallback,               onFailure: genericFailureCallback,               load:true}),

 

Adapter options, success callback and a failure callback functions are provided to the collection. When a JSONStore is created by default the following CRUD operations can be obtained from the wizard. For example if the name of the adapter is User the procedures will be as follows:

<procedure name=“getUsers“> </procedure>         <procedure name=“addUser”> </procedure>         <procedure name=“updateUser”> </procedure>         <procedure name=“deleteUser”> </procedure>

These procedures can be implemented in adapterimpl.js file. For retrieving data using getUsers the implementation file will be as follows:

function getUsers() {               var path = ‘WorklightWS/worklightdemo/UserProfileWS/GetUserProfileData‘;        var input = {               method : ‘get’,               returnedContentType : ‘json’,               path : path        };        return WL.Server.invokeHttp(input);  }

 Similarly for adding, updating and deleting the implementation logic has to be modified in adapter implementation file.