Tuesday, 21 August 2012

Example Step6:Test Synchronization

Finally, I recommend that you get a sense for how synchronization works between the Oracle Server and the device. Depending on the conflict resolution and other rules that you have set for your Publication and Publication items, it is pretty cool to see that synchronization does work! Since I had a rooted device, here is how I verified that two-way data synchronization was working as expected.

Step 1: Data Modified on Oracle Server
  • I logged in to the database as user AA using a SQL client
  • Issued a simple update to change one record in the ITEMS table
SQL> UPDATE items SET ITEM_DESCRIPTION = 'Sorry Grass is dark Green' WHERE ITEM_ID = 10;
SQL> COMMIT;

On my device, I fired up the Mobile Sync application and clicked 'Sync' and the verified that the data did get refreshed on my device.  Check out the screenshots provided if you are not sure how to do this.


Step 2: Data Modified on Device
  •  Use SQLite client on the device to modify a record using an UPDATE statement
  • Perform a manual sync and you should see the modification on the Server-side. I have provided a screenshot

    Download Screen Shots

Example Step5:Demo Application

Now that we have installed DMS and set up the mobile sync client along with couple of tables, we can now look at a simple Titanium application.

Note: The sample application that I use is adapted from a Titanium database example shared by Hammer! In his/her example, Hammer creates the two database tables CATEGORIES and ITEMS using the FireFox add-on SQLite Manager and includes it as a file in the Titanium project. Since the tables are already available on the device in our case, we will ignore this step. I also have made a couple of changes to the sources. Instead of using the method Titanium.Database.install, we will use the method Titanium.Database.open since the database is already available on External Storage (SD Card) and is not in the ApplicationDataDirectory in internal memory

Step 1: Create a New Titanium Project
  • Create a new Mobile project in Titanium. I named my project DB_Test and set the Application ID to net.adkoli.dbtest (this must relate to what you set for DATA_DIRECTORY in OSE.INI; please pay extra attention to this)
Step 2: Replace application files
  • Use instructions in Step 4 of Hammer's sample to replace app.js and few other files of the new Titanium project created in Step 1 above.
  • Click File->Refresh
Step 3: Edit app.js for our needs
  • Comment the line initializing the database. So, comment the line:
Titanium.Database.install('content.sqlite','contentDB');

This is because we will be using the Ti.Database.open method to open the database stored in external storage 

Step 4: Edit tab_categories.js
  • There are two database execute calls in this file. The first one is to fetch records from the CATEGORIES table and the second one is to fetch records from the ITEMS table.
  • In the section "populate category array from database", add a statement to open the database that we have installed on the device. Comment the line 
 var db = Titanium.Database.open('contentDB');

 in the existing tab_categories.js file provided by Hammer.

Replace it with the following:

if (Ti.Platform.name === 'android' && Ti.Filesystem.isExternalStoragePresent()) {
     var db = Titanium.Database.open('/sdcard/net.adkoli.dbtest/AA/TEST.db');
    }

Be sure to modify the path and database name to match the location of your database.

Make the same change in the function(showItemsInCategory) in this file.

Step 5: Build the Application and Install

  • Build the application and run in the Emulator to ensure that there are no errors
  • Then connect the Android device via the USB port and use the option "Install to Android Device"
  • Pay close attention to the log window. If all goes well you should see a confirmation that application was installed on device and that you can launch it
  • Launch DB_Test or whatever you named your app and you should see the sample application with data.
You can download a copy of my app.js and tab_categories.js files

Application Screen Shots

My Experience

  1. I have hardcoded the path to the database in the Ti.Database.open method because I could not get my code with system variables and calls to Ti.Filesystem.externalStorageDirectory working. Ideally, we should be using something like:
var db = Ti.Database.open(Ti.Filesystem.externalStorageDirectory + 'AA' + Ti.Filesystem.separator + 'TEST.db'). I kept getting an error "contains a path separator". If someone gets this going, please share your comments


Monday, 20 August 2012

Example Step4: Download Application onto Client

