Tuesday, June 26, 2012

Beginning Android Part 4 - Apache Cordova Persistence Support

Revision History
Latest: Revision 0.5 - Aug. 15, 2012
  • Created
  • First draft
  • 2nd draft
  • Added "Running The Demo Application" video
  • 3rd draft
  • Added "Running The Demo Application as Dolphin Garage Web-App"
  • 4th draft
  • Enhancement
  • 5th draft
  • Final

Persistence is a mean of saving applications state and it is one of the most important qualities necessary to reuse an application. Imagine what it would be like if an application like word processors such as Microsoft Office, OpenOffice does not have the quality of saving your documents, or an image manipulation program such as GIMP cannot save your images! An application can save its state into a datastore. The datastore can be a relational databases (RDBMS) such as MySQL, or a flat-file or an XML files.

Android Storage Quickview

Android supports many storage options for you to save your persistent application data. It is important for you to carefully read the official Android Storage Options documentation.
Android data storage options are the following:
  1. Shared Preferences - Store private primitive data in key-value pairs.
  2. Internal Storage - Store private data on the device memory.
  3. External Storage - Store public data on the shared external storage.
  4. SQLite Databases - Store structured data in a private database.
  5. Network Connection - Store data on the web with your own network server.

Persistence Strategy: What kind of data storage should I use?

The decision about which of the Android storage options you choose is usually determined by the following:
  1. Application Properties - You can use SharePreferences here.
  2. Database - You should use SQLite if you need to store structured data.
  3. Filesystem - You can use the Internal/External storage options.
This tutorial will focus on storage options provided by Apache Cordova to store structured data in a database.

Apache Cordova - Android

Apache Cordova is an HTML5 app platform that allows you to author native applications with web technologies and get access to APIs and app stores.
In this article, we will:
  1. Briefly covered the two feasible options of Cordova for offline storage on mobile devices
First - Please carefully read the CordovaStorage documentation along with W3C spec for Web SQL Database support. The W3C docs helped fill in some things that the Cordova documentation didn’t cover such as the error and labels forSQLError.

Working Offline: Caching

Cordova provides two feasible options for persisting your applications data: LocalStorage and Web SQL.
Web SQL is a thin, asynchronous wrapper around an SQLite database which is currently well-implemented on first-class mobile devices (iOS, Android, and BlackBerry OS 6.0). Note thatWebSQL is not supported on Firefox and IEThe WebSQL spec was deprecated in Nov. 18, 2010.
Web SQL offers a useful interface for storing structured data, it works well if you have a remote server that uses a SQL databases and you want to mirror the structure of your data between platforms. I will use this Web SQL standards in my demo application because it is fast and heavy-duty and because the storage size of SQLite is much bigger compare to local storage and well-implemented on first-class mobile devices such as Android.

Time for Action: A Simple To-Do Application

Ok, so let’s talk about the application. My demo application is called TodoListPhoneGap. It only allows you to add a task (it is your assignment to add the other functionality). You can checkout the source code by issuing the following command on terminal:
Once you’ve checked out the TodoListPhoneGap project, open it with Eclipse.
1. The first thing we need to do when using Cordova is to get a reference to our database, using the openDatabase function:
function createTaskDB() {
        db = window.openDatabase("TaskDB", "1.0", "Simple Tasks", 1000000);
The openDatabase function requires four parameters: the name of the dabase, the version of the database, the display name of the database, and the size in bytes of the database.
2. The next step is to create a table to store our records. To do this, we will start a transaction on ourdb, and execute the SQL query asynchronously:
// start transaction on out db
db.transaction(createTable, sqlErrH, getTaskList);
The function transaction accepts three parameters: the function that will executes the SQL query, the function to handle the errors (if any), and the function to call when transaction is successful.
function createTable(tx) {
        tx.executeSql("CREATE TABLE IF NOT EXISTS task (id unique, taskname)");
3. Finally, we need to populate and query the table in our db. To do this, we will start a transaction again on our db, but this time we will pass a DML (Data Manipulation Language such as INSERT, UPDATE, SELECT, DELETE) instead of DDL (Data Definition Language such as CREATE, DROP, ALTER).
db.transaction(function(tx) {
        tx.executeSql("INSERT INTO task (taskname) VALUES (?)",[ task.taskname ]);
}, sqlErrH, cb);

Running The Demo Application

Running The Demo Application as Dolphin Garage Web-App

Dolphin announced its Garage Open API at Google I/O 2012. PhoneGap and Dolphin browsers recently team up.
Steps to run my demo application as a thin-client web-app for Dolphin users:
1. Checkout my demo application using SVN
2. Copy the files located in <your project's name>/assets/www to your web server (i.e. Tomcat)

3. Place cordova.dolphin.js to your web-server.

4. Make changes to index.html. Just replace js/cordova-1.5.0.js with js/cordova.dolphin.js

5. Run your web-server.

6. Test the demo application:
  1. Download Dolphin Browser HD and the PhoneGap add-on.
  2. Access <your webserver>/TodoListPhoneGap using the Dolphin Browser HD.
The first approach shows you how to run my demo application as an Android Application Package (APK). Usually, the APK’s are release through marketplace such as Google Play.
The second approach shows you how to deploy my demo application to your web-server.

And that’s pretty much it. There’a a lot more you can do with PhoneGap. In this article you learned how to:
1. Persist application state by using the Web SQL standards.
2. Use Dolphin Garage API.

Further Reading:



No comments:

Post a Comment

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