Skip Headers
Oracle® Database Lite SQLite Mobile Client Guide
Release 10.3

Part Number E16214-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

4 Using an Android Application on the SQLite Mobile Client

As described on the Android developer Web site at http://developer.android.com, all applications for the Android platform are required to be digitally signed in order to be installed on the Android device. This key is also used to encrypt the SQLite database. Thus, only the user with the key can access the database and perform synchronization.

Because of the required key, you cannot download and install the SQLite Mobile client binaries unless they are downloaded within the context of a signed application. Thus, there is no option for a manual synchronization through mSync. Instead, all manual synchronization events are invoked through synchronization APIs.

Note:

This chapter assumes that you know how to use Eclipse to build an Android project and how to appropriately develop and sign an Android application.

The following sections uses the simple_sync_android project to describe the steps to include the SQLite Mobile client within your signed application.

4.1 Prerequisites

The following are the prerequisites for enabling synchronization for a SQLite application:

  1. Install Eclipse IDE with the ADT plug-in, as detailed at the following site:

    http://developer.android.com/sdk/eclipse-adt.html#installing
    
  2. Install the latest Android SDK, as detailed at the following site:

    http://developer.android.com/sdk/index.html
    
  3. Install the Oracle Database Lite Mobile Development Kit.

4.2 Developing an Android Application for Oracle Database Lite

When developing the application for an Android platform, perform the following to include the SQLite Mobile client:

  1. Use the Oracle Database Lite pure Java synchronization APIs to invoke a manual synchronization. For more information on the pure Java APIs, see Section 4.3, "Synchronization API for Pure Java Applications on SQLite Mobile Clients" in the Oracle Database Lite Developer's Guide.

  2. Sign and build your application according to Android specifications.

An Android platform sample named MainAct.java is included in the <MDK_ROOT>\Mobile\Sdk\samples\Sync\android\simple_sync_android directory. The MainAct.java sample initializes the required synchronization structures and invokes the synchronization APIs.

4.3 Import the Oracle Database Lite Android Project into Eclipse

The following steps show how to import your Android project using the Oracle Database Lite simple_sync_android sample project.

  1. Import the Oracle Database Lite sample Android project into your Eclipse Workspace.

    1. Select File->Import and then choose Existing Projects into Workspace. Click Next.

      Figure 4-1 Import Existing Projects into Eclipse Workspace

      Import project into eclipse workspace
      Description of "Figure 4-1 Import Existing Projects into Eclipse Workspace"

    2. Set the root directory to point to the Android project within the Oracle Database Lite MDK. Enable the Select Root Directory button and browse for the simple_sync_android project, which is located in the following directory:

      <MDK_ROOT>Mobile\Sdk\samples\Sync\android\simple_sync_android
      

      where the <MDK_ROOT> is replaced with the full path where the Oracle Database Lite MDK is installed.

      Figure 4-2 demonstrates setting the root directory. After which, all projects in the specified root directory are displayed in the Projects window.

      Figure 4-2 Select Root Directory for Eclipse Project

      Set root directory
      Description of "Figure 4-2 Select Root Directory for Eclipse Project"

    3. Select the simple_sync_android project and click Finish. The simple_sync_android project is now imported into your Eclipse Workspace.

4.4 Build Oracle Database Lite Android Project

The following details how to build your Android project using the Oracle Database Lite simple_sync_android sample project.

  1. Set required environment variables. The project references Oracle Database Lite synchronization classes, which are located within the osync_android.jar library file. Set the MOBILE_SYNC_ANDROID_LIB environment variable to point to the location of this JAR file with the following steps:

    1. Highlight the simple_sync_android project in the Project Explorer window, as shown in Figure 4-3.

      Figure 4-3 Project Explorer window

      Project explorer window
      Description of "Figure 4-3 Project Explorer window"

    2. Select 'Alt Enter' to display the Project Properties window.

    3. As shown in Figure 4-4, select the Java Build Path in the left pane. Then, select the Libraries tab in the Java Build Path window. Click Add variable.

      Figure 4-4 Properties for simple_sync_android Project

      Add new variable
      Description of "Figure 4-4 Properties for simple_sync_android Project"

    4. Click Configure Variables.

      Figure 4-5 Configure a New Variable

      Configure a new variable
      Description of "Figure 4-5 Configure a New Variable"

    5. Click New to add a the new variable.

      Figure 4-6 Add New Path Variable

      Add new path variable
      Description of "Figure 4-6 Add New Path Variable"

    6. Enter MOBILE_SYNC_ANDROID_LIB in the Name field and add <MDK_ROOT>/Mobile/Sdk/android/lib/osync_android.jar in the Path field.

      Figure 4-7 Creating the MOBILE_SYNC_ANDROID_LIB Environment Variable

      Create environment variable
      Description of "Figure 4-7 Creating the MOBILE_SYNC_ANDROID_LIB Environment Variable"

    7. When finished, click OK. The MOBILE_SYNC_ANDROID_LIB variable provides the library directory where the osync_android.jar file is located, which is required to build your project.

  2. Refresh and build the simple_sync_android project to link in the osync_android.jar file with the Oracle Database Lite synchronization libraries.

  3. Execute and debug the simple_sync_android project with the Android emulator.

    1. Right click on the simple_sync_android project.

    2. Click Run As and select Android Application. The Android emulator is started, where you can execute the sample as the Mobile Sync application.

      Figure 4-8 Test Project with Android Emulator

      Android emulator
      Description of "Figure 4-8 Test Project with Android Emulator"

  4. When you execute the Mobile Sync application, synchronization is initiated. Enter your username, password and Mobile Server URL in the Sync UI, as shown in Figure 4-9.

    Figure 4-9 Synchronization UI

    Synchronization UI on Android
    Description of "Figure 4-9 Synchronization UI"

  5. After the initial synchronization, verify that the SQLite database files are created in the following directory on your Android device:

    /data/data/<pkg_name>/app_oracle.sync/sqlite_db
    

    where <pkg_name> is the name of your package. For example, the simple_sync_android sample stores its SQLite database files in the following directory:

    /data/data/tests.sync/app_oracle.sync/sqlite_db
    
  6. Once you have completed testing your project using an Android emulator, perform the following:

    1. Build and sign your project according to Android standards as described on http://developer.android.com. All applications on the Android platform are required to be digitally signed with a certificate whose private key is held by the application's developer. The application developer signs the Android application with his or her own signing key. This key is also used to encrypt the SQLite database.

      The Android platform tests the signer certificate's expiration date at install time.

    2. Download your application to all intended Android devices.