9/10

# 6 Migrating from Oracle Lite Client Database to Berkeley DB

The Oracle Lite Client Database is no longer supported as of Oracle Database Mobile Server 11g. Oracle recommends replacing the Oracle Lite Client Database (OLite) with Oracle Berkeley DB (BDB): a fast, highly scalable, ACID compliant database. For those users using the Oracle Lite Client Database to synchronize with the backend to an Oracle Database through Oracle Database Mobile Server, the following Section 6.1, "Migration Guideline" provides helpful information and steps to migrate from OLite to BDB.

## 6.1 Migration Guideline

The recommended migration paths for the common OLite use cases are:

1. If you deploy OLite on mobile devices, and the Mobile Server is used to synchronize data between mobile devices and an Oracle database, then it is recommended to replace OLite with BDB.

2. If you are using Web-to-Go on the client side to run JAVA Servlets, and OLite as the client data store, you need to replace Web-to-Go with a Servlet container and replace OLite with BDB.

3. If you are using Branch Office, which consists of OLite and a Multi-User Listener as a database service for multiple users and applications, there is no identical functionality in Oracle Database Mobile Server 11g. Contact Oracle sales to design an appropriate solution.

In scenarios 1 and 2 above, you may want to migrate the data stored in OLite to BDB and modify your applications because of the differences in APIs, SQL syntax, database drivers, etc.

The following sections provide you step by step instructions on how to migrate client side application data from OLite to BDB.

- Section 6.1.1, "Backup OLite Database"

- Section 6.1.2, "Upgrade Oracle Lite Mobile Client"

- Section 6.1.3, "Export Oracle Lite Database"

- Section 6.1.4, "Migrate OLite Publication"

- Section 6.1.5, "Upgrade Oracle Database Lite Mobile Server 10.3.0.3.0 to Oracle Database Mobile Server 11g"

- Section 6.1.6, "Create BDB-based Publication and Application"

- Section 6.1.7, "Install BDB Mobile Client"

- Section 6.1.8, "Import Data to BDB"

After migration, you can synchronize your application data in the backend Oracle Database through Oracle Database Mobile Server.

### 6.1.1 Backup OLite Database

Before you start migration, backup your OLite database on your mobile devices. You can backup the OLite database either by using the backupdb utility or by copying the database files to a safe location. Before any files can be copied, stop all applications that access the OLite database and shut down the multi-user service if it is running. Once completed, execute the backupdb utility. To backup OLite database, use the syntax:BACKUPDB DSN DBName backup_filename [DB_password]Refer to Oracle® Database Lite Oracle Lite Client Guide Release 10.3 for the usages of backupdb utility.

### 6.1.2 Upgrade Oracle Lite Mobile Client

Download and apply the latest patch for Oracle Database Lite Mobile Server 10.3.0.3.0 to support exporting OLite database. After you apply the patch, restart the Mobile Server and execute "Update" from Oracle Lite Mobile Client.

A new version of Oracle Lite Mobile Client will be downloaded and installed which enables you to export OLite database.

### 6.1.3 Export Oracle Lite Database

The newly installed Oracle Lite Mobile Client supports exporting OLite database to binary files using File-based Sync. You can either export data in graphical mode using msync or programmatically using OSE Synchronization API. The steps for exporting data using msync are as follows:

1. Enable OLite data export

   Modify polite.ini, write the following in [SYNC] section:

   OSE_EXPORT_PLUGIN=explite

   This step could be automated by adding <ini> section to the patch file:

   1. In the patch files:

      <ORACLE_HOME>/mobile/server/admin/repository/setup/dmc/[win32|linux/x86|wince/ppc60]/patch_[win32|linux-x86|ppc60]_bug#.inf

      After

      <action msg_i='$FILE_I$' msg='$FILE_U$'>ini</action>

      Add

      <action msg_i='$INI_I$' msg='$INI_U$'>ini</action>

      Then, add <ini> element after </file>

      <ini>

      <item name='POLITE.INI' section='SYNC'>

      <item name='OSE_EXPORT_PLUGIN'>explite</item>

      </item>

      </ini>

   2. The same should be done for patch files in the

      <ORACLE_HOME>/mobile_oc4j/j2ee/mobileserver/applications/mobileserver/setup_HOME

