path: root/doc/src/webkit/guide/chapter_cache.qdoc

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the Qt WebKit documentation.
**
** $QT_BEGIN_LICENSE:BSD$
** You may use this file under the terms of the BSD license as follows:
**
** "Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions are
** met:
**   * Redistributions of source code must retain the above copyright
**     notice, this list of conditions and the following disclaimer.
**   * Redistributions in binary form must reproduce the above copyright
**     notice, this list of conditions and the following disclaimer in
**     the documentation and/or other materials provided with the
**     distribution.
**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
**     the names of its contributors may be used to endorse or promote
**     products derived from this software without specific prior written
**     permission.
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
** $QT_END_LICENSE$
**
****************************************************************************/

/*!

\page qtwebkit-guide-cache.html
\title Client Storage (BETA)
\chapter Client Storage

Traditional mobile web development centered around the limitations of
client handsets,
which had very little storage for applications.
As handsets become more powerful,
however,
this assumption is no longer valid.
HTML5\'s newly introduced Storage features expand application storage
on the client.

HTML 5 standardizes access to an application\'s local data via
\c{LocalStorage} and \c{SessionStorage} APIs.
These APIs boost the amount of client storage available to web
applications.
They also can effectively replace cookies as a means to maintain
application state and track user preferences.

Local storage persists indefinitely,
while session storage lasts only for the duration of a window session.
Local storage is available from any page or window from the same site,
while session storage is local to each window.
Both local and session storage rely on simple key/value pairs,
with keys and values both stored as strings.

Local and session storage are not the only client storage available.
HTML 5 WebSQL serves as a more full-featured,
client-side database.
WebSQL brings SQLite-based structured database functionality,
typically deployed on servers,
to client browser applications.
WebSQL is appropriate for data-intensive applications requiring
complex queries rather than simple key/value access.
WebSQL database transaction calls help avoid interfaces from locking
up,
facilitate rollback and error handling,
and protect against SQL injection.
Database versioning allows you to manage schema changes incrementally.


\section1 Simple Data Storage

The \c{localStorage} and \c{sessionStorage} APIs offer applications
up to 5MB of data storage. They both share the same simple key/value
interface, but have different namespaces and also differ in the extent
to which data is available. Local storage persists indefinitely, while
session storage only lasts for the duration of a window session. Local
storage is available from any page or window from the same site, while
session storage is local to each window.

The following examples demonstrate the API interface.  While these use
\c{localStorage} as an example, the same set of API calls work for
\c{sessionStorage}, which is also available within the \c{window}
object.

The following performs an initial check for support of browser-based
storage and assigns the database to a variable:

\code
if (window.localStorage) {
    var db = window.localStorage;
    // storage functionality here
}
else {
    // store data remotely?
}
\endcode

The \c{getItem()} method retrieves the value of a database field named
\bold{key}:

\code
var value = db.getItem("key");
\endcode

Note that both keys and values are represented as strings.
If you specify any other type of data,
it is converted silently to a string representation.
(See \l{Storing Non-String Data} for ways around this limitation.)
If \c{getItem()} returns \c{null} rather than a string value,
it means the specified key does not exist.

The \c{setItem()} method establishes a new value.
When adding data,
it is a good idea to check to make sure you haven\'t exceeded the
allotted storage space:

\code
try {
    db.setItem("key", "string");
}
catch(err) {
    if (err.QUOTA_EXCEEDED_ERR) {
        // storage space is exceeded
    }
}
\endcode

The \c{removeItem()} method deletes database fields:

\code
db.removeItem("key");
\endcode

The \c{clear()} method deletes all key/value pairs within the
database, either for an entire site in the case of \c{localStorage},
or for an individual window session in the case of \c{sessionStorage}:

\code
db.clear();
\endcode

Databases can be accessed as arrays using index notation, useful in
cases where you may not know all the field names.  The \c{length}
property returns the number of fields in the database, and the
\c{key()} method returns the name of the key corresponding to a given
index. The following reflects the contents of a database in a
JavaScript object:

\code
var obj = {};
for ( var i = 0, l = db.length ; i < l ; i++ ) {
    obj[ db.key(i) ] = db.getItem( db.key(i) );
}
\endcode

Since keys correspond to array indexes, you should not add or remove
keys during any operation that iterates over the full set of key/value
pairs. Newly introduced keys are introduced randomly into the array\'s
sequence.

The following displays simple storage functionality. The application
prompts for a login and password if they are unavailable. This locally
stored data is available the next time users open the browser.
However, the contents of the credit card field is stored only for the
duration of the browing session.

\l{ex_storage}{\inlineimage webkit-guide/scr_storage.png
}

\l{storage_css}{(CSS)}
\l{storage_js}{(JavaScript)}


    \section2 Storing Non-String Data

    Since local and session storage APIs only support string values, you
    need to be careful not to allow errors that result from passive
    conversions from other data types. The following sample shows how
    such an error might come about:

    \code
    var db = window.localStorage;
    var saveCardInfo;
        // user expresses preference NOT to save credit card info:
    saveCardInfo = false;
        // BUG happens here...
    db.setItem("save_card_info", saveCardInfo);
        // variable is now a string, not a boolean:
    saveCardInfo = db.getItem("save_card_info");
        // both "true" and "false" strings evaluate as true...
    if ( saveCardInfo ) {
        // ...so this code always executes...
    }
    else {
        // ...and this code never executes.
    }
    \endcode

    The user\'s preference to retain credit card information is expressed
    within the application as a \c{true} or \c{false} boolean value. When
    each value is passed to storage, however, it is passively converted to
    a string. When reassigned to a JavaScript variable, it no longer
    serves as a valid boolean test. The application falsely assumes users
    want to save credit card information, regardless of their expressed
    preference.

    The following sample fixes the problem. Instead of using \c{true} and
    \c{false} boolean values, it converts \c{1} and \c{0} strings to
    numbers:

    \code
    var db = window.localStorage;
    var saveCardInfo = 0;
    db.setItem("save_card_info", saveCardInfo);
    // multiplying forces numeric output:
    saveCardInfo = db.getItem("save_card_info") * 1;
    \endcode

    For a more reliable alternative, store values as JSON strings and rely
    on automatic type conversion when subsequently parsing them.  The
    following sample shows how parsing JSON preserves both boolean and
    numeric data:

    \code
    var saveCardInfo = true;                    // boolean
    var shipMethod = 2;                        // number
    var db = window.localStorage;

    db.setItem("save_card_info", JSON.stringify(saveCardInfo));
    db.setItem("ship_method", JSON.stringify(shipMethod));

    saveCardInfo = JSON.parse(db.getItem("save_card_info"));    // boolean
    shipMethod = JSON.parse(db.getItem("ship_method"));        // number
    \endcode

    Note that this simple approach may cause problems of its own. For
    example, perhaps the words \bold{true} and \bold{false} really should
    be represented as strings. Encapsulating data within objects accounts
    for such variability:

    \code
    var db = window.localStorage;
    var obj = {
        bool    : true,
        str        : "true",
        num        : 1
    };
    db.setItem("appState", JSON.stringify(obj));    // to database...
    // "appState" is "{'bool':true,'num':1,'str':'true'}"
    obj = JSON.parse(db.getItem("appState"));    // ...and back
    // obj is same as initially defined.
    \endcode

    The ability to save objects as JSON strings means that you can save an
    application\'s state within a single database field.  For example, you
    might use the following approach to save the entire contents of a
    shopping cart in a single field for later use:

    \code
    var db = window.localStorage;
    var cart = { items: [] };

    cart.message = "From your loving uncle";

    cart.items.push({
        description    : "Floor to Ceiling Shoe Rack",
        id        : 203174676,
        price    : 99.95,
        quantity    : 1,
        weight    : 20,
    });

    cart.items.push({
        description    : "Automatic Laser Toy for Cats",
        id        : 203345371,
        price    : 19.95,
        quantity    : 2,
        weight    : 0.5,
    });

    // save all cumulative items:
    db.setItem("cart", JSON.stringify(cart));

    // extract items from storage:
    cart = JSON.parse(db.getItem("cart"));
    \endcode

    JSON allows you to store data types, but functions are ignored.  That
    makes it more difficult to preserve objects representing fully
    functional applications.

    \section2 Storage Events

    The \c{storage} event allows applications to respond indirectly to
    modified data resulting from calls to \c{setItem()}, \c{removeItem()},
    or \c{clear()}. This may be useful in providing users with visual
    feedback notifying them of data that is modified locally, perhaps
    rather than being sent to a remote server:

    \code
    window.addEventListener("storage", function(event){
        var icon = document.querySelector("#indicator");
        if (event.storageArea.length) {
            icon.className = "writing";
        }
        else {
            icon.className = "empty";
        }
    }, false);
    \endcode

    The \c{storage} event\'s \c{storageArea} attribute returns the
    \c{localStorage} or \c{sessionStorage} object being modified. The
    \c{key} is the name of the field being modified, and \c{oldValue} and
    \c{newValue} are its values before and after the event. The \c{url} is
    the page that called the method triggering the change.


\section1 WebSQL Databases

While common local- or session-based databases are capable of storing
complex data structures, QtWebKit-based browsers can also rely upon
the WebSQL standard, which brings SQLite-based structured database
functionality, typically deployed on servers, to client browser
applications. Based on SQLite version 3.6.19, WebSQL is appropriate
for data-intensive applications requring complex queries rather than
simple key/value access.

The following test confirms support for WebSQL:

\code
if (!!window.openDatabase) {
    // supports WebSQL
}
\endcode

Calls to databases made via the WebSQL API are made asynchronously via
transactions to avoid the user interface from locking up, as database
interaction may occur from several windows at a time.

The three core API methods are:

\list

\o \c{openDatabase()}

\o \c{transaction()}

\o \c{executeSql()}

\endlist

    \section2 Creating and Opening a New Database

    To create and open a database, use \c{openDatabase()}on the Window object,
    for example:

    \code
    var db = openDatabase('mydb', '1.0', 'my first database', 2*1024*1024);
    var db = openDatabase('notes', '', 'The Example Notes App!', 1048576);
    \endcode

    The four required arguments are the database name, version, display
    name, and estimated size in bytes.  You can supply a function as an
    optional fifth argument to serve as a callback when a database is
    created.  It may be used to call the \c{changeversion()} method, in
    which case the callback is invoked with an empty string for the
    database version.

    The second example above specifies an empty string for the version. In
    this case the database opens no matter what the database version
    is. (An \c{openDatabase()} call specifying the wrong version for an
    existing database throws an \c{INVALID_STATE_ERR} exception.) You can
    then query the version by examining the database object's version
    property, for example:

    \code
    var version = db.version;
    \endcode

    Note that you don\'t need to close a client-side Web SQL database when
    you\'re done working with it.

    \section2 Transaction Calls and ExecuteSQL Method

    Performing database transactions is superior to running SQL statements
    directly because transactions are not committed if they fail and you
    can undo them if needed. Transactions also allow you to handle errors
    using a callback. To implement a transaction, specify a callback
    function such as the following:

    \code
    db.transaction(function (tx) {
      // SQL details on the tx object go here
    }
    \endcode

    The \c{transaction()} method takes one to three arguments:

    \list

    \o a required transaction callback, in which \c{executeSQL()} calls
    belong

    \o an optional transaction error object

    \o an optional success callback.

    \endlist

    Use the \c{executeSQL()} method to specify SQL statements for read and
    write operations. The method protects against SQL injection and
    provides a callback method to process the results of any SQL queries
    you specify. The \c{executeSQL()} method takes from one to four
    arguments:

    \list

    \o a required SQL statement

    \o an optional object array of arguments

    \o an optional SQL statement callback

    \o an optional SQL statement error callback

    \endlist

    The example below creates the database if it doesn\'t exist, adds a
    two-column table to the database, and adds a row of data to the table:

    \code
    var db = openDatabase('mydb', '1.0', 'my first database', 2 * 1024 * 1024);
    db.transaction(function (tx) {
        tx.executeSql('CREATE TABLE IF NOT EXISTS foo (id unique, text)');
        tx.executeSql('INSERT INTO foo (id, text) VALUES (1, "synergies")');
    });
    \endcode

    To capture data from the user or an external source, use \c{?}
    placeholders to map that data into the SQL query. This ensures the
    data doesn\'t compromise database security, for example from SQL
    injection:

    \code
    tx.executeSql('INSERT INTO foo (id, text) VALUES (?, ?)', [id, value]);
    \endcode

    \c{id} and \c{value} are external variables, and \c{executeSql} maps
    the items in the array to the \c{?}s.

    To select values from the table, use a callback to capture the
    results:

    \code
    tx.executeSql('SELECT * FROM foo', [], function(tx, results) {
        for (var i = 0 , len = results.rows.length; i < len; i++) {
            // do something with results.rows.item(i).text
        }
    });
    \endcode

    No fields are mapped in the above query, but to use the third argument
    you need to pass in an empty array as the second argument.

    The SQL statement callback for \c{executeSQL()} is called with the
    \c{transaction} object and a SQL statement \c{result} object. The
    \c{result} gives access to the ID of the last inserted row, the number
    of rows affected, and an indexed list representing the rows returned,
    in the order returned.

    The \c{result} object contains an array-like \c{rows} object. It has a
    length, but to access individual rows you need to use
    \c{results.rows.item(i)}, where \c{i} is the index of the row.  This
    returns an object representation of each row.  For example, if your
    database has a \c{name} and an \c{age} field, the \c{row} contains a
    \c{name} and an \c{age} property. The value of the \c{age} field can
    be accessed using \c{results.rows.item(i).age}.

    \section2 Changing Database Versions

    Each database has one version at a time and multiple versions cannot
    exist at one time. Versions allow you to manage schema changes
    incrementally.

    You can change the version of a client-side Web SQL database using the
    \c{changeversion()} method:

    \code
    if (db.version == "1.0") {
        try {
            // comment out for crash recovery.
            db.changeVersion("1.0", "2.0", cv_1_0_2_0, oops_1_0_2_0, success_1_0_2_0);
        } catch(e) {
            alert('changeversion 1.0 -> 2.0 failed');
            alert('DB Version: '+db.version);
        }
    }
    \endcode

    \c{changeversion()} takes the following arguments: required old and
    new version numbers, optional SQL transaction callback, optional SQL
    transaction error callback, and optional success callback.

    \section2 Errors

    Asynchronous API errors are reported using callbacks that have a
    \c{SQLError} object as one of their arguments. \c{SQLError} contains a
    code from the table below and a localized message string.

    Error codes are:

    \list

    \o 0 \c{UNKNOWN_ERROR} Transaction failed for reasons unrelated to the DB

    \o 1 \c{DATABASE_ERROR} Statement failed for DB reasons not covered by other
    code

    \o 2 \c{VERSION_ERROR} DB version doesn\'t match expected version

    \o 3 \c{TOO_LARGE_ERROR} Data returned from DB was too large. Try the
    \c{SQL LIMIT} modifier.

    \o 4 \c{QUOTA_ERROR} Insufficient remaining storage

    \o 5 \c{SYNTAX_ERROR} Syntax error, argument mismatch, or unallowed
    statement

    \o 6 \c{CONSTRAINT_ERROR} An \c{INSERT}, \c{UPDATE}, or \c{REPLACE}
    statement failed due to a constraint error

    \o 7 \c{TIMEOUT_ERROR} Timeout waiting for transaction lock

    \endlist

    \bold{See Also:}
    \l{http://html5doctor.com/introducing-web-sql-databases/}{HTML5
    Doctor: Introducing Web SQL Databases}

*/