- From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
- Date: Sun, 16 Aug 2009 10:28:43 +0000
- To: public-html-commits@w3.org
Update of /sources/public/html5/webdatabase
In directory hutz:/tmp/cvs-serv26938
Modified Files:
Overview.html
Log Message:
Make the Sync Database API use callbacks. (whatwg r3636)
Index: Overview.html
===================================================================
RCS file: /sources/public/html5/webdatabase/Overview.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -d -r1.10 -r1.11
--- Overview.html 14 Aug 2009 23:08:20 -0000 1.10
+++ Overview.html 16 Aug 2009 10:28:41 -0000 1.11
@@ -174,7 +174,7 @@
<h1>Web Database</h1>
<!--ZZZ:-->
<!--<h2 class="no-num no-toc">W3C Working Draft 23 April 2009</h2>-->
- <h2 class="no-num no-toc" id="editor-s-draft-date-1-january-1970">Editor's Draft 14 August 2009</h2>
+ <h2 class="no-num no-toc" id="editor-s-draft-date-1-january-1970">Editor's Draft 16 August 2009</h2>
<!--:ZZZ-->
<dl><!-- ZZZ: update the month/day (twice), (un)comment out
<dt>This Version:</dt>
@@ -241,7 +241,7 @@
specification's progress along the W3C Recommendation track.
<!--ZZZ:-->
<!--This specification is the 23 April 2009 Working Draft.-->
- This specification is the 14 August 2009 Editor's Draft.
+ This specification is the 16 August 2009 Editor's Draft.
<!--:ZZZ-->
</p><!-- required patent boilerplate --><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5
February 2004 W3C Patent Policy</a>. W3C maintains a <a href="http://www.w3.org/2004/01/pp-impl/42538/status" rel="disclosure">public list of
@@ -701,18 +701,48 @@
</ol><p>The <span>task source</span> for these tasks is the <dfn id="database-access-task-source">database
access task source</dfn>.<h3 id="synchronous-database-api"><span class="secno">4.4 </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>();
+ void <a href="#dom-database-sync-transaction" title="dom-database-sync-transaction">transaction</a>(in <a href="#sqltransactionsynccallback">SQLTransactionSyncCallback</a> callback);
+ void <a href="#dom-database-sync-readtransaction" title="dom-database-sync-readTransaction">readTransaction</a>(in <a href="#sqltransactionsynccallback">SQLTransactionSyncCallback</a> callback);
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);
+ void <a href="#dom-database-sync-changeversion" title="dom-database-sync-changeVersion">changeVersion</a>(in DOMString oldVersion, in DOMString newVersion, in <a href="#sqltransactionsynccallback">SQLTransactionSyncCallback</a> callback);
+};
+
+[Callback=FunctionOnly, NoInterfaceObject]
+interface <dfn id="sqltransactionsynccallback">SQLTransactionSyncCallback</dfn> {
+ void <span title="dom-sqltransactionsynccallback-handleEvent">handleEvent</span>(in <a href="#sqltransactionsync">SQLTransactionSync</a> transaction);
};</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>
+ and <dfn id="dom-database-sync-readtransaction" title="dom-database-sync-readTransaction"><code>readTransaction()</code></dfn>
+ methods must run the following steps:<ol><li><p>If the method was the <code title="dom-database-sync-transaction"><a href="#dom-database-sync-transaction">transaction()</a></code> method,
+ <a href="#create-a-sqltransactionsync-object">create a <code>SQLTransactionSync</code> object</a> for a
+ read/write transaction. Otherwise, <a href="#create-a-sqltransactionsync-object">create a
+ <code>SQLTransactionSync</code> object</a> for a read-only
+ transaction. In either case, if this throws an exception, then
+ rethrow it and abort these steps. Otherwise, let <var title="">transaction</var> be the newly created
+ <code><a href="#sqltransactionsync">SQLTransactionSync</a></code> object.</li>
+
+ <li><p>If the first argument is null, rollback the transaction,
+ throw a <code><a href="#sqlexception">SQLException</a></code> exception, and abort these
+ steps. (<a href="#dom-sqlerror-code-0" title="dom-sqlerror-code-0">Error code
+ 0</a>.)</li>
+
+ <li><p>Invoke the callback given by the first argument, passing it
+ the <var title="">transaction</var> object as its only
+ argument.</li>
+
+ <li><p>Mark the <code><a href="#sqltransactionsync">SQLTransactionSync</a></code> object as <i title="">stale</i>.</p>
+
+ <li><p>If the callback was terminated by an exception, then
+ rollback the transaction, rethrow that exception, and abort these
+ steps.</li>
+
+ <li><p>Commit the transaction.</li>
+
+ <li><p>If an error occurred in the committing of the transaction,
+ rollback the transaction, throw a <code><a href="#sqlexception">SQLException</a></code>
+ exception, and abort these steps.</li>
+
+ </ol><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>
@@ -720,19 +750,37 @@
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>
+ rethrow it and abort these steps. Otherwise, let <var title="">transaction</var> be the newly created
+ <code><a href="#sqltransactionsync">SQLTransactionSync</a></code> object.</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
+ not, then throw a <code><a href="#sqlexception">SQLException</a></code> exception 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>
+ <li><p>If the third argument is null, rollback the transaction,
+ throw a <code><a href="#sqlexception">SQLException</a></code> exception, and abort these steps.
+ (<a href="#dom-sqlerror-code-0" title="dom-sqlerror-code-0">Error code
+ 0</a>.)</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
+ <li><p>Invoke the callback given by the third argument, passing it
+ the <var title="">transaction</var> object as its only
+ argument.</li>
+
+ <li><p>Mark the <code><a href="#sqltransactionsync">SQLTransactionSync</a></code> object as <i title="">stale</i>.</p>
+
+ <li><p>If the callback was terminated by an exception, then
+ rollback the transaction, rethrow the exception, and abort these
+ steps.</li>
+
+ <li><p>Commit the transaction.</li>
+
+ <li><p>If an error occurred in the committing of the transaction,
+ rollback the transaction, throw a <code><a href="#sqlexception">SQLException</a></code>
+ exception, and abort these steps.</li>
+
+ <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>
@@ -765,8 +813,6 @@
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>();
- void <a href="#dom-sqltransaction-sync-rollback" title="dom-sqltransaction-sync-rollback">rollback</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>
@@ -798,28 +844,7 @@
<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><hr><p>When the <dfn id="dom-sqltransaction-sync-rollback" title="dom-sqltransaction-sync-rollback"><code>rollback()</code></dfn>
- method is invoked, the user agent must run the following
- algorithm:<ol><li><p>Rollback the transaction.</li>
-
- <li><p>Mark the <code><a href="#sqltransactionsync">SQLTransactionSync</a></code> object as <i title="">stale</i>.</p>
-
- </ol><p>If a <code><a href="#sqltransactionsync">SQLTransactionSync</a></code> object is garbage collected
- while still <i title="">fresh</i>, the user agent must rollback the
- transaction.<h3 id="database-query-results"><span class="secno">4.5 </span>Database query results</h3><p>The <code title="dom-sqltransaction-executeSql"><a href="#dom-sqltransaction-executesql">executeSql()</a></code>
+ </ol><h3 id="database-query-results"><span class="secno">4.5 </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>;
Received on Sunday, 16 August 2009 10:28:53 UTC