Skip Headers

Oracle® Database Lite SQLite Mobile Client Guide Release 10.3 Part Number E16214-01 |
Home | Book List | Contents | Index | Contact Us

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

- Section 4.1, "Prerequisites"

- Section 4.2, "Developing an Android Application for Oracle Database Lite"

- Section 4.3, "Import the Oracle Database Lite Android Project into Eclipse"

- Section 4.4, "Build Oracle Database Lite Android Project"

## 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

      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

      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

      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

      Description of "Figure 4-4 Properties for simple_sync_android Project"

   4. Click Configure Variables.

      Figure 4-5 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

      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

      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

      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

   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.