Clearly, the Cookie and Depot objects are simplistic, and while attractive for casual data storage and caching, they won’t fulfill the need for formal database support. To address that need, Palm webOS includes support for the HTML 5 Database object to create, update, and query an SQL database. Like the Depot, the HTML 5 database interfaces are asynchronous, requiring you to use callbacks for much of your database handling.

openDatabase( "ext:mydbname", ... );

The HTML 5 specification includes extensions for structured client-side storage, including support for the Storage and Database objects. Palm webOS does not support the Storage object, a list of name/value pairs that grew out of Firefox’s DOM Storage object, but it does support the Database object.

The openDatabase() method will create a new database or open an existing database, returning a Database object:

this.db = openDatabase("myDB", 1, "My DB", 10000);

The arguments are as follows (see Table 6-1).

The database version property is meant to represent the schema version, enabling smooth migration of the database forward through schema changes. If the application specifies a database name and a version number, both need to match an existing database for the database open to succeed; otherwise, a new database will be created.

Once the database is open, you can execute transactions against it, using either transaction() for read/write transactions or readTransaction() for read-only transactions. The transaction methods will specify one to three callbacks:

The transaction callback is the most important; it includes the transaction steps that you wish to execute using an executeSQL() method, which accepts an SQL query string as an argument along with success and error callbacks.

For example, the following code segment calls the transaction method with a literal function that includes two executeSQL() methods, the last of which specifies a success callback, this.successHandler(), and an error callback, this.errorHandler():

MyAssistant.prototype.activate = function()    {
          .
          .
          .
this.db.transaction( (function (transaction) {
            transaction.executeSql('A BUNCH OF SQL', []);
            transaction.executeSql('MORE SQL', [], this.successHandler.bind(this),
               this.errorHandler.bind(this));
     }).bind(this);
          .
          .
          .
MyAssistant.prototype.successHandler = function(transaction, SQLResultSet) {
// Post processing with results

};

MyAssistant.prototype.errorHandler = function(transaction, error)  {
    Mojo.Log.Error('An error occurred',error.message);

    // Handle errors here
};

The success handler is passed the transaction object plus an SQLResultSet object as an argument. The attributes of the results object are described in Table 6-2.

We’ve only touched on the basics of the HTML 5 database capabilities in this section. As a draft standard, HTML 5 will continue to evolve. You should review the formal SQL reference at http://dev.w3.org/html5/webstorage/#databases for more in-depth information. There’s also a basic demo application at http://webkit.org/demos/sticky-notes/index.html.