Persistent Storage for localStorage under iOS5.1b3 phonegap

//
// localStorage loading & saving
//
// Turns out that under iOS 5.1 (b3), the localStorage is stored in a vulnerable location.
// So, we need to ensure that the settings are consistently loaded at app startup and saved
// again at periodic times. The main app will continue to use localStorage as if nothing
// is wrong, but these functions will load and save the data to persistent storage.
//
// Author: Kerri Shotts, photoKandy Studios LLC. License: MIT.
//
// v2
//
// Added: documentation and functions to deal with non-periodic sync

/**************************************************************************
 *
 * persistent storage for localStorage (phonegap / iOS)
 *
 * These functions simply copy the data in localStorage to a persistent
 * location in the documents folder named localStorage.dat. The format is
 * pretty simple: each item is separated by [EOK], whilst the key/value is
 * separated by [EQ]. Therefore, this is easy to break (have a key/value
 * with one of these values...), but it works for my present needs.
 *
 * The persistentStorage object stores the read/write functions and can be
 * used by calling the saveLocalStorage and loadLocalStorage functions.
 *
 * By default, the routine saves data to localStorage.dat at the rate of
 * 30 seconds. If this is not desired, syncLocalStorageInterval should be
 * reset to 0 prior to the next call to saveLocalStorage(), at which point
 * the continuous saving will be stopped. At that point, it is up to you
 * to call saveLocalStorage() manually.
 *
 */

/**
 *
 * syncLocalStorageInterval defines the length of time before another
 * save operation can be started. 30000 = 30s.
 * If you wish to disable the periodic save, set this to 0.
 *
 */
var syncLocalStorageInterval = 30000;
var consoleLogging = true;                                          // if true, log to the console

/**
 *
 * The persistentStorage function contains the functions necessary
 * to read from and save to the localStorage.dat file in the documents
 * directory.
 *
 */
var persistentStorage = function()
{
    // Get self so we don't have to be funny when a timeout calls us...
    var self = this;

    /**
     * Called when the filesystem is successfully returned. Will attempt to get "localStorage.dat"
     * access (and create it if necesssary).
     */
    self.gotFStoWrite = function (fileSystem)
    {
        fileSystem.root.getFile("localStorage.dat", {create: true, exclusive: false}, self.gotFileEntrytoWrite, self.fail);
    }

    /**
     *
     * Called when the filesystem is successfully returned. It will attempt to open "localStorage.dat" for
     * read-only access.
     */
    self.gotFStoRead = function (fileSystem)
    {
        fileSystem.root.getFile("localStorage.dat", null, self.gotFileEntrytoRead, self.fail);
    }

    /**
     *
     * Called when localStorage.dat is obtained for writing. It will create a fileWriter
     * which will actually write the contents of localStorage.
     */
    self.gotFileEntrytoWrite = function (fileEntry)
    {
        fileEntry.createWriter (self.gotFileWriter, self.fail);
    }

    /**
     *
     * Called when localStorage.dat is obtained for reading. It will create a fileReader
     * which will read the contents of the file into localStorage.
     */
    self.gotFileEntrytoRead = function (fileEntry)
    {
        fileEntry.file (self.gotFileReader, self.fail);
    }

    /**
     *
     * Called when the file localStorage.dat is successfully opened for reading.
     * Parses the file by splitting it into key/value pairs, and then splitting
     * those pairs into the key and the value. It then saves them to localStorage
     * using localStorage.setItem().
     *
     * NOTE: localStorage is /not/ cleared when this file is loaded.
     */
    self.gotFileReader = function (file)
    {
        var reader = new FileReader();
        reader.onloadend = function (evt) {
            if (consoleLogging) { console.log ("Syncing localStorage from persistent store."); }
            var ls = evt.target.result.split("[EOK]");
            for (var i=0;i<ls.length;i++)
            {
                var kv = ls[i].split("[EQ]");
                localStorage.setItem ( kv[0], kv[1] );
            }
            if (consoleLogging) { console.log ("Sync complete."); }
            if (self.readCallback)
            {
                self.readCallback();
            }
        };
        reader.readAsText (file);
    }

    /**
     *
     * Called when localStorage.dat is open for writing and created if necessary.
     * Writes out each value in localStorage as a key/value pair.
     */
    self.gotFileWriter = function (writer)
    {
        if (consoleLogging) { console.log ("Syncing localStorage to persistent store."); }

        var s = "";

        for (var i=0; i<localStorage.length; i++)
        {
            var key = localStorage.key(i);
            var value = localStorage[key];
            s = s + key + "[EQ]" + value + "[EOK]";
        }
        writer.write ( s );

        if (consoleLogging) { console.log ("Sync Complete."); }

        if (self.writeCallback)
        {
            self.writeCallback();
        }
    }

    /**
     *
     * If an error should occur during a read or write operation,
     * we will display the error. If a readCallback() is defined,
     * call it.
     */
    self.fail = function (error)
    {
        console.log ("Error: " + error.code);
            if (self.readCallback)
            {
                self.readCallback();
            }
    }

    /**
     *
     * Kicks off a save operation. If callback is specified,
     * it is called when the save operation is complete.
     */
    self.write = function ( callback )
    {
        if (callback)
        {
            self.writeCallback = callback;
        }
        window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, self.gotFStoWrite, self.fail);
    }

    /**
     *
     * Kicks off a read operation. if callback is defined,
     * it is called when the operation is complete OR a read error
     * occurs.
     */
    self.read = function( callback )
    {
        if (callback)
        {
            self.readCallback = callback;
        }
        window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, self.gotFStoRead, self.fail);
    }
}

