[html5] r1024 - /
whatwg at whatwg.org
whatwg at whatwg.org
Fri Sep 21 19:32:24 PDT 2007
Author: ianh
Date: 2007-09-21 19:32:24 -0700 (Fri, 21 Sep 2007)
New Revision: 1024
Modified:
index
source
Log:
[] (0) Add version support to Database. Actually make transactions commit (oops).
Modified: index
===================================================================
--- index 2007-09-22 02:08:07 UTC (rev 1023)
+++ index 2007-09-22 02:32:24 UTC (rev 1024)
@@ -29875,8 +29875,15 @@
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>The version that the database was opened with is the <dfn id=expected
+ title=concept-database-expected-version>expected version</dfn> of this
+ <code><a href="#database0">Database</a></code> object. It can be the empty
+ string, in which case there is no expected version — any version is
+ fine.
+
<pre class=idl>interface <dfn id=database0>Database</dfn> {
- void <span title=dom-database-executeSql>executeSql</span>(in DOMString sqlStatement, <var title="">arguments...</var>, in <a href="#sqlcallback">SQLCallback</a> callback);
+ attribute DOMString <a href="#version" title=dom-database-version>version</a>;
+ void <a href="#executesql" title=dom-database-executeSql>executeSql</a>(in DOMString sqlStatement, <var title="">arguments...</var>, in <a href="#sqlcallback">SQLCallback</a> callback);
void <a href="#closetransaction" title=dom-database-closeTransaction>closeTransaction</a>(); // only needed as part of error recovery
};
@@ -29884,13 +29891,29 @@
void <span title=dom-sqlcallback-handleEvent>handleEvent</span>(in <a href="#resultset">ResultSet</a> resultSet);
};</pre>
+ <p>The <dfn id=version
+ title=dom-database-version><code>version</code></dfn> attribute represents
+ the actual version of the database (as opposed to the <span>expected
+ version</span>).
+
+ <p>On getting, the attribute must return the current version of the
+ database.
+
+ <p>On setting, the attribute must wait for all transactions that are trying
+ to commit to finish commiting, and then must change the current version of
+ the database and the <span>expected version</span> of the <code><a
+ href="#database0">Database</a></code> object on which the attribute was
+ called to the new value.
+
<h4 id=executing><span class=secno>4.12.3. </span>Executing SQL statements</h4>
<p>Once a <code><a href="#database0">Database</a></code> object has been
obtained, an author can interact with the database using the <code
- title=dom-executeSql><a href="#executesql">executeSql()</a></code> method.
+ title=dom-database-executeSql><a
+ href="#executesql">executeSql()</a></code> method.
- <p>When the <dfn id=executesql title=dom-executeSql><code>executeSql(<var
+ <p>When the <dfn id=executesql
+ title=dom-database-executeSql><code>executeSql(<var
title="">sqlStatement</var>, <var title="">arguments...</var>, <var
title="">callback</var>)</code></dfn> method is invoked, the user agent
must run the following algorithm:
@@ -29931,6 +29954,10 @@
statements that were added to that transaction before it have themselves
successfully executed. <a href="#refsSQL">[SQL]</a></p>
+ <p>If the <code><a href="#database0">Database</a></code> object has an
+ <span>expected version</span> that is neither the empty string nor the
+ actual version of the database, the statement must fail.</p>
+
<li>
<p>Once the statement has executed, let <var title="">result</var> be a
new <code><a href="#resultset">ResultSet</a></code> object that
@@ -29956,21 +29983,29 @@
<p>If the callback raised an exception and <var
title="">transaction</var> is not marked as "bad", then <var
title="">transaction</var> must be rolled back and marked as "bad".
+
+ <li>
+ <p>If <var title="">transaction</var> is not marked as "bad" and has no
+ pending statements in it, then the transaction it represents must be
+ commited.
</ol>
<p>The <dfn id=closetransaction
title=dom-database-closeTransaction><code>closeTransaction()</code></dfn>
method may be called while in a callback called by the <code
- title=dom-database-executeSql>executeSql()</code> method. When the method
- is invoked, it must clear any active thread-global transaction, such that
- the next invocation of <code
- title=dom-database-executeSql>executeSql()</code>, even if it is called
- from within an <code title=dom-database-executeSql>executeSql()</code>
- callback, will create a new transaction.
+ title=dom-database-executeSql><a
+ href="#executesql">executeSql()</a></code> method. When the method is
+ invoked, it must clear any active thread-global transaction, such that the
+ next invocation of <code title=dom-database-executeSql><a
+ href="#executesql">executeSql()</a></code>, even if it is called from
+ within an <code title=dom-database-executeSql><a
+ href="#executesql">executeSql()</a></code> callback, will create a new
+ transaction.
<p class=note>This is needed if the previous statement in the current
transaction failed, as otherwise the <code
- title=dom-database-executeSql>executeSql()</code> method would raise an
+ title=dom-database-executeSql><a
+ href="#executesql">executeSql()</a></code> method would raise an
exception.
<p>The user agent must act as if the database was hosted in an otherwise
@@ -29997,7 +30032,7 @@
<h4 id=database><span class=secno>4.12.4. </span>Database query results</h4>
- <p>Calls to the <code title=dom-executeSql><a
+ <p>Calls to the <code title=dom-database-executeSql><a
href="#executesql">executeSql()</a></code> method return <code><a
href="#resultset">ResultSet</a></code> objects.
@@ -30107,7 +30142,13 @@
<tr>
<td>1
- <td>The statement failed.
+ <td>The statement failed for reasons not covered by any other code.
+
+ <tr>
+ <td>2
+
+ <td>The statement failed because the <span>expected version</span> of
+ the database didn't match the actual database version.
</table>
<p class=big-issue>We should define a more thorough list of codes.
@@ -30163,7 +30204,8 @@
<h5 id=sql-injection><span class=secno>4.12.6.2. </span>SQL injection</h5>
<p>Authors are strongly recommended to make use of the <code
- title="">?</code> placeholder feature of the <code title=dom-executeSql><a
+ title="">?</code> placeholder feature of the <code
+ title=dom-database-executeSql><a
href="#executesql">executeSql()</a></code> method, and to never construct
SQL statements on the fly.
Modified: source
===================================================================
--- source 2007-09-22 02:08:07 UTC (rev 1023)
+++ source 2007-09-22 02:32:24 UTC (rev 1024)
@@ -27329,7 +27329,14 @@
names by mapping database names (e.g. using a hashing algorithm) to
the supported set of names.</p>
+ <p>The version that the database was opened with is the <dfn
+ title="concept-database-expected-version">expected version</dfn> of
+ this <code>Database</code> object. It can be the empty string, in
+ which case there is no expected version — any version is
+ fine.</p>
+
<pre class="idl">interface <dfn>Database</dfn> {
+ attribute DOMString <span title="dom-database-version">version</span>;
void <span title="dom-database-executeSql">executeSql</span>(in DOMString sqlStatement, <var title="">arguments...</var>, in <span>SQLCallback</span> callback);
void <span title="dom-database-closeTransaction">closeTransaction</span>(); // only needed as part of error recovery
};
@@ -27338,14 +27345,29 @@
void <span title="dom-sqlcallback-handleEvent">handleEvent</span>(in <span>ResultSet</span> resultSet);
};</pre>
+ <p>The <dfn title="dom-database-version"><code>version</code></dfn>
+ attribute represents the actual version of the database (as opposed
+ to the <span>expected version</span>).</p>
+ <p>On getting, the attribute must return the current version of the
+ database.</p>
+
+ <p>On setting, the attribute must wait for all transactions that are
+ trying to commit to finish commiting, and then must change the
+ current version of the database and the <span>expected
+ version</span> of the <code>Database</code> object on which the
+ attribute was called to the new value.</p>
+
+
+
<h4>Executing SQL statements</h4>
<p>Once a <code>Database</code> object has been obtained, an author
can interact with the database using the <code
- title="dom-executeSql">executeSql()</code> method.</p>
+ title="dom-database-executeSql">executeSql()</code> method.</p>
- <p>When the <dfn title="dom-executeSql"><code>executeSql(<var
+ <p>When the <dfn
+ title="dom-database-executeSql"><code>executeSql(<var
title="">sqlStatement</var>, <var title="">arguments...</var>, <var
title="">callback</var>)</code></dfn> method is invoked, the user
agent must run the following algorithm:</p>
@@ -27383,11 +27405,20 @@
<li><p>The method must then return, but these steps must
continue.</p></li>
- <li><p>The user agent must then add the specified SQL statement to
- <var title="">transaction</var>, and must execute it as soon as all
- the statements that were added to that transaction before it have
- themselves successfully executed. <a href="#refsSQL">[SQL]</a></p>
+ <li>
+ <p>The user agent must then add the specified SQL statement to
+ <var title="">transaction</var>, and must execute it as soon as
+ all the statements that were added to that transaction before it
+ have themselves successfully executed. <a
+ href="#refsSQL">[SQL]</a></p>
+
+ <p>If the <code>Database</code> object has an <span>expected
+ version</span> that is neither the empty string nor the actual
+ version of the database, the statement must fail.</p>
+
+ </li>
+
<li><p>Once the statement has executed, let <var
title="">result</var> be a new <code>ResultSet</code> object that
represents the result of this statement's execution.</p></li>
@@ -27410,6 +27441,10 @@
title="">transaction</var> must be rolled back and marked as
"bad".</p></li>
+ <li><p>If <var title="">transaction</var> is not marked as "bad"
+ and has no pending statements in it, then the transaction it
+ represents must be commited.</p></li>
+
</ol>
<p>The <dfn
@@ -27455,8 +27490,9 @@
<h4>Database query results</h4>
- <p>Calls to the <code title="dom-executeSql">executeSql()</code>
- method return <code>ResultSet</code> objects.</p>
+ <p>Calls to the <code
+ title="dom-database-executeSql">executeSql()</code> method return
+ <code>ResultSet</code> objects.</p>
<pre class="idl">interface <dfn>ResultSet</dfn> {
// cursor
@@ -27556,14 +27592,23 @@
<th>Code
<th>Situation
<tbody>
+
<tr>
<td>0
<td>The statement was successful, any data available will be
returned by the other methods and attributes of the
<code>ResultSet</code> object.
+
<tr>
<td>1
- <td>The statement failed.
+ <td>The statement failed for reasons not covered by any other code.
+
+ <tr>
+ <td>2
+ <td>The statement failed because the <span>expected
+ version</span> of the database didn't match the actual database
+ version.
+
</table>
<p class="big-issue">We should define a more thorough list of
@@ -27624,8 +27669,8 @@
<p>Authors are strongly recommended to make use of the <code
title="">?</code> placeholder feature of the <code
- title="dom-executeSql">executeSql()</code> method, and to never
- construct SQL statements on the fly.</p>
+ title="dom-database-executeSql">executeSql()</code> method, and to
+ never construct SQL statements on the fly.</p>
More information about the Commit-Watchers
mailing list