webstorage/Overview.html 1.18 2957 Set the stage for a synchronous Data

Set the stage for a synchronous Database API. (whatwg r2957)

4.4 Asynchronous database API
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#asynchronous-database-api
openDatabaseSync()
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-opendatabase-sync
executeSql(sqlStatement, arguments, callback, errorCallback)
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqltransaction-executesql
SQLError
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#sqlerror
message
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqlerror-message
4.7 Errors
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#errors
SQLResultSetRowList
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#sqlresultsetrowlist
rows
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqlresultset-rows
SQLResultSet
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#sqlresultset
4.4.1 Executing SQL statements
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#executing-sql-statements
ObjectArray
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#objectarray
5 Disk space
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#disk-space
6
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqlerror-code-6
5
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqlerror-code-5
4
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqlerror-code-4
3
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqlerror-code-3
version
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-database-version
1
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqlerror-code-1
0
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqlerror-code-0
insertId
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqlresultset-insertid
rowsAffected
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqlresultset-rowsaffected
length
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqlresultsetrowlist-length
readTransaction()
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-database-readtransaction
4.3 Parsing and processing SQL statements
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#parsing-and-processing-sql-statements
code
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqlerror-code
changeVersion()
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-database-changeversion
expected version
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#concept-database-expected-version
4.6 Database query results
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#database-query-results
Database
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#database
4.4.2 Processing model
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#processing-model
openDatabase()
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-opendatabase
2
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqlerror-code-2
4.5 Synchronous database API
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#synchronous-database-api
item(index)
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#dom-sqlresultsetrowlist-item
4.2 Databases
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.18.html#databases

http://people.w3.org/mike/diffs/html5/webstorage/Overview.diff.html
http://dev.w3.org/cvsweb/html5/webstorage/Overview.html?r1=1.17&r2=1.18&f=h
http://html5.org/tools/web-apps-tracker?from=2956&to=2957

===================================================================
RCS file: /sources/public/html5/webstorage/Overview.html,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -d -r1.17 -r1.18
--- Overview.html 2 Apr 2009 00:49:12 -0000 1.17
+++ Overview.html 2 Apr 2009 21:32:10 -0000 1.18
@@ -232,10 +232,14 @@
   <ol>
    <li><a href=#introduction-0><span class=secno>4.1 </span>Introduction</a></li>
    <li><a href=#databases><span class=secno>4.2 </span>Databases</a></li>
-   <li><a href=#executing-sql-statements><span class=secno>4.3 </span>Executing SQL statements</a></li>
-   <li><a href=#database-query-results><span class=secno>4.4 </span>Database query results</a></li>
-   <li><a href=#errors><span class=secno>4.5 </span>Errors</a></li>
-   <li><a href=#processing-model><span class=secno>4.6 </span>Processing model</a></ol></li>
+   <li><a href=#parsing-and-processing-sql-statements><span class=secno>4.3 </span>Parsing and processing SQL statements</a></li>
+   <li><a href=#asynchronous-database-api><span class=secno>4.4 </span>Asynchronous database API</a>
+    <ol>
+     <li><a href=#executing-sql-statements><span class=secno>4.4.1 </span>Executing SQL statements</a></li>
+     <li><a href=#processing-model><span class=secno>4.4.2 </span>Processing model</a></ol></li>
+   <li><a href=#synchronous-database-api><span class=secno>4.5 </span>Synchronous database API</a></li>
+   <li><a href=#database-query-results><span class=secno>4.6 </span>Database query results</a></li>
+   <li><a href=#errors><span class=secno>4.7 </span>Errors</a></ol></li>
  <li><a href=#disk-space><span class=secno>5 </span>Disk space</a></li>
  <li><a href=#privacy><span class=secno>6 </span>Privacy</a>
   <ol>
@@ -586,37 +590,89 @@
   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>The <dfn id=dom-opendatabase title=dom-opendatabase><code>openDatabase()</code></dfn> method
