MozillaWiki

Labs/Jetpack/JEP/11: Difference between revisions

Page Discussion

Labs/Jetpack/JEP/11 (view source)

Revision as of 19:53, 1 July 2009

7,761 bytes added ,  1 July 2009
Big changes to reflect bug 499871
(propose API for checking for the existence of values)
(Big changes to reflect bug 499871)
Line 4: Line 4:


* Author: Atul Varma <atul at mozilla dot com>
* Author: Atul Varma <atul at mozilla dot com>
* Champion: Atul Varma <atul at mozilla dot com>
* Editors: Drew Willcoxon <adw at mozilla dot com>
* Status: Draft
* Champion: Atul Varma
* Status: Implementing
* Type: API Track
* Type: API Track
* Created: 27 May 2009
* Created: 27 May 2009
* Reference Implementation: None
* Reference Implementation: None
* Relevant Bugs: {{bug|496694}}, {{bug|499871}}
* [[Labs/Jetpack/JEPs|JEP Index]]
* [[Labs/Jetpack/JEPs|JEP Index]]


Line 23: Line 25:
=== Proposal ===
=== Proposal ===


Persistent storage will live at <code>jetpack.storage.simple</code>. The <code>jetpack.storage</code> namespace will provide access to any other available storage systems, such as sqlite, secure/password storage, and so on.  The current <code>jetpack.sessionStorage</code> 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 <code>jetpack.storage.session</code>.
Persistent storage will live at <code>jetpack.storage.simple</code>. The <code>jetpack.storage</code> namespace will provide access to any other available storage systems, such as SQLite, secure/password storage, and so on.  The current <code>jetpack.sessionStorage</code> 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 <code>jetpack.storage.session</code>.


==== Callbacks ====
==== Callbacks ====
Line 31: Line 33:
In this proposal, <code>onResult</code> refers to either the function form or the <code>object.onResult</code> form.  Since there is only one form for errors, <code>onError</code> refers to the <code>object.onError</code> form.
In this proposal, <code>onResult</code> refers to either the function form or the <code>object.onResult</code> form.  Since there is only one form for errors, <code>onError</code> refers to the <code>object.onError</code> form.


<code>onResult</code> is called when the callback's associated asynchronous operation successfully completes:
The arguments passed to <code>onResult</code> and <code>onError</code> depend on the API method to which the callback is passed.  Each method's description below indicates how it calls its callback.
 
Callbacks are optional, but callers should never assume that an operation completes successfully if it is important that it actually does so.
 
==== Storing a Single Item ====


<pre class="brush:js;toolbar:false;">
<pre class="brush:js;toolbar:false;">
onResult(key, [value])
jetpack.storage.simple.set(key, value, callback)
</pre>
</pre>


<code>onError</code> is called when an error occurs during the operation:
''Arguments''
 
<code>key</code>: A string uniquely identifying the data to be placed into persistent storage.
 
<code>value</code>: 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 <code>key</code> is already being stored, it is overwritten by <code>value</code>. If <code>value</code> is <code>undefined</code>, this method is equivalent to <code>jetpack.storage.simple.remove</code>.
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(key, value)</code>
* <code>onError(errorMessage, key, value)</code>
 
''Return value''
 
This method has no return value.
 
==== Storing Multiple Items ====


<pre class="brush:js;toolbar:false;">
<pre class="brush:js;toolbar:false;">
onError(key, [value,] errorMessage)
jetpack.storage.simple.set(itemsObject, callback)
</pre>
</pre>


The definitions of <code>key</code> and <code>value</code> vary according to the simple storage operation associated with the callback, and depending on the context <code>value</code> may not be passed at all.  Details follow in the sections below.
''Arguments''
 
<code>itemsObject</code>: An object whose properties and their values identify the data to be placed into persistent storage.  As in the single item form of this method, if some other data with a given key is already being stored, it is overwritten by the value in <code>itemsObject</code>.  If a given value is <code>undefined</code>, its key is removed from the store.
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(itemsObject)</code>
* <code>onError(errorMessage, itemsObject)</code>


