Skip to content

Commit

Permalink
[] (0) Introduce transactions and error handling to the SQL feature.
Browse files Browse the repository at this point in the history 
git-svn-id: http://svn.whatwg.org/webapps@1023 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
@Hixie
Hixie committed Sep 22, 2007
1 parent df7f785 commit 4291cd7
Show file tree
Hide file tree
Showing 2 changed files with 273 additions and 70 deletions.
174 changes: 138 additions & 36 deletions index
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@

<h1 id=html-5>HTML 5</h1>

<h2 class="no-num no-toc" id=working>Working Draft &mdash; 21 September
<h2 class="no-num no-toc" id=working>Working Draft &mdash; 22 September
2007</h2>

<p>You can take part in this work. <a
Expand Down Expand Up @@ -29876,47 +29876,102 @@ interface <dfn id=storageitem>StorageItem</dfn> {
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>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>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>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>

<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.

<p>Otherwise, the method must return a <code><a
href="#resultset">ResultSet</a></code> object representing the result of
the operation.
title="">sqlStatement</var>, <var title="">arguments...</var>, <var
title="">callback</var>)</code></dfn> method is invoked, the user agent
must run the following algorithm:

<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>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
Expand Down Expand Up @@ -29959,6 +30014,8 @@ interface <dfn id=storageitem>StorageItem</dfn> {

// 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
Expand Down Expand Up @@ -30028,6 +30085,51 @@ interface <dfn id=storageitem>StorageItem</dfn> {
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
Expand Down
Loading

0 comments on commit 4291cd7

Please sign in to comment.