Local data storage for mobile apps

Gran Sasso Science Institute
Ivano Malavolta
Local Storage

Roadmap
Introduction
Web Storage
WebSQL
IndexedDB
File System Access
Final Considerations

Local storage and file system access
There are 4 ways to store data locally in Cordova:
•  Web storage
•  Local Storage
•  Session Storage
•  WebSQL
•  Indexed DB
•  File System Access
Web storage, WebSQL, and
IndexedDB conform to W3C
specifications and are provided
by the browser itself
File system access API conforms to its
corresponding W3C specification

Web Storage
LocalStorage
stores data in key/value pairs
persists across browser sessions
SessionStorage
stores data in key/value pairs
data is erased when a browser session ends

WebSQL
relational DB
support for tables creation, insert, update, …
transactional
persists across browser sessions

WebSQL
It provides you a structured SQL relational database
You have to setup a DB schema
You can then perform classical SQL queries
tx.executeSql(‘SELECT
*
FROM
User’,
[],

function(tx,
result)
{

//
callback
code

});

IndexedDB
•  It combines Web Storage and WebSQL
•  You can save data as key/value pairs
•  You can deﬁne multiple DBs
•  Good Performance
–  data is indexed
–  Asynchronous à it does not block the UI
You can see a store as a big SQL table with only key/value pairs
à you don’t need to deﬁne a schema upfront

File System
•  you can access ﬁles locally to your app
•  supports main FS operation
–  creation, move, delete, rename, etc.
•  it is not transactional
•  persists across browser sessions

Web Storage
It is based on a single persistent object called
localStorage
You can set values by calling
window.localStorage.setItem(“name”, “Ivano”);
You can get values back by calling
var name = window.localStorage.getItem(“name”);

Supported Methods
.key(0)
Returns the name of the key at the position specified
.getItem(“key”)
Returns the item identified by it's key
.setItem(“key”, “value”)
Saves and item at the key provided
.removeItem(“key”)
Removes the item identified by it's key
.clear()
Removes all the key-value pairs

Complex Objects
Current implementations support only string-to-string mappings
à  you can store only strings
à  keys can be only strings
You can use JSON serialization if you need to store complex data
structures

Example of JSON Serialization
// simple class declaration
function Person(name, surname) {
this.name = name;
this.surname = surname;
}
// object creation
var user = new Person(‘Ivano’, ‘Malavolta’);
// object serialization
window.localStorage.setItem(“user”, JSON.stringify(user));
// object retrieval
var current =
JSON.parse(window.localStorage.getItem(“user”));

Checking Existence
You can simply check if the needed element is == null
if (window.localStorage.getItem(“user”)) {
// there is an object in user
} else {
// the user key does not have any value
}

Selecting elements
In this case you have to manually iterate on elements
var users = [...]; // array of Person objects
window.localStorage.setItem(“users”,
JSON.stringify(users));
var allUsers =
JSON.parse(window.localStorage.getItem(“users”));
var ivanos = [];
for(var i=0; i<allUsers.length; i++) {
if(allUsers[i].name == ‘Ivano’)
ivanos.push(allUsers[i]);
}

Counting Elements
Also in this case, we have to do it manually
var usersNumber =
JSON.parse(window.localStorage.getItem(“users“)).length;

Session Storage
Session Storage provides the same interface as Local Storage
à you can call the same methods
but
Session Storage is cleared between app launches

WebSQL
It provides you a structured SQL relational database
You have to setup a DB schema
You can then perform classical SQL queries
tx.executeSql("SELECT * FROM User“, [],
function(tx, result) {
// callback code
});

