[html5] r1023 - /
whatwg at whatwg.org
whatwg at whatwg.org
Fri Sep 21 19:08:08 PDT 2007
Author: ianh
Date: 2007-09-21 19:08:07 -0700 (Fri, 21 Sep 2007)
New Revision: 1023
Modified:
index
source
Log:
[] (0) Introduce transactions and error handling to the SQL feature.
Modified: index
===================================================================
--- index 2007-09-21 23:29:12 UTC (rev 1022)
+++ index 2007-09-22 02:08:07 UTC (rev 1023)
@@ -22,7 +22,7 @@
<h1 id=html-5>HTML 5</h1>
- <h2 class="no-num no-toc" id=working>Working Draft — 21 September
+ <h2 class="no-num no-toc" id=working>Working Draft — 22 September
2007</h2>
<p>You can take part in this work. <a
@@ -29876,48 +29876,103 @@
names (e.g. using a hashing algorithm) to the supported set of names.
<pre class=idl>interface <dfn id=database0>Database</dfn> {
- <a href="#resultset">ResultSet</a> <a href="#executesql" title=dom-executeSql>executeSql</a>(in DOMString sqlStatement, <var title="">arguments...</var>);
+ void <span title=dom-database-executeSql>executeSql</span>(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
+};
+
+interface <dfn id=sqlcallback>SQLCallback</dfn> {
+ void <span title=dom-sqlcallback-handleEvent>handleEvent</span>(in <a href="#resultset">ResultSet</a> resultSet);
};</pre>
<h4 id=executing><span class=secno>4.12.3. </span>Executing SQL statements</h4>
- <p class=big-issue>There are two major missing features here: One: a way to
- be secure against DNS spoofing (a database created over an SSL connection
- covered by one cert should not be made accessible to content connecting
- with another cert or with no cert). Two: there's no session-specific API,
- so if you have two windows open at once, you can't interact with the site
- doing two separate sessions unless the site goes out of its way to track
- sessions itself, detecting when new tabs are opened, etc. sessionStorage[]
- handles it, why doesn't this? Also, we need to be more explicit about disk
- usage concerns, quota, etc. Some of the security notes from
- globalStorage[] should maybe come down here.
+ <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.
- <p>Each <a href="#origin0">origin</a> must have an associated database
- unique to that origin. An author can interact with the database using the
- <code title=dom-executeSql><a href="#executesql">executeSql()</a></code>
- method.
-
<p>When the <dfn id=executesql title=dom-executeSql><code>executeSql(<var
- title="">sqlStatement</var>, <var
- title="">arguments...</var>)</code></dfn> method is invoked, the user
- agent must first interpret the first argument to the method (<var
- title="">sqlStatement</var>) as an SQL statement, replacing any <code
- title="">?</code> placeholders in the statement with the values given in
- the subsequent arguments (<var title="">arguments...</var>), and must then
- evaluate the statement as an SQL statement in the context of the database
- of the <code><a href="#database0">Database</a></code> object on which the
- method was called. <a href="#refsSQL">[SQL]</a>
+ 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>If the <code title=dom-executeSql><a
- href="#executesql">executeSql()</a></code> method is called with a
- different number of arguments after the statement than there are
- placeholder <code title="">?</code> characters in the statement, then the
- method must raise a <code>SYNTAX_ERR</code> exception.
+ <ol>
+ <li>
+ <p>The first argument to the method (<var title="">sqlStatement</var>)
+ must be interpreted as an SQL statement, replacing any <code
+ title="">?</code> placeholders in the statement with the values given in
+ the subsequent arguments (<var title="">arguments...</var>).</p>
- <p>Otherwise, the method must return a <code><a
- href="#resultset">ResultSet</a></code> object representing the result of
- the operation.
+ <p>If the syntax of <var title="">sqlStatement</var> is not valid, then
+ the the method must raise a <code>SYNTAX_ERR</code> exception and abort
+ these steps.</p>
+ <p>If the number of <var title="">arguments...</var> is not equal to the
+ number of <code title="">?</code> placeholders in the statement, then
+ the method must raise a <code>SYNTAX_ERR<!-- XXX
+ is that the best exception? --></code>
+ exception and abort these steps.</p>
+
+ <li>
+ <p>If there is an active thread-global transaction, then let <var
+ title="">transaction</var> be that transaction. Otherwise, let begin a
+ new transaction and let <var title="">transaction</var> be that
+ transaction.
+
+ <li>
+ <p>If <var title="">transaction</var> has been marked as "bad", then
+ raise an <code>INVALID_STATE_ERR</code> exception.
+
+ <li>
+ <p>The method must then return, but these steps must continue.
+
+ <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>Once the statement has executed, let <var title="">result</var> be a
+ new <code><a href="#resultset">ResultSet</a></code> object that
+ represents the result of this statement's execution.
+
+ <li>
+ <p>If the statement execution fails for some reason, <var
+ title="">transaction</var> must be rolled back and marked as "bad".
+
+ <li>
+ <p>The <var title="">transaction</var> must be set as the active
+ thread-global transaction.
+
+ <li>
+ <p>The <var title="">callback</var> must be invoked with <var
+ title="">result</var> as the argument.
+
+ <li>
+ <p>The active thread-global transaction must be removed again (if it is
+ still active).
+
+ <li>
+ <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".
+ </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.
+
+ <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
+ exception.
+
<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 filesystem will fail.
@@ -29959,6 +30014,8 @@
// general result accessors
readonly attribute int <a href="#insertid" title=dom-ResultSet-insertId>insertId</a>;
+ readonly attribute unsigned int <a href="#errorcode" title=dom-ResultSet-errorCode>errorCode</a>;
+ readonly attribute DOMString <a href="#error2" title=dom-ResultSet-error>error</a>;
};</pre>
<p>A <code><a href="#resultset">ResultSet</a></code> object has a cursor
@@ -30028,6 +30085,51 @@
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=errorcode
+ title=dom-ResultSet-errorCode><code>errorCode</code></dfn> DOM attribute
+ must return the most appropriate code from the following table:
+
+ <table>
+ <thead>
+ <tr>
+ <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><a
+ href="#resultset">ResultSet</a></code> object.
+
+ <tr>
+ <td>1
+
+ <td>The statement failed.
+ </table>
+
+ <p class=big-issue>We should define a more thorough list of codes.
+ Implementation feedback is requested to determine what codes are needed.
+
+ <p>The <dfn id=error2 title=dom-ResultSet-error><code>error</code></dfn>
+ DOM attribute must return an error message, localised to the user's
+ language, describing the error encountered by the last statement. If there
+ was no error, the attribute's value must be the empty string.
+
+ <p>If the statement failed, then <code title=dom-ResultSet-validRow><a
+ href="#validrow">validRow</a></code>, <code title=dom-ResultSet-next><a
+ href="#next0">next()</a></code>, <code title=dom-ResultSet-length><a
+ href="#length8">length</a></code>, <code title=dom-ResultSet-getName><a
+ href="#getname">getName()</a></code>, <code title=dom-ResultSet-item><a
+ href="#itemfield">item()</a></code>, <code
+ title=dom-ResultSet-namedItem><a href="#nameditem3">namedItem()</a></code>
+ and <code title=dom-ResultSet-insertId><a
+ href="#insertid">insertId</a></code> must all raise <code
+ title="">INVALID_STATE_ERR</code> exceptions on getting, setting, or
+ calling (as appropriate).
+
<h4 id=privacy><span class=secno>4.12.5. </span>Privacy</h4>
<p>In contrast with the <code title=dom-globalStorage><a
Modified: source
===================================================================
--- source 2007-09-21 23:29:12 UTC (rev 1022)
+++ source 2007-09-22 02:08:07 UTC (rev 1023)
@@ -27330,49 +27330,105 @@
the supported set of names.</p>
<pre class="idl">interface <dfn>Database</dfn> {
- <span>ResultSet</span> <span title="dom-executeSql">executeSql</span>(in DOMString sqlStatement, <var title="">arguments...</var>);
+ 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
+};
+
+interface <dfn>SQLCallback</dfn> {
+ void <span title="dom-sqlcallback-handleEvent">handleEvent</span>(in <span>ResultSet</span> resultSet);
};</pre>
<h4>Executing SQL statements</h4>
- <p class="big-issue">There are two major missing features here: One:
- a way to be secure against DNS spoofing (a database created over an
- SSL connection covered by one cert should not be made accessible to
- content connecting with another cert or with no cert). Two: there's
- no session-specific API, so if you have two windows open at once,
- you can't interact with the site doing two separate sessions unless
- the site goes out of its way to track sessions itself, detecting
- when new tabs are opened, etc. sessionStorage[] handles it, why
- doesn't this? Also, we need to be more explicit about disk usage
- concerns, quota, etc. Some of the security notes from
- globalStorage[] should maybe come down here.</p>
+ <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>
- <p>Each <span>origin</span> must have an associated database unique
- to that origin. An author can interact with the database using the
- <code title="dom-executeSql">executeSql()</code> method.</p>
-
<p>When the <dfn title="dom-executeSql"><code>executeSql(<var
- title="">sqlStatement</var>, <var
- title="">arguments...</var>)</code></dfn> method is invoked, the
- user agent must first interpret the first argument to the method
- (<var title="">sqlStatement</var>) as an SQL statement, replacing
- any <code title="">?</code> placeholders in the statement with the
- values given in the subsequent arguments (<var
- title="">arguments...</var>), and must then evaluate the statement
- as an SQL statement in the context of the database of the
- <code>Database</code> object on which the method was called. <a
- href="#refsSQL">[SQL]</a></p>
+ 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>
- <p>If the <code title="dom-executeSql">executeSql()</code> method is
- called with a different number of arguments after the statement than
- there are placeholder <code title="">?</code> characters in the
- statement, then the method must raise a <code>SYNTAX_ERR</code>
- exception.</p>
+ <ol>
- <p>Otherwise, the method must return a <code>ResultSet</code> object
- representing the result of the operation.</p>
+ <li>
+ <p>The first argument to the method (<var
+ title="">sqlStatement</var>) must be interpreted as an SQL
+ statement, replacing any <code title="">?</code> placeholders in
+ the statement with the values given in the subsequent arguments
+ (<var title="">arguments...</var>).</p>
+
+ <p>If the syntax of <var title="">sqlStatement</var> is not valid,
+ then the the method must raise a <code>SYNTAX_ERR</code> exception
+ and abort these steps.</p>
+
+ <p>If the number of <var title="">arguments...</var> is not equal
+ to the number of <code title="">?</code> placeholders in the
+ statement, then the method must raise a <code>SYNTAX_ERR<!-- XXX
+ is that the best exception? --></code> exception and abort these
+ steps.</p>
+
+ </li>
+
+ <li><p>If there is an active thread-global transaction, then let
+ <var title="">transaction</var> be that transaction. Otherwise, let
+ begin a new transaction and let <var title="">transaction</var> be
+ that transaction.</p></li>
+
+ <li><p>If <var title="">transaction</var> has been marked as "bad",
+ then raise an <code>INVALID_STATE_ERR</code> exception.</p></li>
+
+ <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>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>
+
+ <li><p>If the statement execution fails for some reason, <var
+ title="">transaction</var> must be rolled back and marked as
+ "bad".</p></li>
+
+ <li><p>The <var title="">transaction</var> must be set as the
+ active thread-global transaction.</p></li>
+
+ <li><p>The <var title="">callback</var> must be invoked with <var
+ title="">result</var> as the argument.</p></li>
+
+ <li><p>The active thread-global transaction must be removed again
+ (if it is still active).</p></li>
+
+ <li><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".</p></li>
+
+ </ol>
+
+ <p>The <dfn
+ 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.</p>
+
+ <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 exception.</p>
+
+
<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 filesystem will
@@ -27415,6 +27471,8 @@
// general result accessors
readonly attribute int <span title="dom-ResultSet-insertId">insertId</span>;
+ readonly attribute unsigned int <span title="dom-ResultSet-errorCode">errorCode</span>;
+ readonly attribute DOMString <span title="dom-ResultSet-error">error</span>;
};</pre>
<p>A <code>ResultSet</code> object has a cursor which visits the
@@ -27487,6 +27545,49 @@
<code>INVALID_ACCESS_ERR</code> exception.</p>
+ <p>The <dfn
+ title="dom-ResultSet-errorCode"><code>errorCode</code></dfn> DOM
+ attribute must return the most appropriate code from the following
+ table:</p>
+
+ <table>
+ <thead>
+ <tr>
+ <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.
+ </table>
+
+ <p class="big-issue">We should define a more thorough list of
+ codes. Implementation feedback is requested to determine what codes
+ are needed.</p>
+
+ <p>The <dfn title="dom-ResultSet-error"><code>error</code></dfn> DOM
+ attribute must return an error message, localised to the user's
+ language, describing the error encountered by the last statement. If
+ there was no error, the attribute's value must be the empty
+ string.</p>
+
+ <p>If the statement failed, then <code
+ title="dom-ResultSet-validRow">validRow</code>, <code
+ title="dom-ResultSet-next">next()</code>, <code
+ title="dom-ResultSet-length">length</code>, <code
+ title="dom-ResultSet-getName">getName()</code>, <code
+ title="dom-ResultSet-item">item()</code>, <code
+ title="dom-ResultSet-namedItem">namedItem()</code> and <code
+ title="dom-ResultSet-insertId">insertId</code> must all raise <code
+ title="">INVALID_STATE_ERR</code> exceptions on getting, setting, or
+ calling (as appropriate).</p>
+
+
<h4>Privacy</h4>
<p>In contrast with the <code
More information about the Commit-Watchers
mailing list