Callbacks are optional, but callers should never assume that an operation completes successfully if it is important that it actually does so.
''Return value''
 
This method has no return value.


==== Storing Values ====
==== Retrieving a Single Item ====


<pre class="brush:js;toolbar:false;">
<pre class="brush:js;toolbar:false;">
jetpack.storage.simple.set(key, value, callback)
jetpack.storage.simple.get(key, callback)
</pre>
</pre>


''Arguments''
''Arguments''


<code>key</code>: A string uniquely identifying the data to be placed into persistent storage, or an object whose properties and their values identify the data to place into persistent storage.  If <code>key</code> is not a string or an object, an exception is thrown.
<code>key</code>: A string uniquely identifying the data to be retrieved from persistent storage.


<code>value</code>: A JS primitive or JSON-able JS object that represents the data to be stored in persistent storage. If <code>key</code> is an object, this argument is ignored. If some other data with the given <code>key</code> is already being stored, it is overwritten by <code>value</code>. If <code>value</code> is not a JS primitive or a JSON-able JS object, an exception is thrown.
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:


<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> will be passed <code>key</code> and <code>value</code>.
* <code>onResult(key, value)</code>
** <code>value</code> is <code>key</code>'s associated data.
** If <code>key</code> does not exist in the store, <code>value</code> is <code>undefined</code>.
* <code>onError(errorMessage, key)</code>


''Return value''
''Return value''


This function has no return value.
This method has no return value.


==== Retrieving Values ====
==== Retrieving Multiple Items ====


<pre class="brush:js;toolbar:false;">
<pre class="brush:js;toolbar:false;">
jetpack.storage.simple.get(key, callback)
jetpack.storage.simple.get(keyArray, callback)
</pre>
</pre>


''Arguments''
''Arguments''


<code>key</code>: A string uniquely identifying the data to be retrieved from persistent storage, or an array of such keys. If <code>key</code> is not a string or array of strings, an exception is thrown.
<code>keyArray</code>: An array of strings, each of which uniquely identifies data to be retrieved from persistent storage.
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(itemsObject)</code>
** The properties and values of <code>itemsObject</code> are the key-value pairs corresponding to the keys in <code>keyArray</code>.
** If a key does not exist in the store, its associated value in <code>itemsObject</code> is <code>undefined</code>.
* <code>onError(errorMessage, keyArray)</code>
 
''Return value''
 
This method has no return value.
 
==== Retrieving All Items ====
 
<pre class="brush:js;toolbar:false;">
jetpack.storage.simple.get(callback)
</pre>


<code>callback</code>: A callback.
''Arguments''


If <code>key</code> is a string, <code>onResult</code> will be passed <code>key</code> and a value.  If <code>key</code> exists in the store, then the value will be <code>key</code>'s associated data.  If no such key exists, then the value will be <code>undefined</code>.  <code>onError</code> will be passed only <code>key</code>.
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:


If <code>key</code> is an array of strings, <code>onResult</code> will be passed <code>key</code> and an array of the values of the keys.  For each key in <code>key</code>, if the key exists in the store, then the value of the element at the corresponding index in the array of values will be the key's associated data.  If no such key exists, then the value will be <code>undefined</code>. <code>onError</code> will be passed only <code>key</code>.
* <code>onResult(allItemsObject)</code>
** The properties and values of <code>allItemsObject</code> are all of the key-value pairs in the store.
* <code>onError(errorMessage)</code>


''Return value''
''Return value''


This function has no return value.
This method has no return value.


==== Removing Values ====
==== Removing a Single Item ====


<pre class="brush:js;toolbar:false;">
<pre class="brush:js;toolbar:false;">
Line 95: Line 147:
''Arguments''
''Arguments''


<code>key</code>: The string uniquely identifying the data to be removed from persistent storage, or an array of such strings.  If <code>key</code> is not a string or an array, an exception is thrown.
<code>key</code>: The string uniquely identifying the data to be removed from persistent storage.


