Sunday, 19 August 2012

Understanding the Mobile Client

There is a lot of documentation provided by Oracle, and I spent considerable time reading these. Despite the long hours that I spent reading the docs, it took me several days to understand how the mobile client hangs together in the whole architecture. For example, it took me ages to understand that the instructions provided in Chapter 4 of the Oracle Database Mobile Server Mobile Client Guide are vital to set up the mobile client. It took me over two weeks to understand exactly how the mobile application will "address" or "find" the database.  I am used to Connect Strings, JDBC connections etc.. in my legacy applications. But for the life of me I could not figure out how my mobile application will open a connection to the database on the device!

Let me take a stab at providing my own view of the mobile client. In upcoming blogs I will also provide information on how to do all of this :-)

I suggest that the mobile client be viewed as two separate pieces. The first piece called "Mobile Sync" is required to create the directory structure of the Mobile Client on the Android device. The second piece, and I will call it the Oracle Update piece, really helps to pull applications and updates from the Oracle Mobile Server. 

Let me elaborate on some of the points that confused me for academic reasons.

How will the Oracle Mobile Server sync publications and publication items with a database on the device? Exactly, which database does it sync to? How do the tables associated with the Publication and items get onto the device?

Suggested Reading: Storage Options on Android

Basically, the Oracle Mobile Sync application is the first piece of the puzzle. You must build this application and install it on the Android Device. When this application is run the first time, it creates a directory structure in internal storage on the device under the /data/data directory structure. If you really want to go and take a peek at this, you can do so with adb. I even went to the extent of rooting an old phone that I had to get a full understanding of what was going on (rooting a phone allows you superuser access - so you can see everything and have complete control of your device. Just search on the web for 'how to root android phone' and you will get information). 

I found that the Mobile Sync application created a structure /data/data/tests.sync and then created some configuration files like ose.ini and default SQLite database default.db under this path in /data/data/tests.sync/app_oracle.sync

This led me to my next roadblock. If the Mobile Sync application puts the database in its Application directory in internal storage, how will my application be able to read this database? Considering that Android 'sandboxes' applications and their files, I could not understand how my application would connect to this database sitting in the Mobile Sync's application directory. 

The simple answer. You can control the location of the database on the Mobile device by configuring a file named OSE.INI on the device. So all one has to do is point a parameter DATA_DIRECTORY to a common location that can be 'seen' by both the application and the sync client - most likely on external storage (SD card) to get over space limitations in internal storage.

Again, Oracle documentation is unclear on how the OSE.INI gets edited. Since I had a rooted phone, I used adb pull and adb push to replace the old OSE.INI file with my version. Turns out that the OSE.INI file can be edited from the Mobile Sync client itself! So, here is what one needs to do to install Mobile Sync and then 'point' it to a common storage area.

Step 0: Set up Oracle Database Mobile Server and a new user
Step 1: Import the simple_sync_android application into Eclipse
Step 2: Build Mobile Sync Application and install it on device
Step 3: Edit OSE.INI file and point DATA_DIRECTORY to a directory on external storage
Step 4: Connect to DMS using the user credentials created in Step 0 and sync to create the basic directory structures used by the Mobile Client.

Now that the database is created and available in External Storage, you can address it from your mobile application.

I have described how the Mobile Sync piece works thus far. Let us now look at the second piece - the Oracle Update.
Oracle Update application allows the device to pull publications, publication items and applications onto the device. For Android, you can point your browser on the device to <mobile server>/mobile/setup and install the appropriate software. You will first install an application named Oracle Setup. You will be automatically made to install two other applications named Oracle DMAgent and Oracle Update. 

When you launch Oracle Update and connect to the DMS, you can see any new application update (including publication and publication items) made available to you. So, every time you update, new applications, upgrades, publications and publication items will get on to your device.

Finally, another point that was not quite clear to me was how to install or package the mobile application itself to install on device. You really have two choices. The first method is to simple push your application (APK file) on to the device using Eclipse or Titanium (in my case). The second method is to bundle the application and publish through the DMS. 

Now for most readers who have come this far, it might still not be clear as to how all this hangs together. I recommend that you review my next 2-3 posts where I will walk you through a sample deployment and then return to this blog to get a complete understanding.


  1. Hello ,
    I have built the simple_sync_android application,installed it on the device. I am trying to sync the simple_sync_android application. But I keep getting the error
    Encountered Error: Plugin has thrown an exception. See the cause....
    Please help.

  2. Please look into the Error log. With Mobile Sync app running, click Settings on your phone and you can see Error log.

  3. any possible way to resolve this exception....

  4. Try this... , in Eclipse
    1. Go to Project Properties
    2. Java Build Path
    3. Order and Export Tab
    4. Ensure that variable MOBILE_SYNC_ANDROID_LIB is checked
    5. Click Top and make it first entry
    6. Rebuild

  5. I am getting following error:
    Server error ,id=2000:"ORA-00942 table or view does not exist"

    please help me.......thanks in advance

  6. Hi Avnish , There are many reason for getting this error , If you could give more details
    , are you creating publication in MDK or by java code ?

  7. This is a decent overview. I would like to understand better the "DMAgent". There doesn't seem to be very good doc'n ANYWHERE about how to configure each type of network (ie. SMPT, SMS, HTTP, etc.) with examples and requirement.

    1. JD, I think you should try posting to the Oracle DMS Forum for this. I have not really done any work in this area. I have had pretty good experience getting responses from the Oracle Team. It takes a few days, but they do engage


Note: only a member of this blog may post a comment.