Local Storage Ivano Malavolta Ivano Malavolta [email protected] http://www.di.univaq.it/malavolta 

Roadmap • Introduction • Web Storage • Web Storage • WebSQL • IndexedDB • File System Access • Final Considerations • Final Considerations 

Introduction There are 4 ways to store data locally • Web Web Web Web storage storage storage storage – Local Local Local Local Storage Storage Storage Storage – Session Session Session Session Storage Storage Storage Storage • WebSQL WebSQL WebSQL WebSQL • Indexed Indexed Indexed Indexed DB DB DB DB • File System Access File System Access File System Access File System Access 

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

Introduction WebSQL WebSQL WebSQL WebSQL Database Database Database Database relational DB relational DB support for tables creation, insert, update, … transactional persists across browser sessions Its evolution is called IndexedDB IndexedDB IndexedDB IndexedDB, but it is actually not supported by most mobile browsers 

Introduction File System Access File System Access File System Access File System Access you can access files locally to your app you can access files locally to your app supports main FS operations – files creation, move, delete, rename, creation, etc. it is not transactional persists across browser sessions 

Introduction Mobile browsers compatibility matrix 

Roadmap • Introduction • Web Storage • Web Storage • WebSQL • IndexedDB • File System Access • Final Considerations • Final Considerations 

Web Storage It is based on a single persistent object called localStorage 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 localStorage.key(0) Returns the name of the key at the position specified 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(“hey”) Removes the item identified by it's key clear() Removes all of the key value pairs 

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

Example of JSON Serialization // simple class declaration function Person(name, surname) { this.name = name; this.name = name; this.surname = surname; } // object creation var user = new Person(‘Ivano’, ‘Malavolta’); // object serialization window.localStorage.setItem(“user”, JSON.stringify(user)); 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 // 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 = []; var ivanos = []; for(var i=0; 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 Storage you can call the same methods but Session Storage is cleared between app launches Session Storage is cleared between app launches Session Storage is cleared between app launches Session Storage is cleared between app launches 

Roadmap • Introduction • Web Storage • Web Storage • WebSQL • IndexedDB • File System Access • Final Considerations • Final Considerations 