<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> will be passed only <code>key</code>.
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(key)</code>
* <code>onError(errorMessage, key)</code>


''Return value''
''Return value''


This function has no return value.
This method has no return value.


==== Checking For the Existence of Values ====
==== Removing Multiple Items ====
 
<pre class="brush:js;toolbar:false;">
jetpack.storage.simple.remove(keyArray, callback)
</pre>
 
''Arguments''
 
<code>key</code>: An array of strings, each of which uniquely identifies data to be removed from persistent storage.
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(keyArray)</code>
* <code>onError(errorMessage, keyArray)</code>
 
''Return value''
 
This method has no return value.
 
==== Removing All Items ====
 
<pre class="brush:js;toolbar:false;">
jetpack.storage.simple.clear(callback)
</pre>
 
''Arguments''
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult()</code>
* <code>onError(errorMessage)</code>
 
''Return value''
 
This method has no return value.
 
==== Testing the Existence of a Single Item ====


<pre class="brush:js;toolbar:false;">
<pre class="brush:js;toolbar:false;">
Line 111: Line 202:
''Arguments''
''Arguments''


<code>key</code>: A string uniquely identifying the data whose existence in persistent storage is to be checked, or an array of such keys. If <code>key</code> is not a string or array of strings, an exception is thrown.
<code>key</code>: A string uniquely identifying the data whose existence in persistent storage is to be checked.
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(key, exists)</code>
** <code>exists</code> is <code>true</code> if <code>key</code> exists in the store and <code>false</code> otherwise.
* <code>onError(errorMessage, key)</code>
 
''Return value''
 
This method has no return value.
 
==== Testing the Existence of Multiple Items ====
 
<pre class="brush:js;toolbar:false;">
jetpack.storage.simple.has(keyArray, callback)
</pre>
 
''Arguments''
 
<code>keyArray</code>: An array of strings, each of which uniquely identifies data whose existence in persistent storage is to be checked.
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(keyArray, existsObject)</code>
** <code>existsObject</code> is a JS object whose properties map to the keys in <code>keyArray</code> and whose values are <code>true</code> if their associated keys exist and <code>false</code> otherwise.
* <code>onError(errorMessage, keyArray)</code>
 
''Return value''
 
This method has no return value.
 
==== Enumerating Specific Items ====
 
<pre class="brush:js;toolbar:false;">
jetpack.storage.simple.forEachItem(keyArray, callback)
</pre>
 
''Arguments''
 
<code>keyArray</code>: An array of strings, each of which uniquely identifies data to retrieve from the store.
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(key, value)</code>
** <code>onResult(key, value)</code> is called for each key given in <code>keyArray</code>.  If a given key does not exist in the store, <code>value</code> will be <code>undefined</code>. Items are enumerated in the same order that their keys are given in <code>keyArray</code>.
* <code>onResult(null, null)</code>
** When all items are exhausted, <code>onResult(null, null)</code> is called to signal that enumeration is complete.
* <code>onError(errorMessage, keyArray)</code>
 
''Return value''


<code>callback</code>: A callback.  
This method has no return value.


If <code>key</code> is a string, <code>onResult</code> will be passed <code>key</code> and a boolean value.  If <code>key</code> exists in the store, then the value will be <code>true</code>.  If no such key exists, then the value will be <code>false</code>.  <code>onError</code> will be passed only <code>key</code>.
==== Enumerating All Items ====


If <code>key</code> is an array of strings, <code>onResult</code> will be passed <code>key</code> and an array of boolean values.  For each key in <code>key</code>, if the key exists in the store, then the value of the element at the corresponding index in the array of values will be <code>true</code>.  If no such key exists, then the value will be <code>false</code>. <code>onError</code> will be passed only <code>key</code>.
<pre class="brush:js;toolbar:false;">
jetpack.storage.simple.forEachItem(callback)
</pre>
 
''Arguments''
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(key, value)</code>
** <code>onResult(key, value)</code> is called for each key-value pair in the store.  The order of enumeration is arbitrary.
* <code>onResult(null, null)</code>
** When all items are exhausted, <code>onResult(null, null)</code> is called to signal that enumeration is complete.
* <code>onError(errorMessage)</code>