Opening a DB
Done via a dedicated function
var db =
openDatabase(‘Test', ‘1.0', ‘Test DB', 100000);
It creates a new SQLite DB and returns a new Database object
The Database object will be used to manipulate the data

Opening a DB: syntax
openDatabase(name, version, displayname, size);
name
the name of the DB
version
the version of the DB
displayname
the display name of the DB
size
the size of the DB in bytes

Database
It allows to manipulate the data via 2 methods:
changeVersion
atomically verify the version number and change it
db.changeVersion("1.0", "1.1");
transaction
performs a DB transaction

Transactions
It allow you to execute SQL statements against the DB
db.transaction(queries, error, success);
3 functions as parameters:
queries : contains the queries to be performed
error : executed if the transaction results in an error
success : executed if the transaction terminates correctly

Transaction Example
http://bit.ly/JlUJde

executeSql
It is the method that performs a SQL statement
The user can build up a database transaction by calling the
executeSql method multiple times
function populateDB(tx) {
tx.executeSql('DROP TABLE IF EXISTS USER');
tx.executeSql('CREATE TABLE IF NOT EXISTS USER (id
unique, name, surname)');
tx.executeSql('INSERT INTO USER(id, name, surname)
VALUES (1, ?, ?)‘, [“Ivano“, “Malavolta“],
success, error);
}

Result Sets
When the executeSql method is called, it will invoke it's callback
with a SQLResultSet parameter
It has 3 properties:
insertId
the ID of the row that has been inserted
rowsAffected
the number of rows changed by the SQL statement
rows
the data returned from a SQL select statement
rows is an object of type SQLResultSetList

Results Sets Example
...
tx.executeSql('INSERT INTO USER(id, name,surname) VALUES
(5, ?, ?)‘, [“Ivano“, “Malavolta“], success, error);
}
function success(tx, results) {
var affected = results.rowsAffected(); // 1
}
function error(err) {
// code for managing the error
}

Result Set Lists
It contains the data returned from a SQL Select statement
length
the number of rows returned by the SQL query

item(index)
returns the row at the speciﬁed index represented by a JavaScript
object

Result Set List Example
...
tx.executeSql(‘SELECT * FROM USER‘, [], success, error);
}
function success(tx, results) {
var size = results.rows.length;
for (var i=0; i<size; i++){
console.log(results.rows.item(i).name);
}
}

Errors
It contains information about an occurred error
code
A predeﬁned error code
es. UNKNOWN_ERR,
DATABASE_ERR,
TOO_LARGE_ERR,
QUOTA_ERR,
TIMEOUT_ERR,
SYNTAX_ERR
message
A description of the error
error not considered by any other error codes
internal error of the database
the result set is too large
the db now exceeds the storage space of the app
•  the statement is not sintactically correct
•  the number of parameters does not match with
placeholders
no reasonable time to get the lock for the transition

Error Code Example
...
tx.executeSql(‘SELECT * FROM USER‘,[], success, error);
}
function error(err) {
console.log(err.code);
}

Indexed DB
It tries to combine Web Storage and WebSQL
You can save data as key/value pairs
You can deﬁne multiple DBs
Good Performance
data is indexed
asynchronous à it does not block the UI

Indexed DB
An Indexed DB is a collection of object stores
You can drop objects into the stores
You can see a store as a big SQL table with only key/value pairs
à you don’t need to deﬁne a schema upfront

IndexedDB !== mobile storage
still not fully supported by iOS

File System Access
It allows you to read, write and navigate ﬁle system hierarchies
It is fundamental for managing and storing large ﬁles and binary
content on the client-side

File System Access Workflow
1.  request file system access
–  persistent or temporary file system
2.  then you can perform CRUD operations for both files and
folders:
–  Create
–  Read
–  Update
–  Delete

Request File System
requestFileSystem(type, size, successCb, [errorCb])
type
LocalFileSystem.TEMPORARY
LocalFileSystem .PERSISTENT
size
size in bytes the app will require for storage
successCb
success callback, its argument is a FileSystem object
ErrorCb
error callback, its argument is a FileError object

Temporary VS Persistent
Temporary
the ﬁles stored by the app can be deleted at the browser’s
discretion
à no guarantee of persistence
Persistent
cannot be deleted by the browser without authorization by the
app

Local File System Example
window.requestFileSystem(
LocalFileSystem.PERSISTENT,
0,
onSuccess,
onError);
function onSuccess(fileSystem) {
console.log(fileSystem.name);
}
leave it to zero, Apache Cordova will take care of it

File System
The FileSystem object has 2 properties:
name
the name of the file system
it is unique across the list of exposed file systems
root
the DirectoryEntry object representing the root folder of the
file system

Resolving a File URI
window.resolveLocalFileSystemURI
retrieve a DirectoryEntry or FileEntry using a URI
window.resolveLocalFileSystemURI(
"file:///userImg.png", onSuccess, onError);
function onSuccess(fileEntry) {
console.log(fileEntry.name);
}

Entities
FileEntry
DirectoryEntry
File
FileReader
FileWriter
DirectoryReader
The real objects
Descriptor
Writing & Reading objects

