[html5] r5736 - [e] (0) Purge references to Web SQL Database.
whatwg at whatwg.org
whatwg at whatwg.org
Fri Dec 31 22:33:54 PST 2010
Author: ianh
Date: 2010-12-31 22:33:52 -0800 (Fri, 31 Dec 2010)
New Revision: 5736
Modified:
complete.html
index
source
Log:
[e] (0) Purge references to Web SQL Database.
Modified: complete.html
===================================================================
--- complete.html 2011-01-01 06:20:53 UTC (rev 5735)
+++ complete.html 2011-01-01 06:33:52 UTC (rev 5736)
@@ -1023,9 +1023,8 @@
<ol>
<li><a href=#importing-scripts-and-libraries><span class=secno>9.3.1 </span>Importing scripts and libraries</a></li>
<li><a href=#the-workernavigator-object><span class=secno>9.3.2 </span>The <code>WorkerNavigator</code> object</a></li>
- <li><a href=#apis-defined-in-other-specifications><span class=secno>9.3.3 </span>APIs defined in other specifications</a></li>
- <li><a href=#interface-objects-and-constructors><span class=secno>9.3.4 </span>Interface objects and constructors</a></li>
- <li><a href=#worker-locations><span class=secno>9.3.5 </span>Worker locations</a></ol></ol></li>
+ <li><a href=#interface-objects-and-constructors><span class=secno>9.3.3 </span>Interface objects and constructors</a></li>
+ <li><a href=#worker-locations><span class=secno>9.3.4 </span>Worker locations</a></ol></ol></li>
<li><a href=#comms><span class=secno>10 </span>Communication</a>
<ol>
<li><a href=#event-definitions-0><span class=secno>10.1 </span>Event definitions</a></li>
@@ -22902,8 +22901,7 @@
<p>This flag also <a href=#sandboxCookies>prevents script from
reading from or writing to the <code title=dom-document-cookie>document.cookie</code> IDL
- attribute</a>, and blocks access to <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> and <code title=dom-opendatabase>openDatabase()</code>.
- <a href=#refsWEBSQL>[WEBSQL]</a>
+ attribute</a>, and blocks access to <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code>.
</p>
<div class=note>
@@ -61015,15 +61013,7 @@
</ol><p>This specification defines the following <dfn id=unloading-document-cleanup-steps>unloading document
cleanup steps</dfn>. Other specifications can define more.</p>
- <ol><li><p>If there are any outstanding transactions that have
- callbacks that involve <a href=#concept-script title=concept-script>scripts</a>
- whose <a href="#script's-global-object" title="script's global object">global object</a> is
- the <code><a href=#document>Document</a></code>'s <code><a href=#window>Window</a></code> object, roll them
- back (without invoking any of the callbacks) and set the
- <code><a href=#document>Document</a></code>'s <var title=concept-document-salvageable>salvageable</var> state to
- false. <a href=#refsWEBSQL>[WEBSQL]</a></li>
-
- <li><p><span>Close the WebSocket connection</span> of any
+ <ol><li><p><span>Close the WebSocket connection</span> of any
<code><a href=#websocket>WebSocket</a></code> objects that were created by the <code title=dom-WebSocket><a href=#dom-websocket>WebSocket()</a></code> constructor visible on the
<code><a href=#document>Document</a></code>'s <code><a href=#window>Window</a></code> object. If this
affected any <code><a href=#websocket>WebSocket</a></code> objects, the set
@@ -71491,16 +71481,6 @@
<li>
- <p>If there are any outstanding transactions that have callbacks
- that involve <a href=#concept-script title=concept-script>scripts</a> whose
- <a href="#script's-global-object" title="script's global object">global object</a> is the
- <var title="">worker global scope</var>, roll them back (without
- invoking any of the callbacks). <a href=#refsWEBSQL>[WEBSQL]</a></p>
-
- </li>
-
- <li>
-
<p>Empty the <var title="">worker global scope</var>'s <a href=#list-of-active-timeouts>list
of active timeouts</a> and its <a href=#list-of-active-intervals>list of active
intervals</a>.</p>
@@ -72162,16 +72142,9 @@
- <h4 id=apis-defined-in-other-specifications><span class=secno>9.3.3 </span>APIs defined in other specifications</h4>
- <p>The <code title=dom-opendatabase>openDatabase()</code> and
- <code title=dom-opendatabase-sync>openDatabaseSync()</code>
- methods are defined in the Web SQL Database specification. <a href=#refsWEBSQL>[WEBSQL]</a></p>
+ <h4 id=interface-objects-and-constructors><span class=secno>9.3.3 </span>Interface objects and constructors</h4>
-
-
- <h4 id=interface-objects-and-constructors><span class=secno>9.3.4 </span>Interface objects and constructors</h4>
-
<p>There must be no interface objects and constructors available in
the global scope of scripts whose <a href="#script's-global-object">script's global
object</a> is a <code><a href=#workerglobalscope>WorkerGlobalScope</a></code> object except for
@@ -72205,7 +72178,7 @@
visibility of interfaces annotated with the <code title="">[NoInterfaceObject]</code> extended attribute.</p>
- <h4 id=worker-locations><span class=secno>9.3.5 </span>Worker locations</h4>
+ <h4 id=worker-locations><span class=secno>9.3.4 </span>Worker locations</h4>
<pre class=idl>interface <dfn id=workerlocation>WorkerLocation</dfn> {
// <a href=#url-decomposition-idl-attributes>URL decomposition IDL attributes</a>
@@ -74723,25 +74696,11 @@
executing, other than in a way that is predictable by the script
itself.</p>
-
- </div><!--data-component-->
-
-
- <div data-component="Web Storage (editor: Ian Hickson)">
-
-
-
-
<h3 id=disk-space-0><span class=secno>11.3 </span>Disk space</h3>
<p>User agents should limit the total amount of space allowed for
-
- storage areas.
-
-
-
- </p>
+ storage areas.</p>
<p>User agents should guard against sites storing data under the
origins other affiliated sites, e.g. storing up to the limit in
@@ -74756,11 +74715,9 @@
<p>User agents should allow users to see how much space each domain
is using.</p>
-
<!--<p>If the storage area space limit is reached during a <code
title="dom-Storage-setItem">setItem()</code> call, the method will
raise an exception.</p>-->
-
<p>A mostly arbitrary limit of five megabytes per
<a href=#origin>origin</a> is recommended. Implementation feedback is
@@ -74774,18 +74731,13 @@
<p>A third-party advertiser (or any entity capable of getting
content distributed to multiple sites) could use a unique identifier
- stored in its
-
- local storage area
-
-
- to track a user across multiple sessions, building a profile of the
- user's interests to allow for highly targeted advertising. In
- conjunction with a site that is aware of the user's real identity
- (for example an e-commerce site that requires authenticated
- credentials), this could allow oppressive groups to target
- individuals with greater accuracy than in a world with purely
- anonymous Web usage.</p>
+ stored in its local storage area to track a user across multiple
+ sessions, building a profile of the user's interests to allow for
+ highly targeted advertising. In conjunction with a site that is
+ aware of the user's real identity (for example an e-commerce site
+ that requires authenticated credentials), this could allow
+ oppressive groups to target individuals with greater accuracy than
+ in a world with purely anonymous Web usage.</p>
<p>There are a number of techniques that can be used to mitigate the
risk of user tracking:</p>
@@ -74793,14 +74745,10 @@
<dl><dt>Blocking third-party storage</dt>
<dd>
- <p>User agents may restrict access to
-
- the <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> objects
-
-
- to scripts originating at the domain of the top-level document of
- the <a href=#browsing-context>browsing context</a>, for instance denying access to
- the API for pages from other domains running in
+ <p>User agents may restrict access to the <code title=dom-localStorage><a href=#dom-localstorage>localStorage</a></code> objects to scripts
+ originating at the domain of the top-level document of the
+ <a href=#browsing-context>browsing context</a>, for instance denying access to the
+ API for pages from other domains running in
<code><a href=#the-iframe-element>iframe</a></code>s.</p>
</dd>
@@ -74811,12 +74759,10 @@
<p>User agents may, if so configured by the user, automatically
delete stored data after a period of time.</p>
-
<p>For example, a user agent could be configured to treat
third-party local storage areas as session-only storage, deleting
the data once the user had closed all the <a href=#browsing-context title="browsing
context">browsing contexts</a> that could access it.</p>
-
<p>This can restrict the ability of a site to track a user, as the
site would then only be able to track the user across multiple
@@ -74828,10 +74774,8 @@
risk, if the user does not fully understand the implications of
data expiration.</p>
-
<!--v2 consider adding an explicit way for sites to state when
data should expire, as in localStorage.expireData(365); -->
-
</dd>
@@ -74839,34 +74783,22 @@
<dd>
<p>If users attempt to protect their privacy by clearing cookies
- without also clearing data stored in the
-
- local storage area,
-
-
-
- sites can defeat those attempts by using the two features as
- redundant backup for each other. User agents should present the
- interfaces for clearing these in a way that helps users to
- understand this possibility and enables them to delete data in all
- persistent storage features simultaneously. <a href=#refsCOOKIES>[COOKIES]</a></p>
+ without also clearing data stored in the local storage area, sites
+ can defeat those attempts by using the two features as redundant
+ backup for each other. User agents should present the interfaces
+ for clearing these in a way that helps users to understand this
+ possibility and enables them to delete data in all persistent
+ storage features simultaneously. <a href=#refsCOOKIES>[COOKIES]</a></p>
</dd>
- <dt>Site-specific white-listing of access to
-
- local storage areas
-
-
- </dt>
+ <dt>Site-specific white-listing of access to local storage
+ areas</dt>
<dd>
-
<p>User agents may allow sites to access session storage areas in
an unrestricted manner, but require the user to authorize access
to local storage areas.</p>
-
-
</dd>
@@ -74936,27 +74868,17 @@
from that domain. To mitigate this, pages can use TLS. Pages using
TLS can be sure that only pages using TLS that have certificates
identifying them as being from the same domain can access their
-
- storage areas.
-
-
-
- </p>
+ storage areas.</p>
<h4 id=cross-directory-attacks><span class=secno>11.5.2 </span>Cross-directory attacks</h4>
<p>Different authors sharing one host name, for example users
- hosting content on <code>geocities.com</code>, all share one
-
- local storage object.
-
-
-
- There is no feature to restrict the access by pathname. Authors on
- shared hosts are therefore recommended to avoid using these
- features, as it would be trivial for other authors to read the data
- and overwrite it.</p>
+ hosting content on <code>geocities.com</code>, all share one local
+ storage object. There is no feature to restrict the access by
+ pathname. Authors on shared hosts are therefore recommended to avoid
+ using these features, as it would be trivial for other authors to
+ read the data and overwrite it.</p>
<p class=note>Even if a path-restriction feature was made
available, the usual DOM scripting security model would make it
@@ -74989,7 +74911,6 @@
in this specification is important for user security.</p>
-
</div><!--data-component-->
@@ -93306,10 +93227,6 @@
<dd><cite><a href=http://tools.ietf.org/html/draft-nottingham-http-link-header>Web
Linking</a></cite>, M. Nottingham. IETF.</dd>
- <dt id=refsWEBSQL>[WEBSQL]</dt>
- <dd><cite><a href=http://dev.w3.org/html5/webdatabase/>Web SQL
- Database</a></cite>, I. Hickson. W3C.</dd>
-
<dt id=refsWHATWGWIKI>[WHATWGWIKI]</dt>
<dd><cite><a href=http://wiki.whatwg.org/>The WHATWG Wiki</a></cite>. WHATWG.</dd>
Modified: index
===================================================================
--- index 2011-01-01 06:20:53 UTC (rev 5735)
+++ index 2011-01-01 06:33:52 UTC (rev 5736)
@@ -1336,7 +1336,6 @@
<li><a href="http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol">WebSocket protocol</a>
-->
<li><a href=http://dev.w3.org/html5/eventsource/>Server-sent Events</a>
- <li><a href=http://dev.w3.org/html5/webdatabase/>Web SQL Database</a>
<li><a href=http://tools.ietf.org/html/draft-abarth-mime-sniff>Media Type Sniffing</a>
<li><a href=http://tools.ietf.org/html/draft-abarth-origin>The Web Origin Concept</a>
<li><a href=http://dev.w3.org/geo/api/spec-source.html>Geolocation API</a>
@@ -22881,11 +22880,10 @@
<p>This flag also <a href=#sandboxCookies>prevents script from
reading from or writing to the <code title=dom-document-cookie>document.cookie</code> IDL
- attribute</a>, and blocks access to <code title=dom-localStorage>localStorage</code> and <code title=dom-opendatabase>openDatabase()</code>.
+ attribute</a>, and blocks access to <code title=dom-localStorage>localStorage</code>.
<a href=#refsWEBSTORAGE>[WEBSTORAGE]</a>
- <a href=#refsWEBSQL>[WEBSQL]</a>
</p>
<div class=note>
@@ -60997,15 +60995,7 @@
</ol><p>This specification defines the following <dfn id=unloading-document-cleanup-steps>unloading document
cleanup steps</dfn>. Other specifications can define more.</p>
- <ol><li><p>If there are any outstanding transactions that have
- callbacks that involve <a href=#concept-script title=concept-script>scripts</a>
- whose <a href="#script's-global-object" title="script's global object">global object</a> is
- the <code><a href=#document>Document</a></code>'s <code><a href=#window>Window</a></code> object, roll them
- back (without invoking any of the callbacks) and set the
- <code><a href=#document>Document</a></code>'s <var title=concept-document-salvageable>salvageable</var> state to
- false. <a href=#refsWEBSQL>[WEBSQL]</a></li>
-
- <li><p><span>Close the WebSocket connection</span> of any
+ <ol><li><p><span>Close the WebSocket connection</span> of any
<code>WebSocket</code> objects that were created by the <code title=dom-WebSocket>WebSocket()</code> constructor visible on the
<code><a href=#document>Document</a></code>'s <code><a href=#window>Window</a></code> object. If this
affected any <code>WebSocket</code> objects, the set
@@ -89368,10 +89358,6 @@
<dd><cite><a href=http://dev.w3.org/html5/websockets/>The WebSocket
API</a></cite>, I. Hickson. W3C.</dd>
- <dt id=refsWEBSQL>[WEBSQL]</dt>
- <dd><cite><a href=http://dev.w3.org/html5/webdatabase/>Web SQL
- Database</a></cite>, I. Hickson. W3C.</dd>
-
<dt id=refsWEBSTORAGE>[WEBSTORAGE]</dt>
<dd><cite><a href=http://dev.w3.org/html5/webstorage/>Web
Storage</a></cite>, I. Hickson. W3C.</dd>
Modified: source
===================================================================
--- source 2011-01-01 06:20:53 UTC (rev 5735)
+++ source 2011-01-01 06:33:52 UTC (rev 5736)
@@ -110,7 +110,6 @@
<li><a href="http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol">WebSocket protocol</a>
-->
<li><a href="http://dev.w3.org/html5/eventsource/">Server-sent Events</a>
- <li><a href="http://dev.w3.org/html5/webdatabase/">Web SQL Database</a>
<li><a href="http://tools.ietf.org/html/draft-abarth-mime-sniff">Media Type Sniffing</a>
<li><a href="http://tools.ietf.org/html/draft-abarth-origin">The Web Origin Concept</a>
<li><a href="http://dev.w3.org/geo/api/spec-source.html">Geolocation API</a>
@@ -24538,12 +24537,10 @@
reading from or writing to the <code
title="dom-document-cookie">document.cookie</code> IDL
attribute</a>, and blocks access to <code
- title="dom-localStorage">localStorage</code> and <code
- title="dom-opendatabase">openDatabase()</code>.
+ title="dom-localStorage">localStorage</code>.
<!--END complete--><!--END epub-->
<a href="#refsWEBSTORAGE">[WEBSTORAGE]</a>
<!--START complete--><!--START epub-->
- <a href="#refsWEBSQL">[WEBSQL]</a>
</p>
<div class="note">
@@ -69343,15 +69340,6 @@
<ol>
- <li><p>If there are any outstanding transactions that have
- callbacks that involve <span title="concept-script">scripts</span>
- whose <span title="script's global object">global object</span> is
- the <code>Document</code>'s <code>Window</code> object, roll them
- back (without invoking any of the callbacks) and set the
- <code>Document</code>'s <var
- title="concept-document-salvageable">salvageable</var> state to
- false. <a href="#refsWEBSQL">[WEBSQL]</a></p></li>
-
<li><p><span>Close the WebSocket connection</span> of any
<code>WebSocket</code> objects that were created by the <code
title="dom-WebSocket">WebSocket()</code> constructor visible on the
@@ -80815,16 +80803,6 @@
<li>
- <p>If there are any outstanding transactions that have callbacks
- that involve <span title="concept-script">scripts</span> whose
- <span title="script's global object">global object</span> is the
- <var title="">worker global scope</var>, roll them back (without
- invoking any of the callbacks). <a href="#refsWEBSQL">[WEBSQL]</a></p>
-
- </li>
-
- <li>
-
<p>Empty the <var title="">worker global scope</var>'s <span>list
of active timeouts</span> and its <span>list of active
intervals</span>.</p>
@@ -81619,15 +81597,7 @@
- <h4>APIs defined in other specifications</h4>
- <p>The <code title="dom-opendatabase">openDatabase()</code> and
- <code title="dom-opendatabase-sync">openDatabaseSync()</code>
- methods are defined in the Web SQL Database specification. <a
- href="#refsWEBSQL">[WEBSQL]</a></p>
-
-
-
<h4>Interface objects and constructors</h4>
<p>There must be no interface objects and constructors available in
@@ -84059,11 +84029,6 @@
<!--END html-->
-<!--END complete--><!--END epub-->
-
- <h2 id="storage-and-database">Structured client-side storage APIs</h2>
-
-<!--START complete--><!--START epub-->
<!--FIXUP complete -1-->
<div data-component="Web Storage (editor: Ian Hickson)">
@@ -84587,1128 +84552,11 @@
executing, other than in a way that is predictable by the script
itself.</p>
- <!--END storage-->
- </div><!--data-component-->
-
- <!--END complete--><!--END epub-->
-
-
-
-
- <h3>Web SQL database</h3>
-
- <div data-component="Web Database (editor: Ian Hickson)">
-
- <!--START database-->
-
- <!-- Feature requests for future versions (v2):
- * deleting databases
- * determining how much storage room is left
- * handling the database getting corrupted
- -->
-
- <h4>Introduction</h4>
-
- <p><i>This section is non-normative.</i></p>
-
- <p>This specification introduces a set of APIs to manipulate
- client-side databases using SQL.</p>
-
- <p>The API is asynchronous, so authors are likely to find anonymous
- functions (lambdas) very useful in using this API.</p>
-
- <p>Here is an example of a script using this API. First, a function
- <code title="">prepareDatabase()</code> is defined. This function
- returns a handle to the database, first creating the database if
- necessary. The example then calls the function to do the actual
- work, in this case <code title="">showDocCount()</code>.</p>
-
- <pre>function prepareDatabase(ready, error) {
- return openDatabase('documents', '1.0', 'Offline document storage', 5*1024*1024, function (db) {
- db.changeVersion('', '1.0', function (t) {
- t.executeSql('CREATE TABLE docids (id, name)');
- }, error);
- });
-}
-
-function showDocCount(db, span) {
- db.readTransaction(function (t) {
- t.executeSql('SELECT COUNT(*) AS c FROM docids', [], function (t, r) {
- span.textContent = r.rows[0].c;
- }, function (t, e) {
- // couldn't read database
- span.textContent = '(unknown: ' + e.message + ')';
- });
- });
-}
-
-prepareDatabase(function(db) {
- // got database
- var span = document.getElementById('doc-count');
- showDocCount(db, span);
-}, function (e) {
- // error getting database
- alert(e.message);
-});</pre>
-
- <hr>
-
- <p>The <code
- title="dom-sqltransaction-executeSql">executeSql()</code> method has
- an argument intended to allow variables to be substituted into
- statements without risking SQL injection vulnerabilities:</p>
-
- <pre>db.readTransaction(function (t) {
- t.executeSql('SELECT title, author FROM docs WHERE id=?', [id], function (t, data) {
- report(data.rows[0].title, data.rows[0].author);
- });
-});</pre>
-
- <hr>
-
- <p>Sometimes, there might be an arbitrary number of variables to
- substitute in. Even in these case, the right solution is to
- construct the query using only "?" characters, and then to pass the
- variables in as the second argument:</p>
-
-<pre>function findDocs(db, resultCallback) {
- var q = "";
- for each (var i in labels)
- q += (q == "" ? "" : ", ") + "?";
- db.readTransaction(function (t) {
- t.executeSql('SELECT id FROM docs WHERE label IN (' + q + ')', labels, function (t, data) {
- resultCallback(data);
- });
- });
-}</pre>
-
- <!--BOILERPLATE middle-w3c-api-intro-->
- <!--BOILERPLATE middle-w3c-js-disclaimer-->
-
- <h4 id="sql">The API</h4>
-
- <h5>Databases</h5>
-
- <p>Each <i>origin</i> has an associated set of databases. Each
- database has a name and a current version. There is no way to
- enumerate or delete the databases available for an origin from this
- API.</p>
-
- <p class="note">Each database has one version at a time; a database
- can't exist in multiple versions at once. Versions are intended to
- allow authors to manage schema changes incrementally and
- non-destructively, and without running the risk of old code (e.g. in
- another browser window) trying to write to a database with incorrect
- assumptions.</p>
-
- <pre class="idl">[Supplemental, NoInterfaceObject]
-interface <span>WindowDatabase</span> {
- <span>Database</span> <span title="dom-opendatabase">openDatabase</span>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize, in optional <span>DatabaseCallback</span> creationCallback);
-};
-<span>Window</span> implements <span>WindowDatabase</span>;
-
-[Supplemental, NoInterfaceObject]
-interface <span>WorkerUtilsDatabase</span> {
- <span>Database</span> <span title="dom-opendatabase">openDatabase</span>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize, in optional <span>DatabaseCallback</span> creationCallback);
- <span>DatabaseSync</span> <span title="dom-opendatabase-sync">openDatabaseSync</span>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize, in optional <span>DatabaseCallback</span> creationCallback);
-};
-<span>WorkerUtils</span> implements <span>WorkerUtilsDatabase</span>;
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface <dfn>DatabaseCallback</dfn> {
- void <span title="dom-databasecallback-handleEvent">handleEvent</span>(in <span>Database</span> database);
-};</pre>
-
- <p>The <dfn
- title="dom-opendatabase"><code>openDatabase()</code></dfn> method on
- the <code>Window</code> and <code>WorkerUtils</code> interfaces and
- the <dfn
- title="dom-opendatabase-sync"><code>openDatabaseSync()</code></dfn>
- method on the <code>WorkerUtils</code> interface take the following
- arguments: a database name, a database version, a display name, an
- estimated size — in bytes — of the data that will be
- stored in the database, and optionally a callback to be invoked if
- the database has not yet been created. The callback, if provided, is
- intended to be used to call <code
- title="dom-database-changeVersion">changeVersion()</code>; the
- callback is invoked with the database having the empty string as its
- version regardless of the given database version. If the callback is
- not provided, the database is created with the given database
- version as its version.</p>
-
- <p>When invoked, these methods must run the following steps, with all
- but the last two steps being run atomically:</p>
-
- <ol>
-
- <li>
-
- <p>The user agent may raise a <code>SECURITY_ERR</code> exception
- instead of returning a <code>Database</code> object if the request
- violates a policy decision (e.g. if the user agent is configured
- to not allow the page to open databases).</p>
-
- </li>
-
- <li>
-
- <p>For the method on the <code>Window</code> object: let <var
- title="">origin</var> be the <span>origin</span> of the
- <span>active document</span> of the <span>browsing context</span>
- of the <code>Window</code> object on which the method was
- invoked.</p>
-
- <p>For the methods on the <code>WorkerUtils</code> object: let
- <var title="">origin</var> be the <span>origin</span> of the
- scripts in the worker.</p>
-
- </li>
-
- <li><p>If <var title="">origin</var> is not a scheme/host/port
- tuple, then throw a <code>SECURITY_ERR</code> exception and abort
- these steps.</p></li>
-
- <li><p>If the database version provided is not the empty string,
- and there is already a database with the given name from the origin
- <var title="">origin</var>, but the database has a different
- version than the version provided, then throw an
- <code>INVALID_STATE_ERR</code> exception and abort these
- steps.</p></li>
-
- <li>
-
- <p>If no database with the given name from the origin <var
- title="">origin</var> exists, then create the database and let
- <var title="">created</var> be true. If a callback was passed to
- the method, then set the new database's version to the empty
- string. Otherwise, set the new database's version to the given
- database version.</p>
-
- <p>Otherwise, if a database with the given name already exists,
- let <var title="">created</var> be false.</p>
-
- </li>
-
- <li>
-
- <p>For the <code title="dom-opendatabase">openDatabase()</code>
- methods: let <var title="">result</var> be a newly constructed
- <code>Database</code> object representing the database with the
- given database name from the origin <var
- title="">origin</var>.</p>
-
- <p>For the <code
- title="dom-opendatabase-sync">openDatabaseSync()</code> method:
- let <var title="">result</var> be a newly constructed
- <code>DatabaseSync</code> object representing the database with
- the given database name from the origin <var
- title="">origin</var>.</p>
-
- </li>
-
- <li>
-
- <p>If <var title="">created</var> is false or if no callback was
- passed to the method, skip this step. Otherwise:</p>
-
- <p>For the <code title="dom-opendatabase">openDatabase()</code>
- methods: <span>queue a task</span> to to invoke the callback with
- <var title="">result</var> as its only argument.</p>
-
- <p>For the <code
- title="dom-opendatabase-sync">openDatabaseSync()</code> method:
- invoke the callback with <var title="">result</var> as its only
- argument. If the callback throws an exception, rethrow that
- exception and abort these steps.</p>
-
- </li>
-
- <li>
-
- <p>Return <var title="">result</var>.</p>
-
- </li>
-
- </ol>
-
- <p>All strings including the empty string are valid database
- names. Database names must be compared in a
- <span>case-sensitive</span> manner.</p>
-
- <p class="note">Implementations can support this even in
- environments that only support a subset of all strings as database
- names by mapping database names (e.g. using a hashing algorithm) to
- the supported set of names.</p>
-
- <p>The version that the database was opened with is the <dfn
- title="concept-database-expected-version">expected version</dfn> of
- this <code>Database</code> or <code>DatabaseSync</code> object. It
- can be the empty string, in which case there is no expected version
- — any version is fine.</p>
-
- <p>User agents are expected to use the display name and the
- estimated database size to optimize the user experience. For
- example, a user agent could use the estimated size to suggest an
- initial quota to the user. This allows a site that is aware that it
- will try to use hundreds of megabytes to declare this upfront,
- instead of the user agent prompting the user for permission to
- increase the quota every five megabytes.</p>
-
-
- <h5>Parsing and processing SQL statements</h5>
-
- <p>When the user agent is to <dfn title="preprocess the SQL
- statement">preprocess a SQL statement</dfn> <var
- title="">sqlStatement</var> with an array of arguments <var
- title="">arguments</var>, it must run the following steps:</p>
-
- <ol>
-
- <li><p>Parse <var title="">sqlStatement</var> as a SQL statement,
- with the exception that U+003F QUESTION MARK characters (?) can be
- used in place of SQL literals in the statement. <a
- href="#refsSQL">[SQL]</a></p></li>
-
- <li>
-
- <p>Bind each <code title="">?</code> placeholder with the value of
- the argument in the <var title="">arguments</var> array with the
- same position. (So the first <code title="">?</code> placeholder
- gets bound to the first value in the <var title="">arguments</var>
- array, and generally the <var title="">n</var>th <code
- title="">?</code> placeholder gets bound to the <var
- title="">n</var>th value in the <var title="">arguments</var>
- array.)</p>
-
- <p class="note">Binding the <code title="">?</code> placeholders
- is done at the literal level, not as string concatenations, so
- this provides a way to dynamically insert parameters into a
- statement without risk of a SQL injection attack.</p>
-
- <p>The result is <var title="">the statement</var>.</p>
-
- </li>
-
- <li><p>If the <code>Database</code> object that the
- <code>SQLTransaction</code> or <code>SQLTransactionSync</code>
- object was created from has an <span
- title="concept-database-expected-version">expected version</span>
- that is neither the empty string nor the actual version of the
- database, then mark <var title="">the statement</var> as
- bogus. (<span title="dom-sqlerror-code-2">Error code
- 2</span>.)</p></li>
-
- <li>
-
- <p>Otherwise, if the syntax of <var title="">sqlStatement</var> is
- not valid (except for the use of <code title="">?</code>
- characters in the place of literals), or the statement uses
- features that are not supported (e.g. due to security reasons), or
- the number of items in the <var title="">arguments</var> array is
- not equal to the number of <code title="">?</code> placeholders in
- the statement, or the statement cannot be parsed for some other
- reason, then mark <var title="">the statement</var> as
- bogus. (<span title="dom-sqlerror-code-5">Error code
- 5</span>.)</p>
-
- <p>User agents must consider statements that use the <code
- title="">BEGIN</code>, <code title="">COMMIT</code>, and <code
- title="">ROLLBACK</code> SQL features as being unsupported (and thus
- will mark them as bogus), so as to not let these statements
- interfere with the explicit transactions managed by the database API
- itself.</p>
-
- </li>
-
- <li id="modifications-fail-if-read-only">
-
- <p>Otherwise, if the <i>mode</i> that was used to create the
- <code>SQLTransaction</code> or <code>SQLTransactionSync</code>
- object is read-only but the statement's main verb can modify the
- database, mark the statement as bogus. (<span
- title="dom-sqlerror-code-5">Error code 5</span>.)</p>
-
- <p class="note">Only the statement's main verb (e.g. <code
- title="">UPDATE</code>, <code title="">SELECT</code>, <code
- title="">DROP</code>) is considered here. Thus, a statement like
- "<code title="">UPDATE test SET id=0 WHERE 0=1</code>" would be
- treated as potentially modifying the database for the purposes
- of this step, even though it could never in fact have any
- side-effects.</p>
-
- </li>
-
- <li><p>Return <var title="">the statement</var>.</p></li>
-
- </ol>
-
- <p>The user agent must act as if the database was hosted in an
- otherwise completely empty environment with no resources. For
- example, attempts to read from or write to the file system will
- fail.</p>
-
- <p class="note">A future version of this specification will probably
- define the exact SQL subset required in more detail.</p>
-
-
-
- <h5>Asynchronous database API</h5>
-
- <pre class="idl">interface <dfn>Database</dfn> {
- void <span title="dom-database-transaction">transaction</span>(in <span>SQLTransactionCallback</span> callback, in optional <span>SQLTransactionErrorCallback</span> errorCallback, in optional <span>SQLVoidCallback</span> successCallback);
- void <span title="dom-database-readTransaction">readTransaction</span>(in <span>SQLTransactionCallback</span> callback, in optional <span>SQLTransactionErrorCallback</span> errorCallback, in optional <span>SQLVoidCallback</span> successCallback);
-
- readonly attribute DOMString <span title="dom-database-version">version</span>;
- void <span title="dom-database-changeVersion">changeVersion</span>(in DOMString oldVersion, in DOMString newVersion, in optional <span>SQLTransactionCallback</span> callback, in optional <span>SQLTransactionErrorCallback</span> errorCallback, in optional <span>SQLVoidCallback</span> successCallback);
-};
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface <dfn>SQLVoidCallback</dfn> {
- void <span title="dom-sqlvoidcallback-handleEvent">handleEvent</span>();
-};
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface <dfn>SQLTransactionCallback</dfn> {
- void <span title="dom-sqltransactioncallback-handleEvent">handleEvent</span>(in <span>SQLTransaction</span> transaction);
-};
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface <dfn>SQLTransactionErrorCallback</dfn> {
- void <span title="dom-sqltransactionerrorcallback-handleEvent">handleEvent</span>(in <span>SQLError</span> error);
-};</pre>
-
- <p>The <dfn
- title="dom-database-transaction"><code>transaction()</code></dfn>
- and <dfn
- title="dom-database-readTransaction"><code>readTransaction()</code></dfn>
- methods takes one to three arguments. When called, these methods must
- immediately return and then asynchronously run the <span>transaction
- steps</span> with the <i>transaction callback</i> being the first
- argument, the <i>error callback</i> being the second argument, if
- any, the <i>success callback</i> being the third argument, if any,
- and with no <i>preflight operation</i> or <i>postflight
- operation</i>.</p>
-
- <p>For the <code
- title="dom-database-transaction">transaction()</code> method, the
- <i>mode</i> must be read/write. For the <code
- title="dom-database-readTransaction">readTransaction()</code>
- method, the <i>mode</i> must be read-only.</p>
-
- <p>On getting, the <dfn
- title="dom-database-version"><code>version</code></dfn> attribute
- must return the current version of the database (as opposed to the
- <span title="concept-database-expected-version">expected
- version</span> of the <code>Database</code> object).</p>
-
- <p>The <dfn
- title="dom-database-changeVersion"><code>changeVersion()</code></dfn>
- method allows scripts to atomically verify the version number and
- change it at the same time as doing a schema update. When the method
- is invoked, it must immediately return, and then asynchronously run
- the <span>transaction steps</span> with the <i>transaction
- callback</i> being the third argument, the <i>error callback</i>
- being the fourth argument, the <i>success callback</i> being the
- fifth argument, the <i>preflight operation</i> being the
- following:</p>
-
- <ol>
-
- <li><p>Check that the value of the first argument to the <code
- title="dom-database-changeVersion">changeVersion()</code> method
- exactly matches the database's actual version. If it does not, then
- the <i>preflight operation</i> fails.</li>
-
- </ol>
-
- <p>...the <i>postflight operation</i> being the following:</p>
-
- <ol>
-
- <li>Change the database's actual version to the value of the second
- argument to the <code
- title="dom-database-changeVersion">changeVersion()</code>
- method.</li>
-
- <li>Change the <code>Database</code> object's expected version to
- the value of the second argument to the <code
- title="dom-database-changeVersion">changeVersion()</code>
- method.</li>
-
- </ol>
-
- <p>...and the <i>mode</i> being read/write.</p>
-
- <p>If any of the optional arguments are omitted, then they must be
- treated as if they were null.</p>
-
-
- <h6>Executing SQL statements</h6>
-
- <p>The <code title="dom-database-transaction">transaction()</code>,
- <code title="dom-database-readTransaction">readTransaction()</code>,
- and <code title="dom-database-changeVersion">changeVersion()</code>
- methods invoke callbacks with <code>SQLTransaction</code>
- objects.</p>
-
- <pre class="idl">typedef sequence<any> <dfn>ObjectArray</dfn>;
-
-interface <dfn>SQLTransaction</dfn> {
- void <span title="dom-sqltransaction-executeSql">executeSql</span>(in DOMString sqlStatement, in optional <span>ObjectArray</span> arguments, in optional <span>SQLStatementCallback</span> callback, in optional <span>SQLStatementErrorCallback</span> errorCallback);
-};
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface <dfn>SQLStatementCallback</dfn> {
- void <span title="dom-sqlstatementcallback-handleEvent">handleEvent</span>(in <span>SQLTransaction</span> transaction, in <span>SQLResultSet</span> resultSet);
-};
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface <dfn>SQLStatementErrorCallback</dfn> {
- boolean <span title="dom-sqlstatementerrorcallback-handleEvent">handleEvent</span>(in <span>SQLTransaction</span> transaction, in <span>SQLError</span> error);
-};</pre>
-
- <p>When the <dfn
- title="dom-sqltransaction-executeSql"><code>executeSql(<var
- title="">sqlStatement</var>, <var title="">arguments</var>, <var
- title="">callback</var>, <var
- title="">errorCallback</var>)</code></dfn> method is invoked, the
- user agent must run the following algorithm. (This algorithm is
- relatively simple in that it doesn't actually execute any SQL
- — the bulk of the work is actually done as part of the
- <span>transaction steps</span>.)</p>
-
- <ol>
-
- <li><p>If the method was not invoked during the execution of a
- <code>SQLTransactionCallback</code>,
- <code>SQLStatementCallback</code>, or
- <code>SQLStatementErrorCallback</code> then raise an
- <code>INVALID_STATE_ERR</code> exception. (Calls from inside a
- <code>SQLTransactionErrorCallback</code> thus raise an
- exception. The <code>SQLTransactionErrorCallback</code> handler is
- only called once a transaction has failed, and no SQL statements
- can be added to a failed transaction.)</p></li>
-
- <li>
-
- <p><span>Preprocess the SQL statement</span> given as the first
- argument to the method (<var title="">sqlStatement</var>), using
- the second argument to the method as the <var
- title="">arguments</var> array, to obtain <var title="">the
- statement</var>.</p>
-
- <p>If the second argument is omitted or null, then treat the <var
- title="">arguments</var> array as empty.</p>
-
- </li>
-
- <li><p>Queue up <var title="">the statement</var> in the
- transaction, along with the third argument (if any) as the
- statement's result set callback and the fourth argument (if any) as
- the error callback.</p></li>
-
- </ol>
-
-
-
- <h6>Processing model</h6>
-
- <p>The <dfn>transaction steps</dfn> are as follows. These steps must
- be run asynchronously. These steps are invoked with a <i>transaction
- callback</i>, optionally an <i>error callback</i>, optionally a
- <i>success callback</i>, optionally a <i>preflight operation</i>,
- optionally a <i>postflight operation</i>, and with a <i>mode</i>
- that is either read/write or read-only.</p>
-
- <ol>
-
- <li><p>Open a new SQL transaction to the database, and create a
- <code>SQLTransaction</code> object that represents that
- transaction. If the <i>mode</i> is read/write, the transaction must
- have an exclusive write lock over the entire database. If the
- <i>mode</i> is read-only, the transaction must have a shared read
- lock over the entire database. The user agent should wait for an
- appropriate lock to be available.</p></li>
-
- <li><p>If an error occurred in the opening of the transaction
- (e.g. if the user agent failed to obtain an appropriate lock after
- an appropriate delay), jump to the last step.</p></li>
-
- <li><p>If a <i>preflight operation</i> was defined for this
- instance of the transaction steps, run that. If it fails, then jump
- to the last step. (This is basically a hook for the <code
- title="dom-database-changeVersion">changeVersion()</code>
- method.)</p></li>
-
- <li><p>If the <i>transaction callback</i> is not null, <span>queue
- a task</span> to invoke the <i>transaction callback</i> with the
- aforementioned <code>SQLTransaction</code> object as its only
- argument, and wait for that task to be run.</p></li>
-
- <li><p>If the callback raised an exception, jump to the last
- step.</p></li>
-
- <li><p>While there are any statements queued up in the transaction,
- perform the following steps for each queued up statement in the
- transaction, oldest first. Each statement has a statement,
- optionally a result set callback, and optionally an error
- callback.</p>
-
- <ol>
-
- <li><p>If the statement is marked as bogus, jump to the "in case
- of error" steps below.</p></li>
-
- <li><p>Execute the statement in the context of the transaction.
- <a href="#refsSQL">[SQL]</a></p>
-
- <li><p>If the statement failed, jump to the "in case of error"
- steps below.</p></li>
-
- <li><p>Create a <code>SQLResultSet</code> object that represents
- the result of the statement.</p></li>
-
- <li><p>If the statement has a result set callback that is not
- null, <span>queue a task</span> to invoke it with the
- <code>SQLTransaction</code> object as its first argument and the
- new <code>SQLResultSet</code> object as its second argument, and
- wait for that task to be run.</p></li>
-
- <li><p>If the callback was invoked and raised an exception, jump
- to the last step in the overall steps.</p></li>
-
- <li><p>Move on to the next statement, if any, or onto the next
- overall step otherwise.</p></li>
-
- </ol>
-
- <p>In case of error (or more specifically, if the above substeps
- say to jump to the "in case of error" steps), run the following
- substeps:</p>
-
- <ol>
-
- <li><p>If the statement had an associated error callback that is
- not null, then <span>queue a task</span> to invoke that error
- callback with the <code>SQLTransaction</code> object and a newly
- constructed <code>SQLError</code> object that represents the
- error that caused these substeps to be run as the two arguments,
- respectively, and wait for the task to be run.</p></li>
-
- <li><p>If the error callback returns false, then move on to the
- next statement, if any, or onto the next overall step
- otherwise.</p></li>
-
- <li><p>Otherwise, the error callback did not return false, or
- there was no error callback. Jump to the last step in the overall
- steps.</p></li>
-
- </ol>
-
- </li>
-
- <li>
-
- <p>If a <i>postflight operation</i> was defined for this instance
- of the transaction steps, then: as one atomic operation, commit
- the transaction and, if that succeeds, run the <i>postflight
- operation</i>. If the commit fails, then instead jump to the last
- step. (This is basically a hook for the <code
- title="dom-database-changeVersion">changeVersion()</code>
- method.)</p>
-
- <p>Otherwise: commit the transaction. If an error occurred in the
- committing of the transaction, jump to the last step.</p>
-
- </li>
-
- <li><p><span>Queue a task</span> to invoke the <i>success
- callback</i>, if it is not null.</p></li>
-
- <li><p>End these steps. The next step is only used when something
- goes wrong.</p></li>
-
- <li><p><span>Queue a task</span> to invoke the transaction's
- <i>error callback</i>, if it is not null, with a newly constructed
- <code>SQLError</code> object that represents the last error to have
- occurred in this transaction. Rollback the transaction. Any
- still-pending statements in the transaction are discarded.</p></li>
-
- </ol>
-
- <p>The <span>task source</span> for these <span
- title="concept-task">tasks</span> is the <dfn>database access task
- source</dfn>.</p>
-
-
-
- <h5>Synchronous database API</h5>
-
- <pre class="idl">interface <dfn>DatabaseSync</dfn> {
- void <span title="dom-database-sync-transaction">transaction</span>(in <span>SQLTransactionSyncCallback</span> callback);
- void <span title="dom-database-sync-readTransaction">readTransaction</span>(in <span>SQLTransactionSyncCallback</span> callback);
-
- readonly attribute DOMString <span title="dom-database-sync-version">version</span>;
- void <span title="dom-database-sync-changeVersion">changeVersion</span>(in DOMString oldVersion, in DOMString newVersion, in optional <span>SQLTransactionSyncCallback</span> callback);
-};
-
-[Callback=FunctionOnly, NoInterfaceObject]
-interface <dfn>SQLTransactionSyncCallback</dfn> {
- void <span title="dom-sqltransactionsynccallback-handleEvent">handleEvent</span>(in <span>SQLTransactionSync</span> transaction);
-};</pre>
-
- <p>The <dfn
- title="dom-database-sync-transaction"><code>transaction()</code></dfn>
- and <dfn
- title="dom-database-sync-readTransaction"><code>readTransaction()</code></dfn>
- methods must run the following steps:</p>
-
- <ol>
-
- <li><p>If the method was the <code
- title="dom-database-sync-transaction">transaction()</code> method,
- <span>create a <code>SQLTransactionSync</code> object</span> for a
- read/write transaction. Otherwise, <span>create a
- <code>SQLTransactionSync</code> object</span> for a read-only
- transaction. In either case, if this throws an exception, then
- rethrow it and abort these steps. Otherwise, let <var
- title="">transaction</var> be the newly created
- <code>SQLTransactionSync</code> object.</p></li>
-
- <li><p>If the first argument is null, rollback the transaction,
- throw a <code>SQLException</code> exception, and abort these
- steps. (<span title="dom-sqlerror-code-0">Error code
- 0</span>.)</p></li>
-
- <li><p>Invoke the callback given by the first argument, passing it
- the <var title="">transaction</var> object as its only
- argument.</p></li>
-
- <li><p>Mark the <code>SQLTransactionSync</code> object as <i
- title="">stale</i>.</p>
-
- <li><p>If the callback was terminated by an exception, then
- rollback the transaction, rethrow that exception, and abort these
- steps.</p></li>
-
- <li><p>Commit the transaction.</p></li>
-
- <li><p>If an error occurred in the committing of the transaction,
- rollback the transaction, throw a <code>SQLException</code>
- exception, and abort these steps.</p></li>
-
- </ol>
-
- <p>On getting, the <dfn
- title="dom-database-sync-version"><code>version</code></dfn>
- attribute must return the current version of the database (as
- opposed to the <span
- title="concept-database-expected-version">expected version</span> of
- the <code>DatabaseSync</code> object).</p>
-
- <p>The <dfn
- title="dom-database-sync-changeVersion"><code>changeVersion()</code></dfn>
- method allows scripts to atomically verify the version number and
- change it at the same time as doing a schema update. When the method
- is invoked, it must run the following steps:</p>
-
- <ol>
-
- <li><p><span>Create a <code>SQLTransactionSync</code> object</span>
- for a read/write transaction. If this throws an exception, then
- rethrow it and abort these steps. Otherwise, let <var
- title="">transaction</var> be the newly created
- <code>SQLTransactionSync</code> object.</p></li>
-
- <li><p>Check that the value of the first argument to the <code
- title="dom-database-sync-changeVersion">changeVersion()</code>
- method exactly matches the database's actual version. If it does
- not, then throw a <code>SQLException</code> exception and abort
- these steps. (<span title="dom-sqlerror-code-2">Error code
- 2</span>.)</p></li>
-
- <li><p>If the third argument is not null, invoke the callback given
- by the third argument, passing it the <var
- title="">transaction</var> object as its only argument.</p></li>
-
- <li><p>Mark the <code>SQLTransactionSync</code> object as <i
- title="">stale</i>.</p>
-
- <li><p>If the callback was terminated by an exception, then
- rollback the transaction, rethrow the exception, and abort these
- steps.</p></li>
-
- <li><p>Commit the transaction.</p></li>
-
- <li><p>If an error occurred in the committing of the transaction,
- rollback the transaction, throw a <code>SQLException</code>
- exception, and abort these steps.</p></li>
-
- <li>Change the database's actual version to the value of the second
- argument to the <code
- title="dom-database-sync-changeVersion">changeVersion()</code>
- method.</li>
-
- <li>Change the <code>Database</code> object's expected version to
- the value of the second argument to the <code
- title="dom-database-sync-changeVersion">changeVersion()</code>
- method.</li>
-
- </ol>
-
- <hr>
-
- <p>When the user agent is to <dfn>create a
- <code>SQLTransactionSync</code> object</dfn> for a transaction that
- is either read/write or read-only, it must run the following
- steps:</p>
-
- <ol>
-
- <li><p>Open a new SQL transaction to the database, and create a
- <code>SQLTransactionSync</code> object that represents that
- transaction. If the <i>mode</i> is read/write, the transaction must
- have an exclusive write lock over the entire database. If the
- <i>mode</i> is read-only, the transaction must have a shared read
- lock over the entire database. The user agent should wait for an
- appropriate lock to be available.</p></li>
-
- <li><p>If an error occurred in the opening of the transaction
- (e.g. if the user agent failed to obtain an appropriate lock after
- an appropriate delay), throw a <code>SQLException</code> exception
- and abort these steps.</p></li>
-
- <li><p>Return the newly created <code>SQLTransactionSync</code>
- object.</p></li>
-
- </ol>
-
-
-
- <h6>Executing SQL statements</h6>
-
- <p>The <code
- title="dom-database-sync-transaction">transaction()</code>, <code
- title="dom-database-sync-readTransaction">readTransaction()</code>,
- and <code
- title="dom-database-sync-changeVersion">changeVersion()</code>
- methods invoke callbacks that are passed
- <code>SQLTransactionSync</code> objects.</p>
-
- <pre class="idl">// typedef sequence<any> <span>ObjectArray</span>;
-
-interface <dfn>SQLTransactionSync</dfn> {
- <span>SQLResultSet</span> <span title="dom-sqltransaction-sync-executeSql">executeSql</span>(in DOMString sqlStatement, in optional <span>ObjectArray</span> arguments);
-};</pre>
-
- <p>A <code>SQLTransactionSync</code> object is initially <i
- title="">fresh</i>, but it will be marked as <i title="">stale</i>
- once it has been committed or rolled back.</p>
-
- <p>When the <dfn
- title="dom-sqltransaction-sync-executeSql"><code>executeSql(<var
- title="">sqlStatement</var>, <var
- title="">arguments</var>)</code></dfn> method is invoked, the user
- agent must run the following algorithm:</p>
-
- <ol>
-
- <li><p>If the <code>SQLTransactionSync</code> object is <i
- title="">stale</i>, then throw an <code>INVALID_STATE_ERR</code>
- exception.</p></li>
-
- <li>
-
- <p><span>Preprocess the SQL statement</span> given as the first
- argument to the method (<var title="">sqlStatement</var>), using
- the second argument to the method as the <var
- title="">arguments</var> array, to obtain <var title="">the
- statement</var>.</p>
-
- <p>If the second argument is omitted or null, then treat the <var
- title="">arguments</var> array as empty.</p>
-
- </li>
-
- <li><p>If the statement is marked as bogus, throw a
- <code>SQLException</code> exception.</p></li>
-
- <li><p>Execute the statement in the context of the transaction.
- <a href="#refsSQL">[SQL]</a></p>
-
- <li><p>If the statement failed, throw a <code>SQLException</code>
- exception.</p></li>
-
- <li><p>Create a <code>SQLResultSet</code> object that represents
- the result of the statement.</p></li>
-
- <li><p>Return the newly created <code>SQLResultSet</code>
- object.</p></li>
-
- </ol>
-
-
-
- <h5>Database query results</h5>
-
- <p>The <code title="dom-sqltransaction-executeSql">executeSql()</code>
- method invokes its callback with a <code>SQLResultSet</code> object
- as an argument.</p>
-
- <pre class="idl">interface <dfn>SQLResultSet</dfn> {
- readonly attribute long <span title="dom-SQLResultSet-insertId">insertId</span>;
- readonly attribute long <span title="dom-SQLResultSet-rowsAffected">rowsAffected</span>;
- readonly attribute <span>SQLResultSetRowList</span> <span title="dom-SQLResultSet-rows">rows</span>;
-};</pre>
-
- <p>The <dfn
- title="dom-SQLResultSet-insertId"><code>insertId</code></dfn>
- attribute must return the row ID of the row that the
- <code>SQLResultSet</code> object's SQL statement inserted into the
- database, if the statement inserted a row. If the statement inserted
- multiple rows, the ID of the last row must be the one returned. If
- the statement did not insert a row, then the attribute must instead
- raise an <code>INVALID_ACCESS_ERR</code> exception.</p>
-
- <p>The <dfn
- title="dom-SQLResultSet-rowsAffected"><code>rowsAffected</code></dfn>
- attribute must return the number of rows that were changed by the
- SQL statement. If the statement did not affected any rows, then the
- attribute must return zero. For "SELECT" statements, this returns
- zero (querying the database doesn't affect any rows).</p>
-
- <p>The <dfn title="dom-SQLResultSet-rows"><code>rows</code></dfn>
- attribute must return a <code>SQLResultSetRowList</code>
- representing the rows returned, in the order returned by the
- database. The same object must be returned each time. If no rows
- were returned, then the object will be empty (its <code
- title="dom-SQLResultSetRowList-length">length</code> will be
- zero).</p>
-
- <pre class="idl">interface <dfn>SQLResultSetRowList</dfn> {
- readonly attribute unsigned long <span title="dom-SQLResultSetRowList-length">length</span>;
- getter <span>any</span> <span title="dom-SQLResultSetRowList-item">item</span>(in unsigned long index);
-};</pre>
-
- <p class="note">For the asynchronous API, implementors are
- encouraged to prefetch all the data for
- <code>SQLResultSetRowList</code> objects when the object is
- constructed (before the result set callback is invoked), rather than
- on-demand, for better responsiveness. For the synchronous API, an
- on-demand lazy evaluation implementation strategy is encouraged
- instead, for better performance.</p>
-
- <p><code>SQLResultSetRowList</code> objects have a <dfn
- title="dom-SQLResultSetRowList-length"><code>length</code></dfn>
- attribute that must return the number of rows it represents (the
- number of rows returned by the database). This is the <var
- title="dom-SQLResultSetRowList-length">length</var>.</p>
-
- <p class="note">Fetching the <code
- title="dom-SQLResultSetRowList-length">length</code> might be
- expensive, and authors are thus encouraged to avoid using it (or
- enumerating over the object, which implicitly uses it) where
- possible.</p>
-
- <p>The object's <span>supported property indices</span> are the
- numbers in the range zero to <span title=""><var
- title="dom-SQLResultSetRowList-length">length</var>-1</span>, unless
- the <var title="dom-SQLResultSetRowList-length">length</var> is
- zero, in which case there are no <span>supported property
- indices</span>.</p>
-
- <p>The <dfn title="dom-SQLResultSetRowList-item"><code>item(<var
- title="">index</var>)</code></dfn> attribute must return the row
- with the given index <var title="">index</var>. If there is no such
- row, then the method must return null.</p>
-
- <p>Each row must be represented by a native ordered dictionary data
- type. In the JavaScript binding, this must be <code>Object</code>.
- Each row object must have one property (or dictionary entry) per
- column, with those properties enumerating in the order that these
- columns were returned by the database. Each property must have the
- name of the column and the value of the cell, as they were returned
- by the database.</p>
-
-
- <h5>Errors and exceptions</h5>
-
- <p>Errors in the asynchronous database API are reported using
- callbacks that have a <code>SQLError</code> object as one of their
- arguments.</p>
-
- <pre class="idl">interface <dfn>SQLError</dfn> {
- const unsigned short <span title="dom-SQLException-code-UNKNOWN">UNKNOWN_ERR</span> = 0;
- const unsigned short <span title="dom-SQLException-code-DATABASE">DATABASE_ERR</span> = 1;
- const unsigned short <span title="dom-SQLException-code-VERSION">VERSION_ERR</span> = 2;
- const unsigned short <span title="dom-SQLException-code-TOO_LARGE">TOO_LARGE_ERR</span> = 3;
- const unsigned short <span title="dom-SQLException-code-QUOTA">QUOTA_ERR</span> = 4;
- const unsigned short <span title="dom-SQLException-code-SYNTAX">SYNTAX_ERR</span> = 5;
- const unsigned short <span title="dom-SQLException-code-CONSTRAINT">CONSTRAINT_ERR</span> = 6;
- const unsigned short <span title="dom-SQLException-code-TIMEOUT">TIMEOUT_ERR</span> = 7;
- readonly attribute unsigned short <span title="dom-SQLError-code">code</span>;
- readonly attribute DOMString <span title="dom-SQLError-message">message</span>;
-};</pre>
-
- <p>The <dfn title="dom-SQLError-code"><code>code</code></dfn> IDL
- attribute must return the most appropriate code from the table
- below.</p>
-
- <p>The <dfn title="dom-SQLError-message"><code>message</code></dfn>
- IDL attribute must return an error message describing the error
- encountered. The message should be localized to the user's
- language.</p>
-
- <hr>
-
- <p>Errors in the synchronous database API are reported using
- <code>SQLException</code> exceptions:</p>
-
- <pre class="idl">exception <dfn>SQLException</dfn> {
- const unsigned short <span title="dom-SQLException-code-UNKNOWN">UNKNOWN_ERR</span> = 0;
- const unsigned short <span title="dom-SQLException-code-DATABASE">DATABASE_ERR</span> = 1;
- const unsigned short <span title="dom-SQLException-code-VERSION">VERSION_ERR</span> = 2;
- const unsigned short <span title="dom-SQLException-code-TOO_LARGE">TOO_LARGE_ERR</span> = 3;
- const unsigned short <span title="dom-SQLException-code-QUOTA">QUOTA_ERR</span> = 4;
- const unsigned short <span title="dom-SQLException-code-SYNTAX">SYNTAX_ERR</span> = 5;
- const unsigned short <span title="dom-SQLException-code-CONSTRAINT">CONSTRAINT_ERR</span> = 6;
- const unsigned short <span title="dom-SQLException-code-TIMEOUT">TIMEOUT_ERR</span> = 7;
- unsigned short <span title="dom-SQLException-code">code</span>;
- DOMString <span title="dom-SQLException-message">message</span>;
-};</pre>
-
- <p>The <dfn title="dom-SQLException-code"><code>code</code></dfn>
- IDL attribute must return the most appropriate code from the table
- below.</p>
-
- <p>The <dfn
- title="dom-SQLException-message"><code>message</code></dfn> IDL
- attribute must return an error message describing the error
- encountered. The message should be localized to the user's
- language.</p>
-
- <hr>
-
- <p>The error codes are as follows:</p>
-
- <table>
- <thead>
- <tr>
- <th>Constant
- <th>Code
- <th>Situation
- <tbody>
-
- <tr>
- <td><dfn title="dom-SQLException-code-UNKNOWN"><code>UNKNOWN_ERR</code></dfn>
- <td><dfn title="dom-sqlerror-code-0">0</dfn>
- <td>The transaction failed for reasons unrelated to the database
- itself and not covered by any other error code.
-
- <tr>
- <td><dfn title="dom-SQLException-code-DATABASE"><code>DATABASE_ERR</code></dfn>
- <td><dfn title="dom-sqlerror-code-1">1</dfn>
- <td>The statement failed for database reasons not covered by any
- other error code.
-
- <tr>
- <td><dfn title="dom-SQLException-code-VERSION"><code>VERSION_ERR</code></dfn>
- <td><dfn title="dom-sqlerror-code-2">2</dfn>
- <td>The operation failed because the actual database version was
- not what it should be. For example, a statement found that the
- actual database version no longer matched the <span
- title="concept-database-expected-version">expected version</span>
- of the <code>Database</code> or <code>DatabaseSync</code> object,
- or the <code
- title="dom-database-changeversion">Database.changeVersion()</code>
- or <code
- title="dom-database-sync-changeversion">DatabaseSync.changeVersion()</code>
- methods were passed a version that doesn't match the actual
- database version.
-
- <tr>
- <td><dfn title="dom-SQLException-code-TOO_LARGE"><code>TOO_LARGE_ERR</code></dfn>
- <td><dfn title="dom-sqlerror-code-3">3</dfn>
- <td>The statement failed because the data returned from the
- database was too large. The SQL "LIMIT" modifier might be useful
- to reduce the size of the result set.
-
- <tr>
- <td><dfn title="dom-SQLException-code-QUOTA"><code>QUOTA_ERR</code></dfn>
- <td><dfn title="dom-sqlerror-code-4">4</dfn>
- <td>The statement failed because there was not enough remaining
- storage space, or the storage quota was reached and the user
- declined to give more space to the database.
-
- <tr>
- <td><dfn title="dom-SQLException-code-SYNTAX"><code>SYNTAX_ERR</code></dfn>
- <td><dfn title="dom-sqlerror-code-5">5</dfn>
- <td>The statement failed because of a syntax error, or the number
- of arguments did not match the number of <code title="">?</code>
- placeholders in the statement, or the statement tried to use a
- statement that is not allowed, such as <code
- title="">BEGIN</code>, <code title="">COMMIT</code>, or <code
- title="">ROLLBACK</code>, or the statement tried to use a verb
- that could modify the database but the transaction was read-only.
-
- <tr>
- <td><dfn title="dom-SQLException-code-CONSTRAINT"><code>CONSTRAINT_ERR</code></dfn>
- <td><dfn title="dom-sqlerror-code-6">6</dfn>
- <td>An <code title="">INSERT</code>, <code
- title="">UPDATE</code>, or <code title="">REPLACE</code>
- statement failed due to a constraint failure. For example,
- because a row was being inserted and the value given for the
- primary key column duplicated the value of an existing row.
-
- <tr>
- <td><dfn title="dom-SQLException-code-TIMEOUT"><code>TIMEOUT_ERR</code></dfn>
- <td><dfn title="dom-sqlerror-code-7">7</dfn>
- <td>A lock for the transaction could not be obtained in a
- reasonable time.
-
- </table>
-
-
- <h4>Web SQL</h4>
-
- <p>User agents must implement the SQL dialect supported by Sqlite 3.6.19.</p>
-
- <p>When converting bound arguments to SQL data types, the JavaScript
- ToPrimitive abstract operation must be applied to obtain the raw
- value to be processed. <a href="#refsECMA262">[ECMA262]</a>.</p>
-
- <!--END database-->
-
- <!-- the next <h3> section needs reworking if we re-add database to complete -->
-
- </div><!--data-component-->
-
-
- <h3>Common concerns</h3>
-
- <!--START complete--><!--START epub-->
-
- <div data-component="Web Storage (editor: Ian Hickson)">
-
- <!--START database-->
- <!--START storage-->
-
<h4>Disk space</h4>
<p>User agents should limit the total amount of space allowed for
- <!--END database-->
- storage areas.
- <!--END storage-->
- <!--END complete--><!--END epub-->
- <!--START database-->
- databases.
- <!--END database-->
- these storage features.
- <!--START complete--><!--START epub-->
- <!--START database-->
- <!--START storage-->
- </p>
+ storage areas.</p>
<p>User agents should guard against sites storing data under the
origins other affiliated sites, e.g. storing up to the limit in
@@ -85723,11 +84571,9 @@
<p>User agents should allow users to see how much space each domain
is using.</p>
- <!--END database-->
<!--<p>If the storage area space limit is reached during a <code
title="dom-Storage-setItem">setItem()</code> call, the method will
raise an exception.</p>-->
- <!--START database-->
<p>A mostly arbitrary limit of five megabytes per
<span>origin</span> is recommended. Implementation feedback is
@@ -85741,23 +84587,13 @@
<p>A third-party advertiser (or any entity capable of getting
content distributed to multiple sites) could use a unique identifier
- stored in its
- <!--END database-->
- local storage area
- <!--END storage-->
- <!--END complete--><!--END epub-->
- or its
- <!--START database-->
- client-side databases
- <!--START complete--><!--START epub-->
- <!--START storage-->
- to track a user across multiple sessions, building a profile of the
- user's interests to allow for highly targeted advertising. In
- conjunction with a site that is aware of the user's real identity
- (for example an e-commerce site that requires authenticated
- credentials), this could allow oppressive groups to target
- individuals with greater accuracy than in a world with purely
- anonymous Web usage.</p>
+ stored in its local storage area to track a user across multiple
+ sessions, building a profile of the user's interests to allow for
+ highly targeted advertising. In conjunction with a site that is
+ aware of the user's real identity (for example an e-commerce site
+ that requires authenticated credentials), this could allow
+ oppressive groups to target individuals with greater accuracy than
+ in a world with purely anonymous Web usage.</p>
<p>There are a number of techniques that can be used to mitigate the
risk of user tracking:</p>
@@ -85767,19 +84603,11 @@
<dt>Blocking third-party storage</dt>
<dd>
- <p>User agents may restrict access to
- <!--END database-->
- the <code title="dom-localStorage">localStorage</code> objects
- <!--END storage-->
- <!--END complete--><!--END epub-->
- and
- <!--START database-->
- the database objects
- <!--START complete--><!--START epub-->
- <!--START storage-->
- to scripts originating at the domain of the top-level document of
- the <span>browsing context</span>, for instance denying access to
- the API for pages from other domains running in
+ <p>User agents may restrict access to the <code
+ title="dom-localStorage">localStorage</code> objects to scripts
+ originating at the domain of the top-level document of the
+ <span>browsing context</span>, for instance denying access to the
+ API for pages from other domains running in
<code>iframe</code>s.</p>
</dd>
@@ -85790,12 +84618,10 @@
<p>User agents may, if so configured by the user, automatically
delete stored data after a period of time.</p>
- <!--END database-->
<p>For example, a user agent could be configured to treat
third-party local storage areas as session-only storage, deleting
the data once the user had closed all the <span title="browsing
context">browsing contexts</span> that could access it.</p>
- <!--START database-->
<p>This can restrict the ability of a site to track a user, as the
site would then only be able to track the user across multiple
@@ -85807,10 +84633,8 @@
risk, if the user does not fully understand the implications of
data expiration.</p>
- <!--END database-->
<!--v2 consider adding an explicit way for sites to state when
data should expire, as in localStorage.expireData(365); -->
- <!--START database-->
</dd>
@@ -85818,53 +84642,24 @@
<dd>
<p>If users attempt to protect their privacy by clearing cookies
- without also clearing data stored in the
- <!--END database-->
- local storage area,
- <!--END storage-->
- <!--END complete--><!--END epub-->
- <!--START database-->
- relevant databases,
- <!--END database-->
- local storage area and relevant databases,
- <!--START complete--><!--START epub-->
- <!--START database-->
- <!--START storage-->
- sites can defeat those attempts by using the two features as
- redundant backup for each other. User agents should present the
- interfaces for clearing these in a way that helps users to
- understand this possibility and enables them to delete data in all
- persistent storage features simultaneously. <a
+ without also clearing data stored in the local storage area, sites
+ can defeat those attempts by using the two features as redundant
+ backup for each other. User agents should present the interfaces
+ for clearing these in a way that helps users to understand this
+ possibility and enables them to delete data in all persistent
+ storage features simultaneously. <a
href="#refsCOOKIES">[COOKIES]</a></p>
</dd>
- <dt>Site-specific white-listing of access to
- <!--END database-->
- local storage areas
- <!--END storage-->
- <!--END complete--><!--END epub-->
- and
- <!--START database-->
- databases
- <!--START complete--><!--START epub-->
- <!--START storage-->
- </dt>
+ <dt>Site-specific white-listing of access to local storage
+ areas</dt>
<dd>
- <!--END database-->
<p>User agents may allow sites to access session storage areas in
an unrestricted manner, but require the user to authorize access
to local storage areas.</p>
- <!--END storage-->
- <!--END complete--><!--END epub-->
- <!--START database-->
- <p>User agents may require the user to authorize access to
- databases before a site can use the feature.</p>
- <!--START complete--><!--START epub-->
- <!--START storage-->
-
</dd>
<dt>Origin-tracking of stored data</dt>
@@ -85935,39 +84730,17 @@
from that domain. To mitigate this, pages can use TLS. Pages using
TLS can be sure that only pages using TLS that have certificates
identifying them as being from the same domain can access their
- <!--END database-->
- storage areas.
- <!--END storage-->
- <!--END complete--><!--END epub-->
- <!--START database-->
- databases.
- <!--END database-->
- storage areas and databases.
- <!--START complete--><!--START epub-->
- <!--START database-->
- <!--START storage-->
- </p>
+ storage areas.</p>
<h5>Cross-directory attacks</h5>
<p>Different authors sharing one host name, for example users
- hosting content on <code>geocities.com</code>, all share one
- <!--END database-->
- local storage object.
- <!--END storage-->
- <!--END complete--><!--END epub-->
- <!--START database-->
- set of databases.
- <!--END database-->
- common set of storage objects and databases.
- <!--START complete--><!--START epub-->
- <!--START database-->
- <!--START storage-->
- There is no feature to restrict the access by pathname. Authors on
- shared hosts are therefore recommended to avoid using these
- features, as it would be trivial for other authors to read the data
- and overwrite it.</p>
+ hosting content on <code>geocities.com</code>, all share one local
+ storage object. There is no feature to restrict the access by
+ pathname. Authors on shared hosts are therefore recommended to avoid
+ using these features, as it would be trivial for other authors to
+ read the data and overwrite it.</p>
<p class="note">Even if a path-restriction feature was made
available, the usual DOM scripting security model would make it
@@ -85999,34 +84772,7 @@
<p>Thus, strictly following the <span>origin</span> model described
in this specification is important for user security.</p>
-
- <!--END storage-->
- <!--END complete--><!--END epub-->
-
- <h5>SQL and user agents</h5>
-
- <p>User agent implementors are strongly encouraged to audit all
- their supported SQL statements for security implications. For
- example, <code title="">LOAD DATA INFILE</code> is likely to pose
- security risks and there is little reason to support it.</p>
-
- <p>In general, it is recommended that user agents not support
- features that control how databases are stored on disk. For example,
- there is little reason to allow Web authors to control the character
- encoding used in the disk representation of the data, as all data in
- JavaScript is implicitly UTF-16.</p>
-
-
- <h5>SQL injection</h5>
-
- <p>Authors are strongly recommended to make use of the <code
- title="">?</code> placeholder feature of the <code
- title="dom-sqltransaction-executeSql">executeSql()</code> method,
- and to never construct SQL statements on the fly.</p>
-
-<!--END database-->
-
-<!--START complete--><!--START epub-->
+<!--END storage-->
<!--FIXUP complete +1-->
</div><!--data-component-->
@@ -106762,7 +105508,7 @@
<!--START complete--><!--START epub--><!--START html-->
<!--START html-device--><!--START microdata--><!--START 2dcontext--><!--START postmsg--><!--START w3c-html-->
-<!--START websocket-api--><!--START storage--><!--START database--><!--START eventsource--><!--START workers-->
+<!--START websocket-api--><!--START storage--><!--START eventsource--><!--START workers-->
<!--START whatwg-workers--><!--START vocabs--><!--START vCard--><!--START vEvent--><!--START work-->
<!--START webvtt-->
@@ -107042,9 +105788,9 @@
<dt id="refsHTML5">[HTML5]</dt>
<dd>
-<!--END vocabs--><!--END vCard--><!--END vEvent--><!--END work--><!--END websocket-api--><!--END storage--><!--END database--><!--END eventsource--><!--END whatwg-workers--><!--END workers--><!--END html-device--><!--YYYEND microdata--><!--END 2dcontext--><!--END postmsg--><!--END w3c-html-->
+<!--END vocabs--><!--END vCard--><!--END vEvent--><!--END work--><!--END websocket-api--><!--END storage--><!--END eventsource--><!--END whatwg-workers--><!--END workers--><!--END html-device--><!--YYYEND microdata--><!--END 2dcontext--><!--END postmsg--><!--END w3c-html-->
(Non-normative)
-<!--START html-device--><!--YYYSTART microdata--><!--START 2dcontext--><!--START postmsg--><!--START w3c-html--><!--START websocket-api--><!--START storage--><!--START database--><!--START eventsource--><!--START whatwg-workers--><!--START workers--><!--START vocabs--><!--START vCard--><!--START vEvent--><!--START work-->
+<!--START html-device--><!--YYYSTART microdata--><!--START 2dcontext--><!--START postmsg--><!--START w3c-html--><!--START websocket-api--><!--START storage--><!--START eventsource--><!--START whatwg-workers--><!--START workers--><!--START vocabs--><!--START vCard--><!--START vEvent--><!--START work-->
<cite><a href="http://dev.w3.org/html5/spec/">HTML5</a></cite>,
I. Hickson. W3C.</dd>
@@ -107398,9 +106144,6 @@
<dd><cite>JIS X0208: 7-bit and 8-bit double byte coded KANJI sets
for information interchange</cite>. Japanese Industrial Standards Committee.</dd>
- <dt id="refsSQL">[SQL]</dt>
- <dd>The precise dialect has not yet been specified.</dd>
-
<dt id="refsSRGB">[SRGB]</dt>
<dd><cite lang="en-GB"><a
href="http://webstore.iec.ch/webstore/webstore.nsf/artnum/025408!OpenDocument&Click=">IEC
@@ -107493,10 +106236,6 @@
<dd><cite><a href="http://dev.w3.org/html5/websockets/">The WebSocket
API</a></cite>, I. Hickson. W3C.</dd>
- <dt id="refsWEBSQL">[WEBSQL]</dt>
- <dd><cite><a href="http://dev.w3.org/html5/webdatabase/">Web SQL
- Database</a></cite>, I. Hickson. W3C.</dd>
-
<dt id="refsWEBSTORAGE">[WEBSTORAGE]</dt>
<dd><cite><a href="http://dev.w3.org/html5/webstorage/">Web
Storage</a></cite>, I. Hickson. W3C.</dd>
@@ -107619,7 +106358,7 @@
<!--END webvtt-->
<!--END whatwg-workers--><!--END vocabs--><!--END vCard--><!--END vEvent--><!--END work-->
-<!--END websocket-api--><!--END storage--><!--END database--><!--END eventsource--><!--END workers-->
+<!--END websocket-api--><!--END storage--><!--END eventsource--><!--END workers-->
<!--END html-device--><!--END microdata--><!--END 2dcontext--><!--END postmsg--><!--END w3c-html-->
<!--START w3c-html-->
More information about the Commit-Watchers
mailing list