User talk:sdwilsh

  • Revision slug: User_talk:sdwilsh
  • Revision title: User talk:sdwilsh
  • Revision id: 165416
  • Created:
  • Creator: sdwilsh
  • Is current revision? No
  • Comment /* Async Storage Statements */ v3.0 of api

Revision Content

Async Storage Statements

This is loosely based off of the HTML 5 SQL spec. This is targeting Firefox 3.1 and whatever version of Gecko that will correlate with.

Sample Code

This is an attempt at some sample code on using async statements.

JavaScript
// conn is a mozIStorageConnection
let stmt = conn.createStatement("SELECT * FROM moz_downloads WHERE state = ?1");
stmt.bindInt32Parameter(0, Ci.nsIDownloadManager.DOWNLOAD_FINISHED);

stmt.executeAsync(
  {
    handleResult: function(aResult)
    {
      for (let row in aResult) {
        // process data
        // should be able to access data in a row by name or argument number
      }
    },
    handleError: function(aError)
    {
      // update UI accordingly
    }
  }
);
C++
class Listener : public Callback {
  NS_IMETHODIMP HandleResult(ResultSet aResult)
  {
    nsCOMPtr<mozIStorageValueArray> row;
    while (NS_SUCCEEDED(aResult->GetRow(row)) && row) {
      // do something with result
    }
  }

  NS_IMETHODIMP HandleError(SQLError aError)
  {
  }
};

// conn is a mozIStorageConnection
nsCOMPtr<mozIStorageStatement> stmt;
(void)conn->CreateStatement(NS_LITERAL_CSTRING(
  "SELECT * FROM moz_downloads WHERE state = ?1"), getter_AddRefs(stmt));
(void)stmt->BindInt32Parameter(0, nsIDownloadManager::DOWNLOAD_FINISHED);

(void)stmt->ExecuteAsync(new Listener());

Proposed Interface

This is a work in progress. Comments welcome.

mozIStorageStatement

These are necessary changes to the mozIStorageStatement interface.


void executeAsync([optional] in Callback aCallback);

Executes a prepared mozIStorageStatement and calls the callback (if provided) when a result is returned.

Callback

Interface handles some sort of callback on the calling thread. This does not have to be the main thread.

void handleResult(in ResultSet aResultSet);

Handles a successful execution of the statement. This function may be called more than once with a different ResultSet each time representing new data.

void handleError(in SQLError aError);

Handles an error of the statement.

ResultSet

Interface used to get the data back. In JS, this should be able to be used as an Iterator.

mozIStorageValueArray getNextResult();

Obtains the next tuple of results and advances the cursor. Null if no results available.

SQLError

Interface used to give information about an error.

TODO: What type of information do we want to give here?

Discussion

Please provide feedback in mozilla.dev.planning

Revision Source

<h3 name="Async_Storage_Statements"> Async Storage Statements </h3>
<p>This is loosely based off of the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/#executing">HTML 5 SQL spec</a>.  This is targeting Firefox 3.1 and whatever version of Gecko that will correlate with.
</p>
<h4 name="Sample_Code"> Sample Code </h4>
<p>This is an attempt at some sample code on using async statements.
</p>
<h5 name="JavaScript"> JavaScript </h5>
<pre>// conn is a mozIStorageConnection
let stmt = conn.createStatement("SELECT * FROM moz_downloads WHERE state = ?1");
stmt.bindInt32Parameter(0, Ci.nsIDownloadManager.DOWNLOAD_FINISHED);

stmt.executeAsync(
  {
    handleResult: function(aResult)
    {
      for (let row in aResult) {
        // process data
        // should be able to access data in a row by name or argument number
      }
    },
    handleError: function(aError)
    {
      // update UI accordingly
    }
  }
);
</pre>
<h5 name="C.2B.2B"> C++ </h5>
<pre>class Listener : public Callback {
  NS_IMETHODIMP HandleResult(ResultSet aResult)
  {
    nsCOMPtr&lt;mozIStorageValueArray&gt; row;
    while (NS_SUCCEEDED(aResult-&gt;GetRow(row)) &amp;&amp; row) {
      // do something with result
    }
  }

  NS_IMETHODIMP HandleError(SQLError aError)
  {
  }
};

// conn is a mozIStorageConnection
nsCOMPtr&lt;mozIStorageStatement&gt; stmt;
(void)conn-&gt;CreateStatement(NS_LITERAL_CSTRING(
  "SELECT * FROM moz_downloads WHERE state = ?1"), getter_AddRefs(stmt));
(void)stmt-&gt;BindInt32Parameter(0, nsIDownloadManager::DOWNLOAD_FINISHED);

(void)stmt-&gt;ExecuteAsync(new Listener());
</pre>
<h4 name="Proposed_Interface"> Proposed Interface </h4>
<p>This is a work in progress.  Comments welcome.
</p>
<h5 name="mozIStorageStatement"> mozIStorageStatement </h5>
<p>These are necessary changes to the <a href="en/MozIStorageStatement">mozIStorageStatement</a> interface.
</p><p><br>
<code>void executeAsync(<span class="plain">[optional]</span> in <a href="#Callback">Callback</a> aCallback);</code>
</p><p>Executes a prepared <a href="en/MozIStorageStatement">mozIStorageStatement</a> and calls the callback (if provided) when a result is returned.
</p>
<h5 name="Callback"> Callback </h5>
<p>Interface handles some sort of callback on the calling thread.  This does not have to be the main thread.
</p><p><code>void handleResult(in <a href="#ResultSet">ResultSet</a> aResultSet);</code>
</p><p>Handles a successful execution of the statement.  This function may be called more than once with a different <a href="#ResultSet">ResultSet</a> each time representing new data.
</p><p><code>void handleError(in <a href="#SQLError">SQLError</a> aError);</code>
</p><p>Handles an error of the statement.
</p>
<h5 name="ResultSet"> ResultSet </h5>
<p>Interface used to get the data back.  In JS, this should be able to be used as an Iterator.
</p><p><code><a href="en/MozIStorageValueArray">mozIStorageValueArray</a> getNextResult();</code>
</p><p>Obtains the next tuple of results and advances the cursor.  Null if no results available.
</p>
<h5 name="SQLError"> SQLError </h5>
<p>Interface used to give information about an error.
</p><p>TODO: What type of information do we want to give here?
</p>
<h4 name="Discussion"> Discussion </h4>
<p>Please provide feedback in <a class="external" href="http://groups.google.com/group/mozilla.dev.planning/browse_thread/thread/045fed0ecba487cc#">mozilla.dev.planning</a>
</p>
Revert to this revision