File Entry
It represents a ﬁle on a ﬁle system
isFile (boolean)
Always true
isDirectory (boolean)
Always false
name (DOMString)
the name of the FileEntry, excluding the path
fullPath (DOMString)
the full absolute path from the root

File Entry Methods
getMetadata(success, fail)
Look up metadata about a file
setMetadata(success, fail, metadataObject)
Sets the metadata of the file
moveTo(parentEntry, newName, success, fail)
Move a file to a different location on the file system
copyTo(parentEntry, newName, success, fail)
Copy a file to a different location on the file system
toURL()
Return a URL that can be used to locate a file

File Entry Methods
remove(success, fail)
Delete a file
getParent(success, fail)
Look up the parent directory
createWriter(success, fail)
Creates a FileWriter object that can be used to write to a file
file(success, fail)
Creates a File object containing file properties

File
It contains attributes of a single file
name (DOMString)
The name of the file
fullPath (DOMString)
The full path of the file including the file name
type (DOMString)
The mime type of the file
lastModifiedDate (Date)
The last time the file was modified
size (long)
The size of the file in bytes

Directory Entry
It represents a directory on a ﬁle system
It has the same properties of FileEntry

Directory Entry Methods
getMetadata(success, fail)
Look up metadata about a directory
setMetadata(success, fail, metadataObject)
Sets the metadata of the directory
moveTo(parentEntry, newName, success, fail)
Move a directory to a different location on the ﬁle system
copyTo(parentEntry, newName, success, fail)
Copy a directory to a different location on the ﬁle system
toURL()
Return a URL that can be used to locate a directory

getParent(success, fail)
Look up the parent directory
createReader()
Creates a DirectoryReader object that can be used to read a
directory
getDirectory(path, options, success, fail)
Creates or looks up a directory
options:
create: (true | false)
exclusive: (true | false)

getFile(path, options, success, fail)
Create or look up a ﬁle within the directory
options are used when the ﬁle does not exist:
create à (true | false)
exclusive à (true | false)
removeRecursively(success, fail)
Delete a directory and all of its contents

File Reader
It is used to read the contents of a ﬁle
Files can be read as:
•  text
•  base64 data encoded string
•  binary string
•  array buffer
You can also abort() a ﬁle reading activity
You can register your own event listeners to receive the
following events:
loadstart, progress, load, loadend, error, abort

File Reader Example
entry.file(win, fail);
function win(file) {
var reader = new FileReader();
reader.onloadend = function(evt) {
console.log(evt.target.result);
};
reader.readAsText(file);
// reader.abort();
};
function fail(evt) {
console.log(error.code);
};

File Writer
It is used to write to a ﬁle
The data to be written must be UTF-8 encoded
You can register your own event listeners to receive the
following events:
writestart, progress, write, writeend, error, abort

File Writer
A FileWriter is created for a single file
You can use it to write to a file multiple times
à the FileWriter maintains the file's position and length
attributes, so you can seek and write anywhere in the file
By default, the FileWriter writes to the beginning of the file (will
overwrite existing data)
Set the optional append boolean to true in the FileWriter's
constructor to begin writing to the end of the file

File Writer Methods
abort()
Aborts writing file
seek(byte)
Moves the file pointer to the byte specified.
truncate(length)
Shortens the file to the length specified.
write(data)
Writes data to the file

File Writer Example
entry.createWriter(win, fail);
function win(writer) {
writer.onwrite = function(evt) {
console.log(“ok");
};
writer.write(“Ivano Malavolta");
};
function fail(evt) {
// error management
};

Directory Reader
It is an object that lists ﬁles and directories in a directory
It has only one method:
readEntries(success, fail)
Read the entries of the directory

Directory Reader Example
var directoryReader = dirEntry.createReader();
directoryReader.readEntries(success, fail);
function success(entries) {
var i;
for (i=0; i<entries.length; i++) {
console.log(entries[i].name);
}
}
function fail(error) {
console.log(error.code);
}

A Final Example
window.requestFileSystem(window.PERSISTENT, 0, initFS, error);
function initFS(fs) {
fs.root.getFile(‘log.txt', {}, win, error);
}
function win(fileEntry) {
fileEntry.file(read, error);
}
function read(file) {
var reader = new FileReader();
reader.onloadend = function(e) {
console.log(this.result);
};
reader.readAsText(file);
}
function error(err) { console.log(err);}
Looking for a ﬁle and reading it

File upload
Upload ﬁles to a remote server via an HTTP multi-part POST
request
var fileURI; // the path of the file on the device
var server; // encoded URL of the server
var win; // success callback
var fail; // error callback
var options; // optional parameters (see next slide)
var trustAllHosts; // optional boolean parameter,
// true to accept all security certificates
var ft = new FileTransfer();
ft.upload(fileURI, encodeURI(server), win, fail, options);

File upload options
The FileUploadOptions can be used to specify additional
parameters to the upload script
var options = new FileUploadOptions();
options.fileKey="file”;
options.fileName= “fileName”);
options.mimeType="text/plain";
…

File upload result
A FileUploadResult object is passed to the success callback
Properties:
bytesSent: the number of bytes sent to the server
responseCode: The HTTP response code returned by the server
response: The HTTP response returned by the server as string
headers: the headers of the HTTP response by the server
not supported in iOS
not supported in iOS

File download
Downloads ﬁles from a remote server via an HTTP GET request
var source; // URL of the file to be downloaded
var target; // full path of the file to be saved
var win; // success callback (takes FileEntry object)
var fail; // error callback
var options; // optional parameters (only headers)
var trustAllHosts; // optional boolean parameter,
// true to accept all security certificates
ft.download(encodeURI(source),target, win, fail, options);

File transfer abort
Used to stop an on-going ﬁle transfer
ft.upload(fileURI, encodeURI(server), win, fail, options);
// perform some operation
ft.abort():

File transfer progress
Special callback activated every time a new piece of data is
transferred
ft.onprogress = function(progress) {
if (progressEvent.lengthComputable) {
console.log((progress.loaded / progress.total) + “%”);
} else {
console.log(“progressed”);
}
};
ft.download(...); // the same works for upload

File transfer error
The FileTransferError object stores information about an error
occurred during a ﬁle transfer (either upload or download)
Properties:
code: predeﬁned error code
source: URI of the source
target: URI of the target
http_status: HTTP status code from the server (if received)
FileTransferError.FILE_NOT_FOUND_ERR
FileTransferError.INVALID_URL_ERR
FileTransferError.CONNECTION_ERR
FileTransferError.ABORT_ERR

Considerations
You will likely use more than one API in combination
à Use the right API for the right job
Web Storage
•  it is not transactional à race conditions
•  very simple API, no schema
•  only String data à performance issues for complex data due
to JSON serialization
•  session storage will be cleared after the app is closed
•  limited quota

Considerations
WebSQL
SQL-based à fast and efﬁcient
transactional à more robust
asynchronous à does not block the UI
rigid data structure à data integrity vs agility
limited quota

Considerations
IndexedDB
simple data model à easy to use
transactional à more robust
good search performance à indexed data
data is unstructured à integrity problems
limited quota
not fully supported by every platform (e.g., iOS)

Considerations
File System
not transactional
indexing and search are not built-in à you have to implement
your lookup functions
unlimited quota à useful for images, videos, documents, etc.

About quotas...
Local Storage
~ 10Mb
Session Storage
~ 10Mb
WebSQL
~ 50-80Mb (depends on
the device)
Indexed DB
~ 50-80Mb (depends on
the device)
File system
unlimited
Native DB
unlimited

Exercises
Extend the previous exercises you developed about Frascati
events so that users can:
1.  save a specific event or “ente” as favorited via local storage
2.  define a dedicated “Favorites” view of the app;
3.  define a WebSQL DB for storing events and “enti”;
–  here you can support a very limited subset of the data
4.  define a data prefetcher that at the first launch of the app
saves all the data coming from the Rest API to the WEBSQL
database;
–  in the subsequent launches of the app, the data must come from
the WebSQL database, and not from the Rest API
Data:
http://www.ivanomalavolta.com/files/data/frascatiEventi.json
http://www.ivanomalavolta.com/files/data/frascatiEnti.json

References
http://cordova.apache.org/docs/en/edge

Contact
Ivano Malavolta |
Gran Sasso Science Institute
iivanoo
ivano.malavolta@gssi.infn.it
www.ivanomalavolta.com

Local data storage for mobile apps

More Related Content

What's hot

Viewers also liked

Similar to Local data storage for mobile apps

More from Ivano Malavolta

Recently uploaded

Local data storage for mobile apps