hixie: Simplify the intro example based on recent changes. Tweak the way the new creation callback is defined to make it safer in race conditions. Let changeVersion()'s success callback be omitted. (whatwg r3653)

hixie: Simplify the intro example based on recent changes. Tweak the way
the new creation callback is defined to make it safer in race
conditions. Let changeVersion()'s success callback be omitted. (whatwg
r3653)

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

===================================================================
RCS file: /sources/public/html5/webdatabase/Overview.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -d -r1.16 -r1.17
--- Overview.html 18 Aug 2009 04:39:47 -0000 1.16
+++ Overview.html 18 Aug 2009 05:00:18 -0000 1.17
@@ -293,41 +293,11 @@
   section function, <code title="">getDatabase()</code>, which obtains
   a handle to the database, and then calls the function to do the
   actual work, in this case <code title="">showDocCount()</code>.<pre>function prepareDatabase(ready, error) {
-  // first open the database with no version to see if it exists
-  var db = openDatabase('documents', '', 'Offline document storage', 5*1024*1024);
-  if (db.version == '') {
-    // database didn't exist
+  return openDatabase('documents', '1.0', 'Offline document storage', 5*1024*1024, function (db) {
     db.changeVersion('', '1.0', function (t) {
-      // create the tables
       t.executeSql('CREATE TABLE docids (id, name)');
-    }, function (e) {
-      // in case of error:
-      if (db.version == '1.0') {
-        // the database got upgraded while we were trying to do it.
-        // (there's a race condition between us checking db.version and
-        // calling changeVersion(), so this is possible if the user opened this
-        // page twice at the same time)
-        // let's try reopening it
-        getDatabase(ready, error);
-      } else {
-        // some other error occurred
-        error(e);
-      }
-    }, function () {
-      // in case of success:
-      getDatabase(ready, error);
-    });
-  } else {
-    getDatabase(ready, error);
-  }
-}
-
-function getDatabase(ready, error) {
-  try {
-    ready(openDatabase('documents', '1.0', 'Offline document storage', 5*1024*1024);
-  } catch (e) {
-    error(e);
-  }
+    }, error);
+  });
 }
 
 function showDocCount(db, span) {
@@ -437,9 +407,13 @@
   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>
+  the database has not yet been created. The callback, if provided, is
+  intended to be used to call <code title="dom-database-changeVersion"><a href="#dom-database-changeversion">changeVersion()</a></code>; the
+  callback is invoked with the database having the empty string as its
+  version regardless of the given database version. If the callback is
+  not provided, the database is created with the given database
+  version as its version.<p>When invoked, these methods must run the following steps, with all
+  but the last two steps being run atomically:<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
@@ -470,10 +444,12 @@
 
    <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>
+    <p>If no database with the given name from the origin <var title="">origin</var> exists, then create the database and let
+    <var title="">created</var> be true. Otherwise, let <var title="">created</var> be false.</p>
+
+    <p>If a callback was passed to the method, then let the database's
+    version be the empty string. Otherwise, let its version be the
+    given database version</p>
 
    </li>
 
@@ -610,7 +586,7 @@
   void <a href="#dom-database-readtransaction" title="dom-database-readTransaction">readTransaction</a>(in <a href="#sqltransactioncallback">SQLTransactionCallback</a> callback, optional in <a href="#sqltransactionerrorcallback">SQLTransactionErrorCallback</a> errorCallback, optional in <a href="#sqlvoidcallback">SQLVoidCallback</a> successCallback);
 
   readonly attribute DOMString <a href="#dom-database-version" title="dom-database-version">version</a>;
-  void <a href="#dom-database-changeversion" title="dom-database-changeVersion">changeVersion</a>(in DOMString oldVersion, in DOMString newVersion, in <a href="#sqltransactioncallback">SQLTransactionCallback</a> callback, in <a href="#sqltransactionerrorcallback">SQLTransactionErrorCallback</a> errorCallback, in <a href="#sqlvoidcallback">SQLVoidCallback</a> successCallback);
+  void <a href="#dom-database-changeversion" title="dom-database-changeVersion">changeVersion</a>(in DOMString oldVersion, in DOMString newVersion, in <a href="#sqltransactioncallback">SQLTransactionCallback</a> callback, in <a href="#sqltransactionerrorcallback">SQLTransactionErrorCallback</a> errorCallback, in optional <a href="#sqlvoidcallback">SQLVoidCallback</a> successCallback);
 };
 
 [Callback=FunctionOnly, NoInterfaceObject]

Received on Tuesday, 18 August 2009 05:01:16 UTC