Getting Started: Samples

The sync sample app demonstrates the 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 sample

The source code for the sync sample apps, both client and server, is included in the 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 iOS sync client app is located in the ios-sdk/samples/sync 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 for the sync sample app:

  • 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.

iOS SDK system requirements

To develop iOS client apps, your development environment must meet the following system requirements:

  • Mac OS X
  • Xcode 5

Deploy the Akula sync app scopes

Two 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:

  1. Stop the Akula Server.
  2. Locate the server-sdk/samples/projects/customsync/target directory in the location where you installed Akula.
  3. Copy the customsync.akz file to the AKULA_HOME/deploy directory.
  4. 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:

  1. Stop the Akula Server.
  2. Navigate to the server-sdk/samples/projects/routesync directory. This is the directory that has the build.xml file.
  3. Execute the following command:

    ant install

    The included Ant script packages the app scope as an AKZ file and deploys the routesync.akz file to the AKULA_HOME/deploy directory.
  4. Restart your Akula Server.

For more information about the route sync project, see the README.txt file in the download.

Run the sample project

To build the iOS client app, you have to edit the source code so that the client app references your Akula Server:

  1. Locate the ios-sdk/samples/sync directory in the location where you installed Akula.
  2. Open the Sync project in Xcode.
  3. In Xcode, open the ASConstants.h file.
  4. Modify the following line to specify the location of the Custom Sync app scope (customsync.akz) on your Akula Server:

    #define kBase_URL @" http://localhost:8080/akula/customsync "

    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:

    #define kBase_URL @" http://myMachine.myco:8080/akula/customsync "

    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:

    <string name="server_url">  http://localhost:8080/akula/routesync  </string>


  5. Save your changes and build the app.

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:

  1. 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.

  2. 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.

  3. Select the Sync button in the upper-right corner; 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.

  4. Click the "+" icon in the upper-right corner to add a task; then name the task and click the Save button. The task is saved to the persistent data store.

  5. 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.

  6. Select the Menu button while the Local Changes screen is visible; 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.

  7. To view the rejected records, select Menu > Rejected Changes from the main screen.

  8. 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: