hixie: Make the Sync Database API use callbacks. (whatwg r3636)

hixie: Make the Sync Database API use callbacks. (whatwg r3636)

http://dev.w3.org/cvsweb/html5/webdatabase/Overview.html?r1=1.10&r2=1.11&f=h
http://html5.org/tools/web-apps-tracker?from=3635&to=3636

===================================================================
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:29:41 UTC