View
186
Download
1
Category
Preview:
Citation preview
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 define 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 define a schema upfront
File System
• you can access files locally to your app
• supports main FS operation– creation, move, delete, rename, etc.
• it is not transactional
• persists across browser sessions
Roadmap
Introduction
Web Storage
WebSQL
IndexedDB
File System Access
Final Considerations
Web Storage
It is based on a single persistent object called localStorage
You can set values by callingwindow.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
Roadmap
Introduction
Web Storage
WebSQL
IndexedDB
File System Access
Final Considerations
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);
namethe name of the DB
versionthe version of the DB
displaynamethe display name of the DB
sizethe 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 specified 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 predefined error code
es. UNKNOWN_ERR,
DATABASE_ERR,
TOO_LARGE_ERR,
QUOTA_ERR,
TIMEOUT_ERR,
SYNTAX_ERR
messageA 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);
}
Roadmap
Introduction
Web Storage
WebSQL
IndexedDB
File System Access
Final Considerations
Indexed DB
It tries to combine Web Storage and WebSQL
You can save data as key/value pairs
You can define 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 define a schema upfront
IndexedDB !== mobile storage
still not fully supported by iOS
Roadmap
Introduction
Web Storage
WebSQL
IndexedDB
File System Access
Final Considerations
File System Access
It allows you to read, write and navigate file system hierarchies
It is fundamental for managing and storing large files 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.TEMPORARYLocalFileSystem .PERSISTENT
sizesize in bytes the app will require for storage
successCbsuccess callback, its argument is a FileSystem object
ErrorCberror callback, its argument is a FileError object
Temporary VS Persistent
Temporary
the files 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);
}
Important directories
Entities
FileEntry
DirectoryEntry
File
FileReader
FileWriter
DirectoryReader
The real objects
Descriptor
Writing & Reading objects
File Entry
It represents a file on a file 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 file 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 file system
copyTo(parentEntry, newName, success, fail)Copy a directory to a different location on the file system
toURL()Return a URL that can be used to locate a directory
Directory Entry Methods
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 directoryoptions: create: (true | false)exclusive: (true | false)
Directory Entry Methods
getFile(path, options, success, fail)
Create or look up a file within the directory
options are used when the file 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 file
Files can be read as:
• text
• base64 data encoded string
• binary string
• array buffer
You can also abort() a 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(); };
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-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 files 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 file and reading it
File upload
Upload files 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 options
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 files 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
var ft = new FileTransfer();
ft.download(encodeURI(source),target, win, fail, options);
File transfer abort
Used to stop an on-going file transfer
var ft = new FileTransfer(); 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 file transfer (either upload or download)
Properties:
code: predefined 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_ERRFileTransferError.INVALID_URL_ERRFileTransferError.CONNECTION_ERRFileTransferError.ABORT_ERR
Roadmap
Introduction
Web Storage
WebSQL
IndexedDB
File System Access
Final Considerations
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 efficient
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
asynchronous à does not block the UI
good search performance à indexed data
data is unstructured à integrity problems
limited quota
not fully supported by every platform (e.g., iOS)
Considerations
File System
asynchronous à does not block the UI
not transactional
indexing and search are not built-in à you have to implement your lookup functions
unlimited quota à useful for images, videos, documents, etc.
Platforms support
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.jsonhttp://www.ivanomalavolta.com/files/data/frascatiEnti.json
References
http://cordova.apache.org/docs/en/edge
ContactIvano Malavolta |
Gran Sasso Science Institute
iivanoo
ivano.malavolta@gssi.infn.it
www.ivanomalavolta.com
Recommended