WebSQL It provides you a structured SQL relational database SQL relational database SQL relational database SQL relational database You have to setup a DB schema DB schema DB schema DB schema You can then perform classical classical classical classical SQL SQL SQL SQL queries queries queries queries tx.executeSql("SELECT * FROM User“, [], 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 SQLLite DB and returns a new Database Database Database Database object Database Database Database Database object The Database object will be used to manipulate the data 

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

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

Transactions It allow you to execute SQL statements against the DB db.transaction(queries, error, success); 3 callback functions: queries queries queries queries : contains the queries to be performed queries queries queries queries : contains the queries to be performed error error error error : executed if the transaction results in an error success success success 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 executeSql executeSql executeSql method multiple times function populateDB(tx) { tx.executeSql('DROP TABLE IF EXISTS USER'); 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 SQLResultSet SQLResultSet SQLResultSet parameter parameter parameter parameter It has 3 properties: insertId insertId insertId insertId the ID of the row that has been inserted rowsAffected rowsAffected rowsAffected rowsAffected the number of rows changed by the SQL statement rows rows rows 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) tx.executeSql('INSERT INTO USER(id, name,surname) VALUES (1, ?, ?)‘, [“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) item(index) returns the row at the specified index represented by a JavaScript object 

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

Errors It contains information about an occurred error code code code code A predefined error code es. UNKNOWN_ERR, DATABASE_ERR, TOO_LARGE_ERR, QUOTA_ERR, SYNTAX_ERR, TIMEOUT_ERR message message message message A description of the error 

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

Roadmap • Introduction • Web Storage • Web Storage • WebSQL • IndexedDB • File System Access • Final Considerations • Final Considerations 

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

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

Roadmap • Introduction • Web Storage • Web Storage • WebSQL • IndexedDB • File System Access • Final Considerations • Final Considerations 

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

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

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

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

Local File System Example window.requestFileSystem( LocalFileSystem.PERSISTENT, LocalFileSystem.PERSISTENT, 0, onSuccess, onError); function onSuccess(fileSystem) { console.log(fileSystem.name); console.log(fileSystem.name); } 

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

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

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

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

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

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

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

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

Directory Entry Methods getMetadata getMetadata getMetadata getMetadata(success, fail) (success, fail) (success, fail) (success, fail) Look up metadata about a directory Look up metadata about a directory moveTo moveTo moveTo moveTo( ( ( (parentEntry parentEntry parentEntry parentEntry, , , , newName newName newName newName, success, fail) , success, fail) , success, fail) , success, fail) Move a directory to a different location on the file system copyTo copyTo copyTo copyTo( ( ( (parentEntry parentEntry parentEntry parentEntry, , , , newName newName newName newName, success, fail) , success, fail) , success, fail) , success, fail) Copy a directory to a different location on the file system Copy a directory to a different location on the file system toURI toURI toURI toURI() () () () Return a URI that can be used to locate a directory 

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

Directory Entry Methods getFile getFile getFile getFile(path, options, success, fail) (path, options, success, fail) (path, options, success, fail) (path, options, success, fail) Create or look up a file within the directory Create or look up a file within the directory options: create (true | false) exclusive (true | false) removeRecursively removeRecursively removeRecursively removeRecursively(success, fail) (success, fail) (success, fail) (success, fail) removeRecursively removeRecursively removeRecursively removeRecursively(success, fail) (success, fail) (success, fail) (success, fail) Delete a directory and all of its contents 

File Reader It is used to read the contents of a file Files can be read as text or as a base64 data encoded string You can also abort() e file 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(); // reader.abort(); }; function fail(evt) { console.log(error.code); }; 

File Writer It is used to write to a file The data to be written must be UTF UTF UTF UTF- - - -8 encoded 8 encoded 8 encoded 8 encoded You can register your own event listeners to receive 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 for a single file for a single file 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() abort() abort() abort() Aborts writing file Aborts writing file seek(byte) seek(byte) seek(byte) seek(byte) Moves the file pointer to the byte specified. truncate(length) truncate(length) truncate(length) truncate(length) Shortens the file to the length specified. Shortens the file to the length specified. write(data) write(data) write(data) 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) { function fail(evt) { // error management }; 

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

Directory Reader Example var directoryReader = dirEntry.createReader(); directoryReader.readEntries(success, fail); directoryReader.readEntries(success, fail); function success(entries) { var i; for (i=0; i

A Final Example: Looking for a file and reading it 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) { function read(file) { var reader = new FileReader(); reader.onloadend = function(e) { console.log(this.result); }; reader.readAsText(file); } function error(err) { console.log(err);} 

Roadmap • Introduction • Web Storage • Web Storage • WebSQL • IndexedDB • File System Access • Final Considerations • Final Considerations 

Final Considerations You will likely use all of them in combination Use the right API for the right job Web Web Web Web Storage Storage Storage Storage • it is not transactional race conditions • very simple API, no schema • 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 • 5Mb quota 

Final Considerations WebSQL WebSQL WebSQL WebSQL • SQL-based fast and efficient • SQL-based fast and efficient • transactional more robust • asynchronous does not block the UI • rigid data structure data integrity vs agility • 5Mb quota • 5Mb quota 

Final Considerations IndexedDB IndexedDB IndexedDB IndexedDB • simple data model easy to use • simple data model easy to use • transactional more robust • asynchronous does not block the UI • good search performance indexed data • data is unstructured integrity problems • data is unstructured integrity problems • 5Mb quota 

Final Considerations File System File System File System File System • asynchronous does not block the UI • asynchronous does not block the UI • not transactional • indexing and search are not built-in you have to implement your lookup functions • unlimited storage – useful for images, videos, documents, etc. 

References http://docs.phonegap.com/en/1.7.0/