|
THIS PAGE IS A WORKING DRAFT | 
|
| The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page. |
JEP 11 - Simple Persistent Storage
- Author: Atul Varma <atul at mozilla dot com>
- Champion: Atul Varma <atul at mozilla dot com>
- Status: Draft
- Type: API Track
- Created: 27 May 2009
- Reference Implementation: None
- JEP Index
Introduction and Rationale
This JEP describes a simple mechanism through which Jetpacks can persistently store JS primitives and blobs of JSON data.
The API of this proposal is constrained by what is possible to implement using JavaScript 1.8, since distributing binary components with the Jetpack extension is nontrivial.
This proposal is favored over DOM Storage because the latter only supports storing strings, which forces the developer to manually perform error-prone parsing tasks for almost any kind of use case. It should also be noted that the simple storage outlined in this proposal can be implemented on the web using DOM Storage; as such, this proposal should not be considered "breaking the web".
Part of this proposal involves adding a jetpack.storage namespace.
Proposal
Persistent storage will live at jetpack.storage.simple. The jetpack.storage namespace will provide access to any other available storage systems, such as sqlite, secure/password storage, and so on. The current jetpack.sessionStorage object, which allows arbitrary JS objects (they need not be JSON-able) to be stored between reloads of a Jetpack within the same Firefox session, will be renamed to jetpack.storage.session.
Storing Values
jetpack.storage.simple.set(key, value)
Arguments
key: A string uniquely identifying the data to be placed in persistent storage.
value: A JS primitive or JSON-able JS object that represents the data to be stored in persistent storage. If some other data with the given key is already being stored, it is overwritten by value.
Return value
This function has no return value.
Retrieving Values
jetpack.storage.simple.get(key)
Arguments
key: A string uniquely identifying the data to be retrieved from persistent storage.
Return value
A JS primitive or JSON-able JS object that represents the corresponding value for key. If no such value exists, undefined is returned.
Removing Values
jetpack.storage.simple.remove(key)
Removes the key and its associated data from persistent storage. Calling jetpack.storage.simple.remove(key) is the same as calling jetpack.storage.simple.set(key, undefined).
Arguments
key: The string uniquely identifying the data to be removed from persistent storage.
Return value
This function has no return value.
Other Notes
Equivalence vs. Equality
The values passed into set() and returned from get() are all serialized/de-serialized at the time of calling; this means that, for instance, given the following code:
var original = {foo: 'bar'};
jetpack.storage.simple.set('test', original);
the following condition will hold:
assert(jetpack.storage.simple.get('test') != original);
Asynchronicity
In the future, it may be useful to add an optional callback parameter to every function in this API, so that Jetpacks can take advantage of storage backends which support asynchronicity (such as Asynchronous mozStorage).