/**
 *
 * Saves localStorage to the persistent store in localStorage.dat in the documents folder.
 *
 * If callback is defined, it is executed when the save operation is complete. If
 * syncLocalStorageInterval is greater than zero, a timeout is created in order to
 * call saveLocalStorage again, essentially creating a repeating save.
 */
function saveLocalStorage( callback )
{
    var self = this;
    var o = new persistentStorage();
    self.callback = callback;
    o.write(function()
            {
                if (syncLocalStorageInterval>0)
                {
                    setTimeout (saveLocalStorage, syncLocalStorageInterval);
                }
                if (self.callback) { self.callback(); self.callback = null; }
            });

}

/**
 *
 * Loads the localStorage data from the Documents/localStorage.dat file.
 *
 * If callback is defined, it is called after the load is complete or an
 * error occurs.
 */
function loadLocalStorage( callback )
{
    var o = new persistentStorage();
    o.read( callback );
}

/**
 *
 * This one kicks everything off. It calls loadLocalStorage to load the
 * localStorage data from the persistent store, and then, if syncLocalStorageInterval
 * is greater than zero, sets up the next save operation.
 *
 * If callback is defined, it is called after the read is complete or an
 * error occurs. Useful for defining when the application should start (as it should
 * load the store completely before beginning.)
 */
function loadLocalStorageAndSync( callback )
{
    var self = this;
    self.callback = callback;

    loadLocalStorage(function()
                     {
                        if (syncLocalStorageInterval>0)
                        {
                            setTimeout (saveLocalStorage, syncLocalStorageInterval);
                        }
                        if (self.callback) { self.callback(); self.callback = null; }
                     });
}

// to kick start it, just do: (we give 500ms for the filesystem to become ready)
// startApp below is the name of your startup routines.
        setTimeout (function()
                    {
                       loadLocalStorageAndSync ( startApp ); // start the app after we load the settings!
                    }, 500); // kick off a load in 500ms

//
// If you want to manage saving manually (instead of every 30s), do this:
syncLocalStorageInterval = 0;          // turn off periodic save
...
localStorage.setItem ("Key", "Value"); // save something to localStorage
saveLocalStorage();                    // save localStorage to persistent storage