- From: poot <cvsmail@w3.org>
- Date: Fri, 3 Apr 2009 08:54:44 +0900 (JST)
- To: public-html-diffs@w3.org
Introduce a Synchronous Database API for Workers. (whatwg r2958)
Otherwise, if the mode that was used to create the SQLTransaction or SQLTransactionSync object is read-only but the statement's main verb can modify the database, mark the statement as bogus. (Error code 5.) Only the statement's main verb (e.g. UPDATE, SELECT, DROP) is considered here. Thus, a statement like "UPDATE test SET id=0 WHERE 0=1" 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.
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#modifications-fail-if-read-only
4.4 Asynchronous database API
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#asynchronous-database-api
executeSql(sqlStatement, arguments)
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqltransaction-sync-executesql
openDatabaseSync()
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-opendatabase-sync
SQLResultSet
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#sqlresultset
4.5.1 Executing SQL statements
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#executing-sql-statements-0
executeSql(sqlStatement, arguments, callback, errorCallback)
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqltransaction-executesql
SQLError
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#sqlerror
SQLTransactionErrorCallback
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#sqltransactionerrorcallback
message
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqlerror-message
version
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-database-sync-version
commit()
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqltransaction-sync-commit
SQLTransactionSync
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#sqltransactionsync
4.4.1 Executing SQL statements
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#executing-sql-statements
SQLException
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#sqlexception
code
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqlexception-code
ObjectArray
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#objectarray
5 Disk space
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#disk-space
6
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqlerror-code-6
5
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqlerror-code-5
4
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqlerror-code-4
create a SQLTransactionSync object
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#create-a-sqltransactionsync-object
2
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqlerror-code-2
changeVersion()
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-database-sync-changeversion
0
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqlerror-code-0
4.6 Database query results
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#database-query-results
message
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqlexception-message
4.7 Errors and exceptions
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#errors-and-exceptions
transaction()
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-database-transaction
transaction()
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-database-sync-transaction
7
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqlerror-code-7
readTransaction()
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-database-readtransaction
4.3 Parsing and processing SQL statements
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#parsing-and-processing-sql-statements
code
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqlerror-code
changeVersion()
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-database-changeversion
expected version
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#concept-database-expected-version
3
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqlerror-code-3
4.4.2 Processing model
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#processing-model
4.5 Synchronous database API
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#synchronous-database-api
item(index)
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqlresultsetrowlist-item
1
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-sqlerror-code-1
readTransaction()
http://people.w3.org/mike/diffs/html5/webstorage/Overview.1.19.html#dom-database-sync-readtransaction
http://people.w3.org/mike/diffs/html5/webstorage/Overview.diff.html
http://dev.w3.org/cvsweb/html5/webstorage/Overview.html?r1=1.18&r2=1.19&f=h
http://html5.org/tools/web-apps-tracker?from=2957&to=2958
===================================================================
RCS file: /sources/public/html5/webstorage/Overview.html,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -d -r1.18 -r1.19
--- Overview.html 2 Apr 2009 21:32:10 -0000 1.18
+++ Overview.html 2 Apr 2009 23:54:15 -0000 1.19
@@ -237,9 +237,11 @@
<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=#synchronous-database-api><span class=secno>4.5 </span>Synchronous database API</a>
+ <ol>
+ <li><a href=#executing-sql-statements-0><span class=secno>4.5.1 </span>Executing SQL statements</a></ol></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=#errors-and-exceptions><span class=secno>4.7 </span>Errors and exceptions</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>
@@ -616,9 +618,9 @@
database already exists but has a different version, or no version,
then the method must raise an <code>INVALID_STATE_ERR</code>
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,
+ this <code><a href=#database>Database</a></code> or <code><a href=#databasesync>DatabaseSync</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 requested is the same as the current version associated
with the database, then the method must return an object
@@ -661,18 +663,56 @@
</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>If the <code><a href=#database>Database</a></code> object that the
+ <code><a href=#sqltransaction>SQLTransaction</a></code> or <code><a href=#sqltransactionsync>SQLTransactionSync</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 <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>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. (<a href=#dom-sqlerror-code-5 title=dom-sqlerror-code-5>Error code
+ 5</a>.)</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><a href=#sqltransaction>SQLTransaction</a></code> or <code><a href=#sqltransactionsync>SQLTransactionSync</a></code>
+ object is read-only but the statement's main verb can modify the
+ database, mark the statement as bogus. (<a href=#dom-sqlerror-code-5 title=dom-sqlerror-code-5>Error code 5</a>.)</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>.</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> {
+ </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 class=note>A future version of this specification will probably
+ define the exact SQL subset required in more detail.<h3 id=asynchronous-database-api><span class=secno>4.4 </span>Asynchronous database API</h3><pre class=idl>interface <dfn id=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);
@@ -695,7 +735,7 @@
void <span title=dom-sqltransactionerrorcallback-handleEvent>handleEvent</span>(in <a href=#sqlerror>SQLError</a> error);
};</pre><p>The <dfn id=dom-database-transaction title=dom-database-transaction><code>transaction()</code></dfn>
and <dfn id=dom-database-readtransaction title=dom-database-readTransaction><code>readTransaction()</code></dfn>
- methods takes one to three arguments. When called, these method must
+ methods takes one to three arguments. When called, these methods must
immediately return and then asynchronously run the <a href=#transaction-steps>transaction
steps</a> with the <i>transaction callback</i> being the first
argument, the <i>error callback</i> being the second argument, if
@@ -726,7 +766,8 @@
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.<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>
+ </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>,
+ <code title=dom-database-readTransaction><a href=#dom-database-readtransaction>readTransaction()</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>;
@@ -768,31 +809,12 @@
</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 <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 <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
- example, attempts to read from or write to the file system will
- fail.<p>SQL inherently supports multiple concurrent connections. Authors
- should make appropriate use of the transaction features to handle
- the case of multiple scripts interacting with the same database
- simultaneously (as could happen if the same page was opened in two
- different <span title="browsing context">browsing
- contexts</span>).<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 class=note>A future version of this specification will probably
- 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
+ </ol><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>,
@@ -836,20 +858,6 @@
<ol><li><p>If the statement is marked as bogus, jump to the "in case
of error" steps below.</li>
- <li id=modifications-fail-if-read-only>
-
- <p>If the <i>mode</i> is read-only but the statement's main verb
- can modify the database, jump to the "in case of error" steps
- below.</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>Execute the statement in the context of the transaction.
<a href=#refsSQL>[SQL]</a></p>
@@ -916,7 +924,117 @@
transaction. Rollback the transaction. Any still-pending statements
in the transaction are discarded.</li>
- </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>
+ </ol><h3 id=synchronous-database-api><span class=secno>4.5 </span>Synchronous database API</h3><pre class=idl>interface <dfn id=databasesync>DatabaseSync</dfn> {
+ <a href=#sqltransactionsync>SQLTransactionSync</a> <a href=#dom-database-sync-transaction title=dom-database-sync-transaction>transaction</a>();
+ <a href=#sqltransactionsync>SQLTransactionSync</a> <a href=#dom-database-sync-readtransaction title=dom-database-sync-readTransaction>readTransaction</a>();
+
+ readonly attribute DOMString <a href=#dom-database-sync-version title=dom-database-sync-version>version</a>;
+ <a href=#sqltransactionsync>SQLTransactionSync</a> <a href=#dom-database-sync-changeversion title=dom-database-sync-changeVersion>changeVersion</a>(in DOMString oldVersion, in DOMString newVersion);
+};</pre><p>The <dfn id=dom-database-sync-transaction title=dom-database-sync-transaction><code>transaction()</code></dfn>
+ method must <a href=#create-a-sqltransactionsync-object>create a <code>SQLTransactionSync</code>
+ object</a> for a read/write transaction, and return that
+ object.<p>The <dfn id=dom-database-sync-readtransaction title=dom-database-sync-readTransaction><code>readTransaction()</code></dfn>
+ method must <a href=#create-a-sqltransactionsync-object>create a <code>SQLTransactionSync</code>
+ object</a> for a read/only transaction, and return that
+ object.<p>On getting, the <dfn id=dom-database-sync-version title=dom-database-sync-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=#databasesync>DatabaseSync</a></code> object).<p>The <dfn id=dom-database-sync-changeversion 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:<ol><li><p><a href=#create-a-sqltransactionsync-object>Create a <code>SQLTransactionSync</code> object</a>
+ for a read/write transaction. If this throws an exception, then
+ rethrow it and abort these steps.</li>
+
+ <li><p>Check that the value of the first argument to the <code title=dom-database-sync-changeVersion><a href=#dom-database-sync-changeversion>changeVersion()</a></code>
+ method exactly matches the database's actual version. If it does
+ not, then throw a <code><a href=#sqltransactionsync>SQLTransactionSync</a></code> object and abort
+ these steps. (<a href=#dom-sqlerror-code-2 title=dom-sqlerror-code-2>Error code
+ 2</a>.)</li>
+
+ <li><p>Return the <code><a href=#sqltransactionsync>SQLTransactionSync</a></code> object.</li>
+
+ </ol><p>When the <code><a href=#sqltransactionsync>SQLTransactionSync</a></code> object's <code title=dom-sqltransaction-sync-commit><a href=#dom-sqltransaction-sync-commit>commit()</a></code> method is
+ invoked, when the steps for that method invoke the <i>postcommit
+ operation</i>, the user agent must run the following steps:<ol><li>Change the database's actual version to the value of the second
+ argument to the <code title=dom-database-sync-changeVersion><a href=#dom-database-sync-changeversion>changeVersion()</a></code>
+ method.</li>
+
+ <li>Change the <code><a href=#database>Database</a></code> object's expected version to
+ the value of the second argument to the <code title=dom-database-sync-changeVersion><a href=#dom-database-sync-changeversion>changeVersion()</a></code>
+ method.</li>
+
+ </ol><hr><p>When the user agent is to <dfn id=create-a-sqltransactionsync-object>create a
+ <code>SQLTransactionSync</code> object</dfn> for a transaction that
+ is either read/write or read-only, it must run the following
+ steps:<ol><li><p>Open a new SQL transaction to the database, and create a
+ <code><a href=#sqltransactionsync>SQLTransactionSync</a></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.</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><a href=#sqlexception>SQLException</a></code> exception
+ and abort these steps.</li>
+
+ <li><p>Return the newly created <code><a href=#sqltransactionsync>SQLTransactionSync</a></code>
+ object.</li>
+
+ </ol><h4 id=executing-sql-statements-0><span class=secno>4.5.1 </span>Executing SQL statements</h4><p>The <code title=dom-database-sync-transaction><a href=#dom-database-sync-transaction>transaction()</a></code>, <code title=dom-database-sync-readTransaction><a href=#dom-database-sync-readtransaction>readTransaction()</a></code>,
+ and <code title=dom-database-sync-changeVersion><a href=#dom-database-sync-changeversion>changeVersion()</a></code>
+ methods return <code><a href=#sqltransactionsync>SQLTransactionSync</a></code> objects.<pre class=idl>// typedef sequence<any> <a href=#objectarray>ObjectArray</a>;
+
+interface <dfn id=sqltransactionsync>SQLTransactionSync</dfn> {
+ <a href=#sqlresultset>SQLResultSet</a> <a href=#dom-sqltransaction-sync-executesql title=dom-sqltransaction-sync-executeSql>executeSql</a>(in DOMString sqlStatement, [Optional] in <a href=#objectarray>ObjectArray</a> arguments);
+ void <a href=#dom-sqltransaction-sync-commit title=dom-sqltransaction-sync-commit>commit</a>();
+};</pre><p>A <code><a href=#sqltransactionsync>SQLTransactionSync</a></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>When the <dfn id=dom-sqltransaction-sync-executesql 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:<ol><li><p>If the <code><a href=#sqltransactionsync>SQLTransactionSync</a></code> object is <i title="">stale</i>, then throw an <code>INVALID_STATE_ERR</code>
+ exception.</li>
+
+ <li>
+
+ <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>
+
+ </li>
+
+ <li><p>If the statement is marked as bogus, throw a
+ <code><a href=#sqlexception>SQLException</a></code> exception.</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><a href=#sqlexception>SQLException</a></code>
+ exception.</li>
+
+ <li><p>Create a <code><a href=#sqlresultset>SQLResultSet</a></code> object that represents
+ the result of the statement.</li>
+
+ <li><p>Return the newly created <code><a href=#sqlresultset>SQLResultSet</a></code>
+ object.</li>
+
+ </ol><hr><p>When the <dfn id=dom-sqltransaction-sync-commit title=dom-sqltransaction-sync-commit><code>commit()</code></dfn>
+ method is invoked, the user agent must run the following
+ algorithm:<ol><li><p>Commit the transaction.</li>
+
+ <li><p>Mark the <code><a href=#sqltransactionsync>SQLTransactionSync</a></code> object as <i title="">stale</i>.</p>
+
+ <li><p>If appropriate (i.e. if the <code title=dom-database-sync-changeVersion><a href=#dom-database-sync-changeversion>changeVersion()</a></code>
+ method created the <code><a href=#sqltransactionsync>SQLTransactionSync</a></code> object), invoke
+ the <i>postcommit operation</i>.</p>
+
+ <li><p>If an error occurred in the committing of the transaction,
+ throw a <code><a href=#sqlexception>SQLException</a></code> exception.</li>
+
+ </ol><h3 id=database-query-results><span class=secno>4.6 </span>Database query results</h3><p>The <code title=dom-sqltransaction-executeSql><a href=#dom-sqltransaction-executesql>executeSql()</a></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>;
@@ -955,13 +1073,27 @@
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> {
+ by the database.<h3 id=errors-and-exceptions><span class=secno>4.7 </span>Errors and exceptions</h3><p>Errors in the asynchronous 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
+ attribute must return the most appropriate code from the table
+ below.<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.<hr><p>Errors in the synchronous database API are reported using
+ exceptions that implement the <code><a href=#sqlexception>SQLException</a></code>
+ interface:<pre class=idl>exception <dfn id=sqlexception>SQLException</dfn> {
+ readonly attribute unsigned long <a href=#dom-sqlexception-code title=dom-SQLException-code>code</a>;
+ readonly attribute DOMString <a href=#dom-sqlexception-message title=dom-SQLException-message>message</a>;
+};</pre><p>The <dfn id=dom-sqlexception-code title=dom-SQLException-code><code>code</code></dfn>
+ DOM attribute must return the most appropriate code from the table
+ below.<p>The <dfn id=dom-sqlexception-message title=dom-SQLException-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.<hr><p>The error codes are as follows:<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
@@ -972,8 +1104,14 @@
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.
+ <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 <a href=#concept-database-expected-version title=concept-database-expected-version>expected version</a>
+ of the <code><a href=#database>Database</a></code> or <code><a href=#databasesync>DatabaseSync</a></code> object,
+ or the <code title=dom-database-changeversion><a href=#dom-database-changeversion>Database.changeVersion()</a></code>
+ or <code title=dom-database-sync-changeversion><a href=#dom-database-sync-changeversion>DatabaseSync.changeVersion()</a></code>
+ methods were passed a version that doesn'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
@@ -986,12 +1124,11 @@
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.
+ <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 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>
@@ -999,12 +1136,11 @@
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
+ <tr><td><dfn id=dom-sqlerror-code-7 title=dom-sqlerror-code-7>7</dfn>
+ <td>A lock for the transaction could not be obtained in a
+ reasonable time.
+
+ </table><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 23:55:29 UTC