Synchronizing Android Applications – Part 1

SymmetricDS now has its web-enabled, fault-tolerant, database synchronization software available on the Android mobile computing platform. The Android client follows all of the same concepts and brings to Android all of the same core SymmetricDS features as the full-featured, Java-based SymmetricDS client. The client is designed to be referenced as a library to run in-process with an Android application requiring synchronization for its SQLite database.

By using SymmetricDS, mobile application development is simplified, in that the mobile application developer can now focus solely on interacting with their local SQLite database. SymmetricDS takes care of capturing and moving data changes to and from a centralized database when the network is available.

One of the main goals of the SymmetricDS 3 release was to support deployment to Android devices. SymmetricDS’s overall footprint was reduced by eliminating a number of external dependencies in order to better deploy to Android. Also, the database access layer was abstracted so that the Android specific database access layer could be used. This allows SymmetricDS to be efficient in accessing the SQLite database on the Android device.

In order to convey how to use the SymmetricDS Android libraries, the rest of this two-part article will show how easy it is to integrate SymmetricDS by demonstrating embedding SymmetricDS into the NotePad sample application that comes with the Android ADK.

The NotePad sample application is a very simple task list application that persists “notes” to a SQLite database table called Notes. The Notes table will be configured to synchronize to a centralized version of the table.

This example will be presented in two parts. This first part will describe how to embed SymmetricDS in the NotePad application. The second part will describe how to setup the central server with an enhanced version of the Notes table that is keyed by both the _ID column as well as the unique id of the SymmetricDS instance so that the centralized Notes table can be shared between multiple Android devices. Eclipse 3.7.2 and Android ADK 20.0.3 were used for this demonstration.

New Sample NotePad Project

Let’s get started embedding SymmetricDS into the NotePad application. The first step is creating the NotePad project. You do this by adding a new Android Sample Project. Select the NotePad project.

Sample NotePad Project

SymmetricDS for Android comes as a zip file of Java archives (jar files) that are required by the SymmetricDS client at runtime. This zip file can be found in the “android” directory of the SymmetricDS Pro install. The first step to using SymmetricDS in an Android application is to unzip the jar files into a location where the project will recognize them. The latest Android SDK and the Eclipse ADK requires that these jar files be put into a libs directory under the Android application project.

Unzip the symmetric-ds-x.x.x-android.zip file to the NotePad project directory. Refresh the NotePad project in Eclipse. You should end up with a libs directory that is automatically added to the Android Dependencies.

Jar Files Added to Libs

The Android version of the SymmetricDS engine is a Java class that can be instantiated directly or wired into an application via a provided Android service. Whether you are using the service or the engine directly you need to provide a few required startup parameters to the engine:

• SQLiteOpenHelper – It is best (but not required) if the SQLiteOpenHelper is shared with the application that will be sharing the SQLite database. This core Android Java class provides software synchronization around the access to the database and minimizes locking errors.
• registrationUrl – This is the URL of where the centralized SymmetricDS instance is hosted.
• externalId – This is the identifier that can be used by the centralized SymmetricDS server to identify whether this instance should get data changes that happen on the server. It could be the serial number of the device, an account username, or some other business concept like store number.
• nodeGroupId – This is the group id for the mobile device in the synchronization configuration. For example, if the nodeGroupId is ‘handheld’, then the SymmetricDS configuration might have a group called ‘handheld’ and a group called ‘corp’ where ‘handheld’ is configured to push and pull data from ‘corp.’
• properties – Optionally tweak the settings for SymmetricDS.

In order to integrate SymmetricDS into the NotePad application, the Android-specific SymmetricService will be used, and we need to tell the Android application this by adding the service to the AndroidManifest.xml file. Add the following snipped to the Manifest as the last entry under the <application> tag:

<service android:name=”org.jumpmind.symmetric.android.SymmetricService” android:enabled=”true” > <intent-filter> <action android:name=”org.jumpmind.symmetric.android.SymmetricService” /> </intent-filter> </service>

The other change required in the Manifest is to give the application permission to use the Internet. Add this as the first entry in the AndroidManifest.xml right before the <application> tag.

<uses-permission android:name=”android.permission.INTERNET”></uses-permission>

The only additional change needed is the call to start the service in the application. The service needs to be started manually because we need to give the application a chance to provide configuration information to the service.

In NotePadProvider.java add the following code snippet in the onCreate method.

NotePadProvider.java

final String HELPER_KEY = "NotePadHelperKey"; 

// Register the database helper, so it can be shared with the SymmetricService 
SQLiteOpenHelperRegistry.register(HELPER_KEY, mOpenHelper); 
Intent intent = new Intent(getContext(), SymmetricService.class); 

// Notify the service of the database helper key 
intent.putExtra(SymmetricService.INTENTKEY_SQLITEOPENHELPER_REGISTRY_KEY, HELPER_KEY); 
intent.putExtra(SymmetricService.INTENTKEY_REGISTRATION_URL, "http://10.0.2.2:31415/sync/server"); 
intent.putExtra(SymmetricService.INTENTKEY_EXTERNAL_ID, "android-simulator"); 
intent.putExtra(SymmetricService.INTENTKEY_NODE_GROUP_ID, "client"); 
intent.putExtra(SymmetricService.INTENTKEY_START_IN_BACKGROUND, true); 

Properties properties = new Properties(); 
// initial load existing notes from the Client to the Server 
properties.setProperty(ParameterConstants.AUTO_RELOAD_REVERSE_ENABLED, "true"); 
intent.putExtra(SymmetricService.INTENTKEY_PROPERTIES, properties); 
getContext().startService(intent);

This code snippet shows how the SQLiteOpenHelper is shared. The application’s SQLiteOpenHelper is registered in a static registry provided by the SymmetricDS Android library. When the service is started, the key used to store the helper is passed to the service so that the service may pull the helper back out of the registry.

The various parameters needed by SymmetricDS are being set in the Intent which will be used by the SymmetricService to start the engine.

Most of the parameters will be familiar to SymmetricDS users. In this case a property is being set which will force an initial load of the existing Notes from the client to the server. This allows the user of the application to enter Notes for the first time offline or while the SymmetricDS engine is unregistered and still have them arrive at the centralized server once the SymmetricDS engine does get registered.

That’s all you have to do to integrate SymmetricDS with your Android application. Users who are adventurous or are already familiar with SymmetricDS can probably figure out how to setup the central SymmetricDS server and configuration synchronization for the Notes table. The second part of Synchronizing Android Applications will describe exactly that. A few transformation goodies will be thrown in as well.