-  returns a <code><a href=#database>Database</a></code> object. The method takes four
-  arguments: a database name, a database version, a display name, and
-  an estimated size, in bytes, of the data that will be stored in the
-  database.<p>The <code title=dom-opendatabase><a href=#dom-opendatabase>openDatabase()</a></code> method
-  must use and create databases from the <span>origin</span> of the
-  <code>Document</code> of the <code>Window</code> object on which the
-  method was invoked.<p>If the database version provided is not the empty string, and the
+  assumptions.<p>The <dfn id=dom-opendatabase title=dom-opendatabase><code>openDatabase()</code></dfn> method on
+  the <code>Window</code> and <code>WorkerUtils</code> interfaces must
+  return a newly constructed <code><a href=#database>Database</a></code> object that
+  represents the database requested.<p>The <dfn id=dom-opendatabase-sync title=dom-opendatabase-sync><code>openDatabaseSync()</code></dfn>
+  method on the <code>WorkerUtils</code> interfaces must return a
+  newly constructed <code><a href=#databasesync>DatabaseSync</a></code> object that represents
+  the database requested.<p>These methods take four arguments: a database name, a database
+  version, a display name, and an estimated size, in bytes, of the
+  data that will be stored in the database.<p>The database requested is the one with the given database
+  name from the appropriate <span>origin</span>.<p>The <code title=dom-opendatabase><a href=#dom-opendatabase>openDatabase()</a></code> method
+  on the <code>Window</code> object must use and create databases from
+  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>The <code title=dom-opendatabase><a href=#dom-opendatabase>openDatabase()</a></code> and
+  <code title=dom-opendatabase-sync><a href=#dom-opendatabase-sync>openDatabaseSync()</a></code>
+  methods on the <code>WorkerUtils</code> object must use and create
+  databases from the <span>origin</span> of the scripts in the
+  worker.<p>All strings including the empty string are valid database
+  names. Database names must be compared in a
+  <span>case-sensitive</span> manner.<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>If the database version provided is not the empty string, and the
   database already exists but has a different version, or no version,
   then the method must raise an <code>INVALID_STATE_ERR</code>
-  exception.<p>Otherwise, if the database version provided is the empty string,
+  exception.<p>The version that the database was opened with is the <dfn id=concept-database-expected-version title=concept-database-expected-version>expected version</dfn> of
+  this <code><a href=#database>Database</a></code> object. It can be the empty string, in
+  which case there is no expected version &mdash; any version is
+  fine.<p>Otherwise, if the database version provided is the empty string,
   or if the database doesn't yet exist, or if the database exists and
-  the version provided to the <code title=dom-opendatabase><a href=#dom-opendatabase>openDatabase()</a></code> method is the same as
-  the current version associated with the database, then the method
-  must return a <code><a href=#database>Database</a></code> object representing the database
-  that has the name that was given. If no such database exists, it
-  must be created first.<p>All strings including the empty string are valid database
-  names. Database names must be compared in a
-  <span>case-sensitive</span> manner.<p>The user agent may raise a <code>SECURITY_ERR</code> exception
+  the version requested is the same as the current version associated
+  with the database, then the method must return an object
+  representing the database that has the name that was given. If no
+  such database exists, it must be created first.<p>The user agent may raise a <code>SECURITY_ERR</code> exception
   instead of returning a <code><a href=#database>Database</a></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 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>User agents are expected to use the display name and the
+  not allow the page to open databases).<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.<pre class=idl>interface <dfn id=database>Database</dfn> {
+  increase the quota every five megabytes.<h3 id=parsing-and-processing-sql-statements><span class=secno>4.3 </span>Parsing and processing SQL statements</h3><p>When the user agent is to <dfn id=preprocess-the-sql-statement 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:<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></li>
+
+   <li>
+
+    <p>Replace 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 replaced by the first value in the <var title="">arguments</var> array, and generally the <var title="">n</var>th <code title="">?</code> placeholder gets
+    replaced by the <var title="">n</var>th value in the <var title="">arguments</var> array.)</p>
+
+    <p class=note>Substitutions for <code title="">?</code>
+    placeholders are 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>
+
+    <p class=XXX>Implementation feedback is requested on what
+    to do with arguments that are of types that are not supported by
+    the underlying SQL backend. For example, SQLite doesn't support
+    booleans, so what should the UA do if passed a boolean? The Gears
+    team suggests failing, not silently converting types.</p>
+
+   </li>
+
+   <li><p>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.</li>
+
+   <li><p>Return <var title="">the statement</var>.</li>
+
+  </ol><h3 id=asynchronous-database-api><span class=secno>4.4 </span>Asynchronous database API</h3><pre class=idl>interface <dfn id=database title=Database>Database</dfn> {
   void <a href=#dom-database-transaction title=dom-database-transaction>transaction</a>(in <a href=#sqltransactioncallback>SQLTransactionCallback</a> callback, [Optional] in <a href=#sqltransactionerrorcallback>SQLTransactionErrorCallback</a> errorCallback, [Optional] in <a href=#sqlvoidcallback>SQLVoidCallback</a> successCallback);
   void <a href=#dom-database-readtransaction title=dom-database-readTransaction>readTransaction</a>(in <a href=#sqltransactioncallback>SQLTransactionCallback</a> callback, [Optional] in <a href=#sqltransactionerrorcallback>SQLTransactionErrorCallback</a> errorCallback, [Optional] in <a href=#sqlvoidcallback>SQLVoidCallback</a> successCallback);
 
@@ -647,10 +703,7 @@
   and with no <i>preflight operation</i> or <i>postflight
   operation</i>.<p>For the <code title=dom-database-transaction><a href=#dom-database-transaction>transaction()</a></code> method, the
   <i>mode</i> must be read/write. For the <code title=dom-database-readTransaction><a href=#dom-database-readtransaction>readTransaction()</a></code>
-  method, the <i>mode</i> must be read-only.<p>The version that the database was opened with is the <dfn id=concept-database-expected-version title=concept-database-expected-version>expected version</dfn> of
-  this <code><a href=#database>Database</a></code> object. It can be the empty string, in
-  which case there is no expected version &mdash; any version is
-  fine.<p>On getting, the <dfn id=dom-database-version title=dom-database-version><code>version</code></dfn> attribute
+  method, the <i>mode</i> must be read-only.<p>On getting, the <dfn id=dom-database-version title=dom-database-version><code>version</code></dfn> attribute
   must return the current version of the database (as opposed to the
   <a href=#concept-database-expected-version title=concept-database-expected-version>expected
   version</a> of the <code><a href=#database>Database</a></code> object).<p>The <dfn id=dom-database-changeversion title=dom-database-changeVersion><code>changeVersion()</code></dfn>
@@ -673,7 +726,7 @@
    the value of the second argument to the <code title=dom-database-changeVersion><a href=#dom-database-changeversion>changeVersion()</a></code>
    method.</li>
 
-  </ol><p>...and the <i>mode</i> being read/write.<h3 id=executing-sql-statements><span class=secno>4.3 </span>Executing SQL statements</h3><p>The <code title=dom-database-transaction><a href=#dom-database-transaction>transaction()</a></code>
+  </ol><p>...and the <i>mode</i> being read/write.<h4 id=executing-sql-statements><span class=secno>4.4.1 </span>Executing SQL statements</h4><p>The <code title=dom-database-transaction><a href=#dom-database-transaction>transaction()</a></code>
   and <code title=dom-database-changeVersion><a href=#dom-database-changeversion>changeVersion()</a></code>
   methods invoke callbacks with <code><a href=#sqltransaction>SQLTransaction</a></code>
   objects.<pre class=idl>typedef sequence&lt;any&gt; <dfn id=objectarray>ObjectArray</dfn>;
@@ -704,53 +757,28 @@
    only called once a transaction has failed, and no SQL statements
    can be added to a failed transaction.)</li>
 
-   <li><p>Parse the first argument to the method (<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></li>
-
    <li>
 
-    <p>Replace 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 replaced by the first value in the <var title="">arguments</var> array, and generally the <var title="">n</var>th <code title="">?</code> placeholder gets
-    replaced by the <var title="">n</var>th value in the <var title="">arguments</var> array.)</p>
-
-    <p class=note>Substitutions for <code title="">?</code>
-    placeholders are 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><a href=#preprocess-the-sql-statement>Preprocess the SQL statement</a> 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>
 
-    <p>The result is <i>the statement</i>.</p>
-
-    <p class=XXX>Implementation feedback is requested on what
-    to do with arguments that are of types that are not supported by
-    the underlying SQL backend. For example, SQLite doesn't support
-    booleans, so what should the UA do if passed a boolean? The Gears
-    team suggests failing, not silently converting types.</p>
-
    </li>
 
-   <li><p>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 <i>the
-   statement</i> as bogus.</li>
-
    <li><p>If the <code><a href=#database>Database</a></code> object that the
    <code><a href=#sqltransaction>SQLTransaction</a></code> object was created from has an <a href=#concept-database-expected-version title=concept-database-expected-version>expected version</a>
    that is neither the empty string nor the actual version of the
-   database, then mark <i>the statement</i> as bogus. (<a href=#dom-sqlerror-code-2 title=dom-sqlerror-code-2>Error code 2</a>.)</li>
+   database, then mark <var title="">the statement</var> as
+   bogus. (<a href=#dom-sqlerror-code-2 title=dom-sqlerror-code-2>Error code
+   2</a>.)</li>
 
-   <li><p>Queue up <i>the statement</i> 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.</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.</li>
 
   </ol><p>The user agent must act as if the database was hosted in an
   otherwise completely empty environment with no resources. For
@@ -764,95 +792,7 @@
   will mark them as bogus), so as to not let these statements
   interfere with the explicit transactions managed by the database API
   itself.<p class=note>A future version of this specification will probably
-  define the exact SQL subset required in more detail.<h3 id=database-query-results><span class=secno>4.4 </span>Database query results</h3><p>The <code title=dom-transaction-executeSql>executeSql()</code>
-  method invokes its callback with a <code><a href=#sqlresultset>SQLResultSet</a></code> object
-  as an argument.<pre class=idl>interface <dfn id=sqlresultset>SQLResultSet</dfn> {
-  readonly attribute long <a href=#dom-sqlresultset-insertid title=dom-SQLResultSet-insertId>insertId</a>;
-  readonly attribute long <a href=#dom-sqlresultset-rowsaffected title=dom-SQLResultSet-rowsAffected>rowsAffected</a>;
-  readonly attribute <a href=#sqlresultsetrowlist>SQLResultSetRowList</a> <a href=#dom-sqlresultset-rows title=dom-SQLResultSet-rows>rows</a>;
-};</pre><p>The <dfn id=dom-sqlresultset-insertid title=dom-SQLResultSet-insertId><code>insertId</code></dfn>
-  attribute must return the row ID of the row that the
-  <code><a href=#sqlresultset>SQLResultSet</a></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>The <dfn id=dom-sqlresultset-rowsaffected title=dom-SQLResultSet-rowsAffected><code>rowsAffected</code></dfn>
-  attribute must return the number of rows that were affected 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>The <dfn id=dom-sqlresultset-rows title=dom-SQLResultSet-rows><code>rows</code></dfn>
-  attribute must return a <code><a href=#sqlresultsetrowlist>SQLResultSetRowList</a></code>
-  representing the rows returned, in the order returned by the
-  database. If no rows were returned, then the object will be empty
-  (its <code title=dom-SQLResultSetRowList-length><a href=#dom-sqlresultsetrowlist-length>length</a></code> will
-  be zero).<pre class=idl>interface <dfn id=sqlresultsetrowlist>SQLResultSetRowList</dfn> {
-  readonly attribute unsigned long <a href=#dom-sqlresultsetrowlist-length title=dom-SQLResultSetRowList-length>length</a>;
-  [IndexGetter] <span>any</span> <a href=#dom-sqlresultsetrowlist-item title=dom-SQLResultSetRowList-item>item</a>(in unsigned long index);
-};</pre><p><code><a href=#sqlresultsetrowlist>SQLResultSetRowList</a></code> objects have a <dfn id=dom-sqlresultsetrowlist-length 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><a href=#dom-sqlresultsetrowlist-length>length</a></var>.<p>The object's <span>indices of the supported indexed
-  properties</span> are the numbers in the range zero to <span title=""><var title=dom-SQLResultSetRowList-length><a href=#dom-sqlresultsetrowlist-length>length</a></var>-1</span>, unless
-  the <var title=dom-SQLResultSetRowList-length><a href=#dom-sqlresultsetrowlist-length>length</a></var> is
-  zero, in which case there are no <span>supported indexed
-  properties</span>.<p>The <dfn id=dom-sqlresultsetrowlist-item 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 raise an <code>INDEX_SIZE_ERR</code>
-  exception.<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.<h3 id=errors><span class=secno>4.5 </span>Errors</h3><p>Errors in the database API are reported using callbacks that have
-  a <code><a href=#sqlerror>SQLError</a></code> object as one of their arguments.<pre class=idl>interface <dfn id=sqlerror>SQLError</dfn> {
-  readonly attribute unsigned long <a href=#dom-sqlerror-code title=dom-SQLError-code>code</a>;
-  readonly attribute DOMString <a href=#dom-sqlerror-message title=dom-SQLError-message>message</a>;
-};</pre><p>The <dfn id=dom-sqlerror-code title=dom-SQLError-code><code>code</code></dfn> DOM
-  attribute must return the most appropriate code from the following
-  table:<table><thead><tr><th>Code
-     <th>Situation
-   <tbody><tr><td><dfn id=dom-sqlerror-code-0 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 id=dom-sqlerror-code-1 title=dom-sqlerror-code-1>1</dfn>
-     <td>The statement failed for database reasons not covered by any
-     other error code.
-
-    <tr><td><dfn id=dom-sqlerror-code-2 title=dom-sqlerror-code-2>2</dfn>
-     <td>The statement failed because the <a href=#concept-database-expected-version title=concept-database-expected-version>expected version</a>
-     of the database didn't match the actual database version.
-
-    <tr><td><dfn id=dom-sqlerror-code-3 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 id=dom-sqlerror-code-4 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 id=dom-sqlerror-code-5 title=dom-sqlerror-code-5>5</dfn>
-     <td>The statement failed because the transaction's first
-     statement was a read-only statement, and a subsequent statement
-     in the same transaction tried to modify the database, but the
-     transaction failed to obtain a write lock before another
-     transaction obtained a write lock and changed a part of the
-     database that the former transaction was depending upon.
-
-    <tr><td><dfn id=dom-sqlerror-code-6 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.
-
-  </table><p class=XXX>We should define a more thorough list of
-  codes. Implementation feedback is requested to determine what codes
-  are needed.<p>The <dfn id=dom-sqlerror-message title=dom-SQLError-message><code>message</code></dfn>
-  DOM attribute must return an error message describing the error
-  encountered. The message should be localized to the user's
-  language.<h3 id=processing-model><span class=secno>4.6 </span>Processing model</h3><p>The <dfn id=transaction-steps>transaction steps</dfn> are as follows. These steps must
+  define the exact SQL subset required in more detail.<h4 id=processing-model><span class=secno>4.4.2 </span>Processing model</h4><p>The <dfn id=transaction-steps>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>,
@@ -976,7 +916,95 @@
    transaction. Rollback the transaction. Any still-pending statements
    in the transaction are discarded.</li>
 
-  </ol><h2 id=disk-space><span class=secno>5 </span>Disk space</h2><p>User agents should limit the total amount of space allowed for
+  </ol><h3 id=synchronous-database-api><span class=secno>4.5 </span>Synchronous database API</h3><p class=XXX>...<dfn id=databasesync>DatabaseSync</dfn><h3 id=database-query-results><span class=secno>4.6 </span>Database query results</h3><p>The <code title=dom-transaction-executeSql>executeSql()</code>
+  method invokes its callback with a <code><a href=#sqlresultset>SQLResultSet</a></code> object
+  as an argument.<pre class=idl>interface <dfn id=sqlresultset>SQLResultSet</dfn> {
+  readonly attribute long <a href=#dom-sqlresultset-insertid title=dom-SQLResultSet-insertId>insertId</a>;
+  readonly attribute long <a href=#dom-sqlresultset-rowsaffected title=dom-SQLResultSet-rowsAffected>rowsAffected</a>;
+  readonly attribute <a href=#sqlresultsetrowlist>SQLResultSetRowList</a> <a href=#dom-sqlresultset-rows title=dom-SQLResultSet-rows>rows</a>;
+};</pre><p>The <dfn id=dom-sqlresultset-insertid title=dom-SQLResultSet-insertId><code>insertId</code></dfn>
+  attribute must return the row ID of the row that the
+  <code><a href=#sqlresultset>SQLResultSet</a></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>The <dfn id=dom-sqlresultset-rowsaffected title=dom-SQLResultSet-rowsAffected><code>rowsAffected</code></dfn>
+  attribute must return the number of rows that were affected 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>The <dfn id=dom-sqlresultset-rows title=dom-SQLResultSet-rows><code>rows</code></dfn>
+  attribute must return a <code><a href=#sqlresultsetrowlist>SQLResultSetRowList</a></code>
+  representing the rows returned, in the order returned by the
+  database. If no rows were returned, then the object will be empty
+  (its <code title=dom-SQLResultSetRowList-length><a href=#dom-sqlresultsetrowlist-length>length</a></code> will
+  be zero).<pre class=idl>interface <dfn id=sqlresultsetrowlist>SQLResultSetRowList</dfn> {
+  readonly attribute unsigned long <a href=#dom-sqlresultsetrowlist-length title=dom-SQLResultSetRowList-length>length</a>;
+  [IndexGetter] <span>any</span> <a href=#dom-sqlresultsetrowlist-item title=dom-SQLResultSetRowList-item>item</a>(in unsigned long index);
+};</pre><p><code><a href=#sqlresultsetrowlist>SQLResultSetRowList</a></code> objects have a <dfn id=dom-sqlresultsetrowlist-length 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><a href=#dom-sqlresultsetrowlist-length>length</a></var>.<p>The object's <span>indices of the supported indexed
+  properties</span> are the numbers in the range zero to <span title=""><var title=dom-SQLResultSetRowList-length><a href=#dom-sqlresultsetrowlist-length>length</a></var>-1</span>, unless
+  the <var title=dom-SQLResultSetRowList-length><a href=#dom-sqlresultsetrowlist-length>length</a></var> is
+  zero, in which case there are no <span>supported indexed
+  properties</span>.<p>The <dfn id=dom-sqlresultsetrowlist-item 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 raise an <code>INDEX_SIZE_ERR</code>
+  exception.<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.<h3 id=errors><span class=secno>4.7 </span>Errors</h3><p>Errors in the database API are reported using callbacks that have
+  a <code><a href=#sqlerror>SQLError</a></code> object as one of their arguments.<pre class=idl>interface <dfn id=sqlerror>SQLError</dfn> {
+  readonly attribute unsigned long <a href=#dom-sqlerror-code title=dom-SQLError-code>code</a>;
+  readonly attribute DOMString <a href=#dom-sqlerror-message title=dom-SQLError-message>message</a>;
+};</pre><p>The <dfn id=dom-sqlerror-code title=dom-SQLError-code><code>code</code></dfn> DOM
+  attribute must return the most appropriate code from the following
+  table:<table><thead><tr><th>Code
+     <th>Situation
+   <tbody><tr><td><dfn id=dom-sqlerror-code-0 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 id=dom-sqlerror-code-1 title=dom-sqlerror-code-1>1</dfn>
+     <td>The statement failed for database reasons not covered by any
+     other error code.
+
+    <tr><td><dfn id=dom-sqlerror-code-2 title=dom-sqlerror-code-2>2</dfn>
+     <td>The statement failed because the <a href=#concept-database-expected-version title=concept-database-expected-version>expected version</a>
+     of the database didn't match the actual database version.
+
+    <tr><td><dfn id=dom-sqlerror-code-3 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 id=dom-sqlerror-code-4 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 id=dom-sqlerror-code-5 title=dom-sqlerror-code-5>5</dfn>
+     <td>The statement failed because the transaction's first
+     statement was a read-only statement, and a subsequent statement
+     in the same transaction tried to modify the database, but the
+     transaction failed to obtain a write lock before another
+     transaction obtained a write lock and changed a part of the
+     database that the former transaction was depending upon.
+
+    <tr><td><dfn id=dom-sqlerror-code-6 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.
+
+  </table><p class=XXX>We should define a more thorough list of
+  codes. Implementation feedback is requested to determine what codes
+  are needed.<p>The <dfn id=dom-sqlerror-message title=dom-SQLError-message><code>message</code></dfn>
+  DOM attribute must return an error message describing the error
+  encountered. The message should be localized to the user's
+  language.<h2 id=disk-space><span class=secno>5 </span>Disk space</h2><p>User agents should limit the total amount of space allowed for
   storage areas and databases.<p>User agents should guard against sites storing data in the
   storage areas or databases of subdomains, e.g. storing up to the
   limit in a1.example.com, a2.example.com, a3.example.com, etc,

Received on Thursday, 2 April 2009 21:33:26 UTC