hixie: Add a feature to openDatabase() to make creating the database the first time way easier. (whatwg r3652)

hixie: Add a feature to openDatabase() to make creating the database the
first time way easier. (whatwg r3652)

http://dev.w3.org/cvsweb/html5/webdatabase/Overview.html?r1=1.15&r2=1.16&f=h
http://html5.org/tools/web-apps-tracker?from=3651&to=3652

===================================================================
RCS file: /sources/public/html5/webdatabase/Overview.html,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -d -r1.15 -r1.16
--- Overview.html 18 Aug 2009 02:57:58 -0000 1.15
+++ Overview.html 18 Aug 2009 04:39:47 -0000 1.16
@@ -416,52 +416,112 @@
   another browser window) trying to write to a database with incorrect
   assumptions.<pre class="idl">[Supplemental, NoInterfaceObject]
 interface <span>WindowDatabase</span> {
-  <a href="#database">Database</a> <a href="#dom-opendatabase" title="dom-opendatabase">openDatabase</a>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize);
+  <a href="#database">Database</a> <a href="#dom-opendatabase" title="dom-opendatabase">openDatabase</a>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize, in optional <a href="#databasecallback">DatabaseCallback</a> creationCallback);
 };
 <span>Window</span> implements <span>WindowDatabase</span>;
 
 [Supplemental, NoInterfaceObject]
 interface <span>WorkerUtilsDatabase</span> {
-  <a href="#database">Database</a> <a href="#dom-opendatabase" title="dom-opendatabase">openDatabase</a>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize);
-  <a href="#databasesync">DatabaseSync</a> <a href="#dom-opendatabase-sync" title="dom-opendatabase-sync">openDatabaseSync</a>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize);
+  <a href="#database">Database</a> <a href="#dom-opendatabase" title="dom-opendatabase">openDatabase</a>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize, in optional <a href="#databasecallback">DatabaseCallback</a> creationCallback);
+  <a href="#databasesync">DatabaseSync</a> <a href="#dom-opendatabase-sync" title="dom-opendatabase-sync">openDatabaseSync</a>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize, in optional <a href="#databasecallback">DatabaseCallback</a> creationCallback);
 };
