577
edits
Labs/Jetpack/JEP/11: Difference between revisions
Jump to navigation
Jump to search
Reverted my changes on async vs. sync
(Reverted my changes on async vs. sync) |
|||
| Line 25: | Line 25: | ||
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 ==== | ||
Because of the asynchronous nature of this API, its operations communicate their statuses and results to callers via callbacks. In the context of simple storage, a callback is either a function or an object that defines the methods <code>onResult</code> and <code>onError</code>. If a callback is a function, it is called when its associated asynchronous operation successfully completes. If a callback is an object, its <code>onResult</code> method (if defined) is called when the operation successfully completes, and its <code>onError</code> method (if defined) is called when an error occurs during the operation. This allows callers to provide a simple function in the common case; only if callers wish to be notified of errors do they need to use the more verbose object 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: | |||
<pre class="brush:js;toolbar:false;"> | |||
onResult(key, [value]) | |||
</pre> | |||
<code>onError</code> is called when an error occurs during the operation: | |||
<pre class="brush:js;toolbar:false;"> | |||
onError(key, [value,] errorMessage) | |||
</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. | |||
Callbacks are optional, but callers should never assume that an operation completes successfully if it is important that it actually does so. | |||
==== Storing Values ==== | ==== Storing Values ==== | ||
| Line 48: | Line 64: | ||
This function has no return value. | This function has no return value. | ||
==== Retrieving Values ==== | ==== Retrieving Values ==== | ||