Thus far, have deployed an application named TestApp containing the Publication TEST with Publication items CATEGORIES and ITEMS. Access has been given to the user AA using Mobile Manager to this application. We will now install this application on to the device. By doing so, a SQLite database is created on the device containing two tables CATEGORIES and ITEMS.

Step 1: Install necessary applications
  • Ensure that your device can install non-marketplace applications. Go to Settings, Applications and ensure that "Unknown Sources" is selected.
  • Visit the URL <Mobile Server>:<port>/mobile/setup from the browser on your device. I used http://192.168.0.17:8080/mobile/setup
  • Choose SQLite Android and download it to your device. You should see a file named Setup.apk. Install this app. Provide the credentials for the user AA when prompted along with URL to the Mobile Server (use http:// in the URL, else it won't work)
  • You will automatically move into the installation of the next application named Oracle DMAgent
  • On one of the screens, you will provide information on the device for registration (I could not change the name of the device - not sure why)
  • At the end of this step, you should see three applications named Oracle Setup, Oracle DMAgent and Oracle Update installed on your device.
Update Screen Shots

Step 2:  Install the TestApp onto device
  • Launch Oracle Update and provide the credentials for user AA along with the URL to the Mobile Server
  • You should see a screen showing TestApp available as an update. Choose to install this by touching the name of the application
  • You will see confirmation that application has been installed
TestApp Screen Shots

Step 3: Validate 
  • Launch Mobile Sync application and click Sync
  • View the OSE.INI file. You should see some additional entries like QUEUES and LIMIT_CONNECTIONS
  • Use adb to view listing of the files on the SD Card
Validation Screen Shots

Example Step3: Publish Test Application

Now that the Mobile Sync application is installed on the device, we can test out the synchronization by pushing and pulling some data to/fro Oracle database and device.

Step 1: Create Sample Schema and Tables in database

We will create a new user (or 'schema' if you prefer) in the Oracle database.
  • Log in to Oracle with DBA user and use CREATE USER, GRANT etc to create a user. I created a user named AA (note that this is a database user and not a user on the DMS. I just happened to use the same name for both).
  • For the purposes of my example, I created two tables CATEGORIES and ITEMS in this schema. You can download the SQL script to create these
Step 2: Create Publication and Publication items
  • On the client development machine, launch Oracle Database Workbench
  • Create a New project named TEST
  • Create a New Publication named TEST
  • Create two New Publication Items named CATEGORIES and ITEMS using the wizard. I selected all columns of my tables CATEGORIES and ITEMS.
  • Select the publication TEST and add the two publication items CATEGORIES and ITEMS
  • Save the Project and Deploy (File-> Deploy). You can view this publication and items in the repository via Mobile Manager to double-check
  • Close MDW

    MDW Screen Shots
Step 3: Use Packaging Wizard to package an application
  • Launch Packaging Wizard, connect to repository
  • Create a new Application Definition called TestApp
  • Choose the platform SQLite Android;US from the list
  • Provide credentials to connect to repository (the database URL will be something like jdbc:oracle:thin:@192.168.0.17:1521:orcl)
  • Choose the publication TEST created in Step 2
  • Click Finish to publish the application
 Packaging Wizard Screen Shots

Step 4: Grant Access to Application
  • Log in to Mobile Manager
  • Click Applications Tab under Mobile Servers. You should see the application TestApp listed
  • Click on the Application and navigate to the Access tab
  • Choose the user AA and grant access to TestApp
Grant Screen Shots

Example Step2: Install Mobile Sync & complete first sync

Note: I have shared screen shots of these steps in a zip file at the bottom of this blog. File names of the screen shot are in parentheses in the discussion below

Step 1: Install Oracle Mobile Development Kit

Launch Oracle Installer and choose to install Mobile Development Kit. I believe Oracle does not support this installation on the same machine as the Mobile Server. I installed Oracle Mobile Development Kit on Windows XP in a VM using default options.

Step 2: Install Eclipse, Android SDK
Step 3: Build Mobile Sync application
  • Launch Eclipse
  • Import simple_sync_android application (File-> Import)
  • Choose the option Import Existing Projects into Workspace
  • Ensure that MOBILE_SYNC_ANDROID_LIB is configured properly (Project Properties -> Java Build Path). In my case, I set it to C:/OraHome_1/Mobile/Sdk/android/lib/osync_android.jar
  • Create an Android Virtual Device (Window->AVD Manager)
  • Set default Build Target to Android 2.3.3 (Project Properties, choose Android and check the default target)
  • Build and run the application in the Android Emulator (Run-> Run As)
  • You should see the Mobile Sync application in your Android Emulator. If you get a ClassNotFoundException, or Force Close, see below  
 Step 4: Install Mobile Sync application on device
  •  If you were able to build the Mobile Sync application successfully and it shows up in the Emulator, then attach your Android device to the PC with USB port. 
  • Ensure that USB driver is installed 
  • Install the application onto device Run As-> with the device connected. You should see the Mobile Sync application on the device (Sync1.png)

    Caution: Do not log in to Mobile Server as yet
  • Launch Mobile Sync application and configure the setting DATA_DIRECTORY. Click the Menu button to see options to Edit OSE.INI, View Error log etc.(Sync2.png)
  • Edit the OSE.INI file. You should see no entries in OSE.INI as yet (Sync3.png)

    Add an entry similar to: SQLITE.DATA_DIRECTORY=/sdcard/net.adkoli.dbtest
    and click Save.



    In the entry above, /sdcard is the directory for external storage (also called SD card). The rest of the entry "net.adkoli.dbtest" matches the name of my mobile application created in Titanium. More on this later. 
  • Now enter User credentials and Server URL. In my example, I had created a user AA (Sync4.png)
  • Click Sync. After a few seconds, you should see message "Sync finished successfully" (Sync5.png)
Note: Detailed instructions are available in a file named "Creating Sync Application for Android" in the \mobile\sdk\samples\sync\android\simple_sync_android folder from the installation completed in Step 1 above. 

Step 5: Sanity Check
  • Use adb to check if the directory structures expected are created. You should see a directory with username appended to it. So, in my example, you would see a directory such as /sdcard/net.adkoli.dbtest/AA.

My Experience

I had a difficult time building the simple_sync_android project out of the box. I kept getting an application Force Close and ClassNotFoundException. I had to do the following to workaround this:
  1. In Eclipse, go to Project Properties
  2. Choose Java Build Path
  3. Click Order and Export tab
  4. Move "MOBILE_SYNC_ANDROID_LIB" entry Up until it is just below the /simple/sync_android/src entry
  5. Now rebuild and this worked for me
Other errors I saw were "HTTP Transport error" while I was trying to Sync. This is because my device had lost network (Sync6.png)

I also was not able to get Mobile Sync to Save the password when I chose the option to do so (checkbox Save Password). The password is somehow saved incorrectly and I kept getting "USER_INVALID" error (Sync7.png). I suspect that the Sync client is encrypting the password provided and then using the mangled version of the password without decrypting again.

Screen Shots

I have made available screenshots to help you follow this blog. Please download zip file and extract it. The names of the files referenced are in parentheses.

Example Step1:Create User on DMS

The general idea is that one mobile client (or device) will be used by one individual user. There might be more complex environments, but in my sample deployment, I will create a user named AA on the Mobile Server and publish my test application to this user. The same application will then be installed and used on the mobile device. In this step, I will share the steps to creating this user.

Log In to Mobile Manager

Visit Mobile Manager via a browser. In my case, I pointed my browser to http://192.168.0.17:8080/mobile and logged in as Administrator.

Create a New User

I navigated to the User Manager section and used the "Create Like" feature to create a new user AA like an Administrator as illustrated below.







Sunday, 19 August 2012

Illustrated Example - 6 Steps

I will share my experience of deploying a sample application. I will break the discussion into six separate blogs as follows:
  1. Create User on DMS 
  2. Install Mobile Sync application on client and complete first sync
  3. Publish a Test Application on DMS with Publication and Publication Items to user created in Step 1
  4. Download Application onto Client
  5. Install Demo Mobile Application on device
  6. Test synchronization and mobile application
Note: I have created a separate development environment for this discussion. What I describe here don't necessarily represent best practices or my advice for a production deployment!
Prerequisite: Oracle Database Mobile Server 11g is installed and running