Getting Started: Samples
Page: Android Sync Sample App
Page: Android Encryption Sample App
Page: Cordova Encryption Sample App
Page: iOS Encryption Sample App
Page: Android Sample Apps
Page: iOS Sync Sample App
Page: Cordova Sync Sample App
Home page: Samples
Page: Cordova Sample Apps
Page: Server Hello World Sample App
Android Sync Sample App
The Android sync sample app demonstrates best practices when using Akula's synchronization mechanism. Because the Akula sync feature builds on top of the persistent data feature, this app builds on the Encryption sample app which is the recommended entry point for these features.
This document contains the following sections:
Get the samples
The source code for the sync sample apps, both client and server, is included in the Verivo_Akula_SDK_v2.5.0.zip file. The files are also available on the Downloads page (log in required). Ensure that you have already installed Akula before proceeding. If you have not installed Akula, contact us for more information.
Viewing the client app source code
The source code for the Android sync client app is located in the android-sdk/samples/sync/src directory in the location where you installed Akula. The steps below include information about editing the source code before you run the sample app.
Viewing the server app source code
There are two server app scopes available as sync samples:
- Custom Sync – Uses a custom module to process synchronization requests.
- Route Sync – Uses the built-in Route Sync module to process synchronization requests.
The source code for the Custom Sync app scope is located in the server-sdk/samples/projects/customsync directory in the location where you installed Akula. This directory includes the source code for the Akula app scope and for the custom sync module used by the app scope. While you do not have to modify the server app scope to run the sync sample app, you can use it as a reference for building your own sync module.
The source code for the Route Sync app scope is located in the server-sdk/samples/projects/routesync directory in the location where you installed Akula
Android SDK system requirements
To develop Android client apps, your development environment must meet the following system requirements:
- Windows or Mac OS
- Android SDK supporting API Level 10 (Android OS 2.3.3) or higher: http://developer.android.com/sdk
- Android samples are compatible with JDK 1.6 and 1.7
Deploy the Akula sync app scopesTwo Akula server app scopes are available to use with the sync client app. You can use one or both of them. For each one you want to use, deploy the corresponding AKZ file to your server. They must be deployed one at a time. The files are:
- customsync.akz (for Custom Sync)
- routesync.akz (for Route Sync)
The customsync.akz file is available in the server-sdk/samples/projects/sync/target directory in the location where you installed Akula. The routesync.akz file must first be built using the source code.
Deploy the Custom Sync app scope
To deploy the Akula Custom Sync app scope:
- Stop the Akula Server.
- Locate the server-sdk/samples/projects/customsync/target directory in the location where you installed Akula.
- Copy the customsync.akz file to the
- Restart the Akula Server.
Build and deploy the Route Sync app scope
Before you can use the Route Sync app scope (routesync.akz), you must download and build it. This process requires that you have Apache Ant installed.
To download, build, and deploy the Route Sync app scope:
- Stop the Akula Server.
- Navigate to the server-sdk/samples/projects/routesync directory. This is the directory that has the build.xml file.
- Execute the following command:
The included Ant script packages the app scope as an AKZ file and deploys the routesync.akz file to the
- Restart your Akula Server.
For more information about the route sync project, see the README.txt file in the download.
Build the sample client app
To build the Android client app, you must edit the source code so that the client app references your Akula Server.
- Locate the android-sdk/samples/sync directory in the location where you installed Akula.
- Import the android-sdk/samples/sync project into your IDE. For example, for Eclipse, import the .project file and ensure that you select Android > Existing Android Code Into Workspace in the Import dialog box.
- Add the android-sdk/lib/AkulaAndroid-x.y.z.jar file to the project.
- Ensure that you have selected Android API level 14 or higher as your build target. While the Akula Android SDK requires API level 10, the sample app uses level 14 APIs.
- Open the android-sdk/samples/sync/res/values/strings.xml file in a text editor.
Modify the following line to specify the location of the Custom Sync app scope (customsync.akz) on your Akula Server:
For example, if the Akula Server is running on your local machine, and the Tomcat or JEE server port number is 8080, edit the line as shown below:
Do not use localhost to reference the Akula Server. Use the IP address or DNS name of your machine.
If you are using the Route Sync app scope (routesync.akz), use the following URL:
Clean, build, and run the app on a simulator or device. If you have an existing Cordova sample on the device, be sure to delete it before deploying a new sample because the samples have the same name and they will cause conflicts.
|Resolve build errors|
If you get an error such as the following
[2015-04-16 15:34:56 - Dex Loader] Unable to execute dex: Multiple dex files define Lcom/google/common/annotations/Beta;
[2015-04-16 15:34:56 - Encryption] Conversion to Dalvik format failed: Unable to execute dex: Multiple dex files define Lcom/google/common/annotations/Beta;
Use the sample app
If you run the sync sample on two different devices or simulators at the same time, make sure that the two devices/simulators are set to the same time and time zone.
The purpose of sync is that changes from one mobile device can be synced with other mobile devices that are connected to the same Akula Server. However, it is hard to demonstrate sync if you have only one device or simulator. Therefore, the Custom Sync app scope (customsync.akz) on the Akula Server implements the following features to simulate a realistic environment:
- Tasks due on weekends are rejected by the server module as if your boss rejected them.
- Each time you sync with the server, you receive a new task as if your boss assigned you a new task.
The Route Sync app scope (routesync.akz) does not perform these tasks. To see changes made by another device when using the Route Sync app scope, you must test with two devices or manually change the SQLite database on the server.
To use the sample app:
Enter a password to unlock the encrypted persistent data store. Remember this password because you need it every time you unlock the persistent data store.
Click the Menu button and select Local Changes. The Local Changes screen should be empty because you have not added or updated any tasks yet.
Select the Menu button while the Local Changes screen is visible, and then select either Incremental Sync or Full Sync to sync with the data on the server.
The first time you sync, the server returns two new tasks in the form:
Sample Todo #1: Try adding a task to the list.
Sample Todo #2: Update your new task's due date.
On every subsequent sync, the Custom Sync app scope returns another new record in that format. The server also updates one record to be in the "completed" state, and deletes the last record that it marked completed. The Route Sync app scope simply syncs your client data with your server data.
Click the "+" icon in the upper-right corner to add a task. The task is saved to the persistent data store.
From the main screen, click the Menu button and select Local Changes. You should see your new task under the Adds area of the screen.
Select the Menu button while the Local Changes screen is visible, and then select either Incremental Sync or Full Sync.
If the data in your new record is valid, the sync succeeds. The Custom Sync app scope rejects tasks if they are due on a weekend, or if their text is empty. If a task is submitted that violates these constraints, it is rejected, and appears in the Rejected Changes screen.
Also, the server rejects a deleted record if it is not in the completed state.
These business rules apply only to the Custom Sync app scope. If you are using the Route Sync app scope, then the server does not reject records during a deletion, regardless of their state.
To view the rejected records, select Menu > Rejected Changes from the main screen.
Try editing an existing record to set its due date to a weekend to see it being rejected.
For more information
For more information, see: