- From: poot <cvsmail@w3.org>
- Date: Fri, 3 Apr 2009 06:32:43 +0900 (JST)
- To: public-html-diffs@w3.org
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 — 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 — 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<any> <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