2. Export OLite data

   1. Export data to the default location. Launch msync. The "Server URL" field should show "N/A(Export Mode)" . Click "Sync" button to export data. By default it will export data into the following file:

      $(USER_DIR)\ose_exports\ose_export_$(SYNC_USER).bin

      USER_DIR is the user home directory on the machine; SYNC_USER is the sync user name. For example: C:\Users\Jack\ose_exports\ose_export_jack.bin

   2. Export data to a customized location

      You can also customize the export file name and location as follows:Launch msync, go to "Tools" - "File Sync Options" menu, check the "File Based Sync", set the mode to "Send" and enter the file location in the "File" field. Click "Sync" to export data. (Do not click "Apply" button because there is a known issue with the mync UI that if you check "File Based Sync" option and click "Apply" button, msync UI will crash. ) Then after export is done, you will get the exported data in the location you specified.

   3. After the export is done, you should see the following message in the msync result window:

      "The database data has been exported. Please proceed with client upgrade."

      Now you can uninstall Oracle Lite Mobile Client.

   If you want to export OLite data programmatically using OSE Synchronization API, refer to Oracle® Database Mobile Server Developer's Guide on how to use File-based Sync.

### 6.1.4 Migrate OLite Publication

The existing OLite publications require migration to support BDB clients. You can migrate the OLite publications before upgrading 10.3.0.3.0 to 11g by running the migration tool MigrateOlitePublication.bat (or MigrateOlitePublication.sh) located at <ORACLE_HOME>/mobile/server/bin to migrate you OLite publications.You can also write a Java program to migrate the OLite publications by a Consolidator.

Java API call: addBDBSQLiteDevFlg(String name)String name is the OLite publication name.

### 6.1.5 Upgrade Oracle Database Lite Mobile Server 10.3.0.3.0 to Oracle Database Mobile Server 11g

Refer to Oracle Database Mobile Server Documentation Release 11.2.0 on how to upgrade the Mobile Server.

### 6.1.6 Create BDB-based Publication and Application

Creation of a new BDB publication is only required if the OLite publication has not been migrated by the method described in Section 6.1.4, "Migrate OLite Publication". You can either use Mobile Development Kit (MDK) or write a program using Consolidator Java API to create BDB publications if needed. Create a new application or modify the existing application and deploy it to the Mobile Server.

1. Create or modify the application

   There are some differences between OLite and Berkeley DB that you need to pay attention to:

   - OLite supports Oracle SQL extensions and Berkeley DB does not.

   - OLite and Berkeley DB both support SQL-92, but in some cases, modifications will be required.

   - OLite and Berkeley DB both support ADO.NET, ODBC, JDBC APIs, but the drivers and usages of these APIs are different.

   - Berkley DB does not support OKAPI, SODA and SODASQL.

     Refer to Berkeley DB documentation on how to write applications with BDB.

2. Deploy the application to Mobile Server

   Deploy your application to Mobile Server either using Packaging Wizard or programmatically using Mobile Server APIs. You have two choices:

   - Delete the old OLite application and publish the new BDB application, then re-assign existing users to the new application.

   - Modify the existing OLite application. This approach does not require to re-assign existing users to the modified application

### 6.1.7 Install BDB Mobile Client

Download BDB Mobile Client from Oracle Database Mobile Server 11g to your mobile device and install it.

### 6.1.8 Import Data to BDB

After instaling BDB Mobile Client, you are ready to import the data that you exported from OLite database to BDB.

1. Import data with default option

   After you install BDB Mobile Client, if there is an export .bin file in the default location ($(USER_DIR)\ose_exports\ose_export_$(SYNC_USER).bin), data migration will happen automatically. The first sync will be setup sync and the next sync will import sync.

2. Customizing data import

   Alternatively, if you want the export file to be in a different (non-default) location and name, follow the instructions:

   1. Put the following in [DEFAULT] section in ose.ini to enable setup sync:

      OSE.SETUP_SYNC=TRUE

   2. Launch msync, click “Sync” button to start setup sync. You will see the following message in msync result window after setup sync is done:

      "The client databases have been set up. Please sync again to import the data from the binary file generated during the export stage. If you would like to specify custom location for this file, please use the File sync options."

   3. The next sync will automatically be import sync.

      Go to “Tools” -> “File Sync Options” menu, check the “File Based Sync”, set the mode to “Receive” and enter the file location in the “File” field. Click “Sync” to start import sync and you will see sync progress dialog. After import sync is done the following message will be displayed:

      "The client data has been imported. This concludes the client upgrade."

   Now data migration is done.

   If you want to import OLite data to BDB programmatically using OSE Synchronization API, refer to Oracle® Database Mobile Server Developer's Guide on how to use File-based Sync.