''Return value''
''Return value''


This function has no return value.
This method has no return value.
 
==== Enumerating Keys ====
 
<pre class="brush:js;toolbar:false;">
jetpack.storage.simple.forEachKey(callback)
</pre>
 
''Arguments''
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(key)</code>
** <code>onResult(key)</code> is called for each key in the store.  The order of enumeration is arbitrary.
* <code>onResult(null)</code>
** When all keys are exhausted, <code>onResult(null)</code> is called to signal that enumeration is complete.
* <code>onError(errorMessage)</code>
 
''Return value''
 
This method has no return value.
 
==== Enumerating Specific Values ====
 
<pre class="brush:js;toolbar:false;">
jetpack.storage.simple.forEachValue(keyArray, callback)
</pre>
 
''Arguments''
 
<code>keyArray</code>: An array of strings, each of which uniquely identifies data to retrieve from the store.
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(value)</code>
** <code>onResult(value)</code> is called for each key given in <code>keyArray</code>.  If a given key does not exist in the store, <code>value</code> will be <code>undefined</code>.  Values are enumerated in the same order that their keys are given in <code>keyArray</code>.
* <code>onResult(null)</code>
** When all values are exhausted, <code>onResult(null)</code> is called to signal that enumeration is complete.
* <code>onError(errorMessage, keyArray)</code>
 
''Return value''
 
This method has no return value.
 
==== Enumerating All Values ====
 
<pre class="brush:js;toolbar:false;">
jetpack.storage.simple.forEachValue(callback)
</pre>
 
''Arguments''
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(value)</code>
** <code>onResult(value)</code> is called for each value in the store.  The order of enumeration is arbitrary.
* <code>onResult(null)</code>
** When all values are exhausted, <code>onResult(null)</code> is called to signal that enumeration is complete.
* <code>onError(errorMessage)</code>
 
''Return value''
 
This method has no return value.
 
==== Retrieving All Keys ====
 
<pre class="brush:js;toolbar:false;">
jetpack.storage.simple.keys(callback)
</pre>
 
''Arguments''
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(keyArray)</code>
** <code>keyArray</code> contains all the keys of the store in an unordered array.
* <code>onError(errorMessage)</code>
 
''Return value''
 
This method has no return value.
 
==== Retrieving All Values ====
 
<pre class="brush:js;toolbar:false;">
jetpack.storage.simple.values(callback)
</pre>
 
''Arguments''
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(valueArray)</code>
** <code>valueArray</code> contains all the values of the store in an unordered array.
* <code>onError(errorMessage)</code>
 
''Return value''
 
This method has no return value.
 
==== Retrieving the Number of Items ====
 
<pre class="brush:js;toolbar:false;">
jetpack.storage.simple.size(callback)
</pre>
 
''Arguments''
 
<code>callback</code>: A callback. <code>onResult</code> and <code>onError</code> are called as follows:
 
* <code>onResult(numItems)</code>
** <code>numItems</code> is the number of key-value pairs in the store.
* <code>onError(errorMessage)</code>
 
''Return value''
 
This method has no return value.
 
==== Errors and Legal Keys and Values ====
 
A key must be a string.  The empty string is a legal key.  If an illegal key is passed to any method, that method will throw an <code>IllegalKeyError</code>.  The prototype of <code>IllegalKeyError</code> is <code>TypeError</code>.
 
A value must be a non-null JS primitive or JSON-able object.  If an illegal value is passed to any method, that method will throw an <code>IllegalValueError</code>.  The prototype of <code>IllegalValueError</code> is <code>TypeError</code>.
 
Because of the polymorphic nature of this API, if any method is passed an unexpected argument, that method will throw an <code>ArgumentError</code>.  The prototype of <code>ArgumentError</code> is <code>TypeError</code>.


==== Other Notes ====
==== Other Notes ====
Adw
Confirmed users
764

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/153062"