-<span>WorkerUtils</span> implements <span>WorkerUtilsDatabase</span>;</pre><p>The <dfn id="dom-opendatabase" title="dom-opendatabase"><code>openDatabase()</code></dfn> method on
-  the <code>Window</code> and <code>WorkerUtils</code> interfaces must
-  return a newly constructed <code><a href="#database">Database</a></code> object that
-  represents the database requested.<p>The <dfn id="dom-opendatabase-sync" title="dom-opendatabase-sync"><code>openDatabaseSync()</code></dfn>
-  method on the <code>WorkerUtils</code> interfaces must return a
-  newly constructed <code><a href="#databasesync">DatabaseSync</a></code> object that represents
-  the database requested.<p>These methods take four arguments: a database name, a database
-  version, a display name, and an estimated size, in bytes, of the
-  data that will be stored in the database.<p>The database requested is the one with the given database
-  name from the appropriate <span>origin</span>.<p>The <code title="dom-opendatabase"><a href="#dom-opendatabase">openDatabase()</a></code> method
-  on the <code>Window</code> object must use and create databases from
-  the <span>origin</span> of the <span>active document</span> of the
-  <span>browsing context</span> of the <code>Window</code> object on
-  which the method was invoked.<p>The <code title="dom-opendatabase"><a href="#dom-opendatabase">openDatabase()</a></code> and
-  <code title="dom-opendatabase-sync"><a href="#dom-opendatabase-sync">openDatabaseSync()</a></code>
-  methods on the <code>WorkerUtils</code> object must use and create
-  databases from the <span>origin</span> of the scripts in the
-  worker.<p>All strings including the empty string are valid database
+<span>WorkerUtils</span> implements <span>WorkerUtilsDatabase</span>;
+
+[Callback=FunctionOnly, NoInterfaceObject]
+interface <dfn id="databasecallback">DatabaseCallback</dfn> {
+  void <span title="dom-databasecallback-handleEvent">handleEvent</span>(in <a href="#database">Database</a> database);
+};</pre><p>The <dfn id="dom-opendatabase" title="dom-opendatabase"><code>openDatabase()</code></dfn> method on
+  the <code>Window</code> and <code>WorkerUtils</code> interfaces and
+  the <dfn id="dom-opendatabase-sync" title="dom-opendatabase-sync"><code>openDatabaseSync()</code></dfn>
+  method on the <code>WorkerUtils</code> interface take the following
+  arguments: a database name, a database version, a display name, an
+  estimated size &mdash; in bytes &mdash; of the data that will be
+  stored in the database, and optionally a callback to be invoked if
+  the database has not yet been created.</p>
+
+  When invoked, these methods must run the following steps:<ol><li>
+
+    <p>The user agent may raise a <code>SECURITY_ERR</code> exception
+    instead of returning a <code><a href="#database">Database</a></code> object if the request
+    violates a policy decision (e.g. if the user agent is configured
+    to not allow the page to open databases).</p>
+
+   </li>
+
+   <li>
+
+    <p>For the method on the <code>Window</code> object: let <var title="">origin</var> be the <span>origin</span> of the
+    <span>active document</span> of the <span>browsing context</span>
+    of the <code>Window</code> object on which the method was
+    invoked.</p>
+
+    <p>For the methods on the <code>WorkerUtils</code> object: let
+    <var title="">origin</var> be the <span>origin</span> of the
+    scripts in the worker.</p>
+
+   </li>
+
+   <li><p>If the database version provided is not the empty string,
+   and there is already a database with the given name from the origin
+   <var title="">origin</var>, but the database has a different
+   version than the version provided, then throw an
+   <code>INVALID_STATE_ERR</code> exception and abort these
+   steps.</li>
+
+   <li>
+
+    <p>If no database with the given name from the origin <var title="">origin</var> exists, then create the database, let its
+    version be the given database version (which might be the empty
+    string), and let <var title="">created</var> be true. Otherwise,
+    let <var title="">created</var> be false.</p>
+
+   </li>
+
+   <li>
+
+    <p>For the <code title="dom-opendatabase"><a href="#dom-opendatabase">openDatabase()</a></code>
+    methods: let <var title="">result</var> be a newly constructed
+    <code><a href="#database">Database</a></code> object representing the database with the
+    given database name from the origin <var title="">origin</var>.</p>
+
+    <p>For the <code title="dom-opendatabase-sync"><a href="#dom-opendatabase-sync">openDatabaseSync()</a></code> method:
+    let <var title="">result</var> be a newly constructed
+    <code><a href="#databasesync">DatabaseSync</a></code> object representing the database with
+    the given database name from the origin <var title="">origin</var>.</p>
+
+   </li>
+
+   <li>
+
+    <p>If <var title="">created</var> is false or if no callback was
+    passed to the method, skip this step. Otherwise:</p>
+
+    <p>For the <code title="dom-opendatabase"><a href="#dom-opendatabase">openDatabase()</a></code>
+    methods: <span>queue a task</span> to to invoke the callback with
+    <var title="">result</var> as its only argument.</p>
+
+    <p>For the <code title="dom-opendatabase-sync"><a href="#dom-opendatabase-sync">openDatabaseSync()</a></code> method:
+    invoke the callback with <var title="">result</var> as its only
+    argument. If the callback throws an exception, rethrow that
+    exception and abort these steps.</p>
+
+   </li>
+
+   <li>
+
+    <p>Return <var title="">result</var>.</p>
+
+   </li>
+
+  </ol><p>All strings including the empty string are valid database
   names. Database names must be compared in a
   <span>case-sensitive</span> manner.<p class="note">Implementations can support this even in
   environments that 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>If the database version provided is not the empty string, and the
-  database already exists but has a different version, or no version,
-  then the method must raise an <code>INVALID_STATE_ERR</code>
-  exception.<p>The version that the database was opened with is the <dfn id="concept-database-expected-version" title="concept-database-expected-version">expected version</dfn> of
+  the supported set of names.<p>The version that the database was opened with is the <dfn id="concept-database-expected-version" title="concept-database-expected-version">expected version</dfn> of
   this <code><a href="#database">Database</a></code> or <code><a href="#databasesync">DatabaseSync</a></code> object. It
   can be the empty string, in which case there is no expected version
-  &mdash; any version is fine.<p>Otherwise, if the database version provided is the empty string,
-  or if the database doesn't yet exist, or if the database exists and
-  the version requested is the same as the current version associated
-  with the database, then the method must return an object
-  representing the database that has the name that was given. If no
-  such database exists, it must be created first.<p>The user agent may raise a <code>SECURITY_ERR</code> exception
-  instead of returning a <code><a href="#database">Database</a></code> object if the request
-  violates a policy decision (e.g. if the user agent is configured to
-  not allow the page to open databases).<p>User agents are expected to use the display name and the
+  &mdash; any version is fine.<p>User agents are expected to use the display name and the
   estimated database size to optimize the user experience. For
   example, a user agent could use the estimated size to suggest an
   initial quota to the user. This allows a site that is aware that it

Received on Tuesday, 18 August 2009 04:40:49 UTC