mozilla

Revision 298236 of IDBRequest

  • Revision slug: IndexedDB/IDBRequest
  • Revision title: IDBRequest
  • Revision id: 298236
  • Created:
  • Creator: scottrowe
  • Is current revision? No
  • Comment

Revision Content

The IDBRequest interface of the IndexedDB API provides access to results of asynchronous requests to databases and database objects using event handler attributes. Each reading and writing operation on a database is done using a request.

The request object does not initially contain any information about the result of the operation, but once information becomes available, an event is fired on the request, and the information becomes available through the properties of the IDBRequest instance.

Inherits from: EventTarget

About this document

This document was last updated on August 17, 2012 and follows the W3C Specifications (Editor's Draft) drafted on July 24, 2012. It has not yet been verified.

Basic concepts

All asynchronous operations immediately return an IDBRequest instance. Each request has a readyState that is set to the pending state, which then changes to done when the request is completed or fails. When the state is set to done, every request returns a result and an error, and an event is fired on the request. When the state is still pending, any attempt to access the result or error raises an InvalidStateError exception.

All that is saying in plain English is that: All asynchronous methods return a request object. If the request has been completed successfully, the result is made available through the result property and an event indicating success is fired at the request. If an error occurs while performing the operation, the exception is made available through the result property and an error event is fired.

Example

In the following code snippet, we open a database asynchronously and make a request. Event handlers are registered for responding to various situations.

var request = window.indexedDB.open('Database Name');
request.onsuccess = function(event) {
        var db = this.result;
        var transaction = db.transaction([], IDBTransaction.READ_ONLY);
        var curRequest = transaction.objectStore('ObjectStore Name').openCursor();
        curRequest.onsuccess = ...;
    };
request.onerror = function(event) {
         ...;
    };

Attributes

Attribute Type Description
result readonly any

Returns the result of the request.

If the the request failed and the result is not available, the InvalidStateError exception is thrown.

error readonly DOMError

The following error codes are returned under certain conditions:

  • AbortError — If you abort the transaction, then all requests still in progress receive this error.
  • ConstraintError — If you insert data that doesn't conform to a constraint. It's an exception type for creating stores and indexes. You get this error, for example, if you try to add a new key that already exists in the record.
  • QuotaExceededError — If you run out of disk quota and the user declined to grant you more space.
  • UnknownError — If the operation failed for reasons unrelated to the database itself. A failure due to disk IO errors is such an example.
  • NoError — If the request succeeds.
  • VersionError — If you try to open a database with a version lower than the one it already has.

In addition to the error codes sent to the IDBRequest object, asynchronous operations can also raise exceptions. The list describes problems that could occur when the request is being executed, but you might also encounter other problems when the request is being made. For example, if the the request failed and the result is not available, the InvalidStateError exception is thrown.

source readonly Object

The source of the request, such as an Index or a ObjectStore. If no source exists (such as when calling indexedDB.open()), it returns null.

transaction readonly IDBTransaction The transaction for the request. This property can be null for certain requests, such as for request returned from IDBFactory.open (You're just connecting to a database, so there is no transaction to return).
readyState readonly enum

The state of the request. Every request starts in the pending state. The state changes to done when the request completes successfully or when an error occurs.

onerror Function The event handler for the error event.
onsuccess Function The event handler for the success event.

Constants

readyState constants

Constant Value Description
done 2 The request has completed or an error has occurred. Initially false
pending 1 The request has been started, but its result is not yet available.

Event handlers

Event handler Event handler type
onerror error
onsuccess success

Derived interface

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 12 {{ property_prefix("-webkit") }} {{ CompatGeckoDesktop("2.0") }} {{ CompatNo() }} {{ CompatNo() }} {{ CompatNo() }}
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support {{ CompatNo() }} {{ CompatGeckoMobile("6.0") }} {{ CompatUnknown() }} {{ CompatNo() }} {{ CompatNo() }}

 

Revision Source

<p>The <code>IDBRequest</code> interface of the IndexedDB&nbsp;API provides access to results of asynchronous requests to databases and database objects using event handler attributes. Each reading and writing operation on a database is done using a request.</p>
<p>The request object does not initially contain any information about the result of the operation, but once information becomes available, an event is fired on the request, and the information becomes available through the properties of the <code>IDBRequest</code> instance.</p>
<p>Inherits from: <a href="/en/DOM/EventTarget" title="en/DOM/EventTarget">EventTarget</a></p>
<h2 id="About_this_document">About this document</h2>
<p>This document was last updated on August 17, 2012 and follows the <a class="external" href="http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html#request-api">W3C Specifications (Editor's Draft)</a> drafted on July 24, 2012. It has not yet been verified.</p>
<h2 id="Basic_concepts">Basic concepts</h2>
<p>All asynchronous operations immediately return an <code>IDBRequest</code> instance. Each request has a <code><a href="#readyState">readyState</a></code> that is set to the <a href="#const_pending" title="#const_pending"><font face="Courier New, Andale Mono, monospace"><span style="line-height: normal;">pending</span></font></a>&nbsp;state, which then changes to <code><a href="#const_done">d</a>one</code> when the request is completed or fails. When the state is set to <code>done</code>, every request returns a&nbsp;<a href="/en/IndexedDB/IDBRequest?revision=11#attr_result" title="en/IndexedDB/IDBRequest?revision=11#attr_result"><code>result</code></a>&nbsp;and an&nbsp;<a href="/en/IndexedDB/IDBRequest?revision=11#attr_errorCode" title="en/IndexedDB/IDBRequest?revision=11#attr_errorCode"><code>error</code></a>, and an event is fired on the request. When the state is still <code>pending</code>, any attempt to access the <code>result</code> or <code>error</code>&nbsp;raises an <code>InvalidStateError</code>&nbsp;exception.</p>
<p>All that is saying in plain English is that: All asynchronous methods return a request object. If the request has been completed successfully, the result is made available through the <code>result</code> property and an event indicating success is fired at the request. If an error occurs while performing the operation, the exception is made available through the <code>result</code> property and an error event is fired.</p>
<h3 id="Example">Example</h3>
<p>In the following code snippet, we open a database asynchronously and make a request. Event handlers are registered for responding to various situations.</p>
<pre class="brush: js">
var request = window.indexedDB.open('Database Name');
request.onsuccess = function(event) {
        var db = this.result;
        var transaction = db.transaction([], IDBTransaction.READ_ONLY);
        var curRequest = transaction.objectStore('ObjectStore Name').openCursor();
        curRequest.onsuccess = ...;
    };
request.onerror = function(event) {
         ...;
    };
</pre>
<h2 id="Attributes">Attributes</h2>
<table class="standard-table">
  <thead>
    <tr>
      <th scope="col" width="145">Attribute</th>
      <th scope="col" width="209">Type</th>
      <th scope="col" width="842">Description</th>
    </tr>
    <tr>
      <td><code><a name="attr_result">result</a></code></td>
      <td><code>readonly any</code></td>
      <td>
        <p>Returns the result of the request.</p>
        <p>If the the request failed and the result is not available, the&nbsp;<span style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal; ">InvalidStateError</span>&nbsp;exception is thrown.</p>
      </td>
    </tr>
    <tr>
      <td><code><a name="attr_errorCode">error</a></code></td>
      <td><code>readonly&nbsp;<a href="/en-US/docs/DOM/DOMError" style="color: rgb(34, 85, 170); line-height: 21px; " title="/en-US/docs/DOM/DOMError">DOMError</a></code></td>
      <td>
        <p>The following error codes are returned under certain conditions:</p>
        <ul>
          <li><code>AbortError</code>&nbsp;— If you abort the transaction, then all requests still in progress receive this error.</li>
          <li><code>ConstraintError</code> — If you insert data that doesn't conform to a constraint. It's an&nbsp;exception type for creating stores and indexes.&nbsp;You get this error, for example, if you try to add a new key that already exists in the record.</li>
          <li><code>QuotaExceededError</code>&nbsp;— If you run out of disk quota and the user declined to grant you more space.</li>
          <li><code>UnknownError</code> — If the operation failed for reasons unrelated to the database itself. A failure due to disk IO errors is such an example.</li>
          <li><code>NoError</code> — If the request succeeds.</li>
          <li><code>VersionError</code>&nbsp;— If you try to open a database with a version lower than the one it already has.</li>
        </ul>
        <p>In addition to the error codes sent to the IDBRequest object, asynchronous operations can also raise exceptions. The list describes problems that could occur when the request is being executed, but you might also encounter other problems when the request is being made.&nbsp;For example, if the the request failed and the result is not available, the&nbsp;<span style="font-family: 'Courier New', 'Andale Mono', monospace; line-height: normal; ">InvalidStateError</span>&nbsp;exception is thrown.</p>
      </td>
    </tr>
    <tr>
      <td><code><a name="attr_source">source</a></code></td>
      <td><code>readonly Object</code></td>
      <td>
        <p>The source of the request, such as an Index or a ObjectStore. If no source exists (such as when calling <code>indexedDB.open()</code>), it returns null.</p>
      </td>
    </tr>
    <tr>
      <td><code><a name="attr_transaction">transaction</a></code></td>
      <td><code>readonly <a href="/en/IndexedDB/IDBTransaction" title="en/IndexedDB/IDBTransaction">IDBTransaction</a></code></td>
      <td>The transaction for the request. This property can be null for certain requests, such as for request returned from <code><a href="/en/IndexedDB/IDBFactory#open" title="en/IndexedDB/IDBFactory#open">IDBFactory.open</a></code> (You're just connecting to a database, so there is no transaction to return).</td>
    </tr>
    <tr>
      <td><code><a name="attr_readyState">readyState</a></code></td>
      <td><code>readonly enum</code></td>
      <td>
        <p>The state of the request. Every request starts in the <code>pending</code>&nbsp;state. The state changes to <code>done</code> when the request completes successfully or when an error occurs.</p>
        <!--<p>The <code>readyState</code> is set to <code>DONE</code> in two situations, with different outcomes:</p>
          <dl>
            <dt>If the request completes successfully,</dt>
            <dd>then the result of the request is included as the <code><a href="mks://localhost/en/IndexedDB/IDBSuccessEvent#attr_result" title="en/IndexedDB/IDBSuccessEvent#attr result">result</a></code> of a new <a href="mks://localhost/en/IndexedDB/IDBSuccessEvent" title="en/IndexedDB/IDBSuccessEvent">IDBSuccessEvent</a> object, which is queued to fire with the name <code>success</code>.</dd>
            <dt>If an error occurs,</dt>
            <dd>then the error code and message are included in a new <a href="mks://localhost/en/IndexedDB/IDBErrorEvent" title="en/IndexedDB/IDBErrorEvent">IDBErrorEvent</a> object, which is queued to fire with the name <code>error</code>.</dd>
          </dl>
          <p>The event fired in these situations has no namespace, does not bubble, and is not cancelable at each <a href="mks://localhost/en/DOM/window" title="en/DOM/window">window</a> object.</p>--></td>
    </tr>
    <tr>
      <td><code><a name="attr_onerror">onerror</a></code></td>
      <td><code>Function </code></td>
      <td>The event handler for the error event.</td>
    </tr>
    <tr>
      <td><code><a name="attr_onsuccess">onsuccess</a></code></td>
      <td><code>Function </code></td>
      <td>The event handler for the success event.</td>
    </tr>
  </thead>
  <tbody>
  </tbody>
</table>
<h2 id="Constants">Constants</h2>
<h3 id="readyState_constants">readyState constants</h3>
<table class="standard-table">
  <thead>
    <tr>
      <th scope="col" width="111">Constant</th>
      <th scope="col" width="53">Value</th>
      <th scope="col" width="690">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code><a name="const_done">done</a></code></td>
      <td>2</td>
      <td>The request has completed or an error has occurred. Initially false</td>
    </tr>
    <tr>
      <td><code><a name="const_pending">pending</a></code></td>
      <td>1</td>
      <td>The request has been started, but its result is not yet available.</td>
    </tr>
  </tbody>
</table>
<h2 id="Event_handlers">Event handlers</h2>
<table border="1" cellpadding="1" cellspacing="1" class="standard-table">
  <thead>
    <tr>
      <th scope="col" width="133">Event handler</th>
      <th scope="col" width="129">Event handler type</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>onerror </code></td>
      <td><code>error </code></td>
    </tr>
    <tr>
      <td><code>onsuccess </code></td>
      <td><code>success </code></td>
    </tr>
  </tbody>
</table>
<!--
<p>Any objects that implement this interface must support, as IDL attributes, the following event handlers and their corresponding event handler types:</p>
<table border="1" cellpadding="1" cellspacing="1" class="standard-table">
	<thead>
		<tr>
			<th scope="col">Event handler</th>
			<th scope="col">Event handler type</th>
			<th scope="col">Event interface(s)</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td><code>onerror<br />
				</code></td>
			<td><code>error<br />
				</code></td>
			<td><a href="mks://localhost/en/IndexedDB/IDBErrorEvent" title="en/IndexedDB/IDBErrorEvent">IDBErrorEvent</a></td>
		</tr>
		<tr>
			<td><code>onsuccess<br />
				</code></td>
			<td><code>success<br />
				</code></td>
			<td><a href="mks://localhost/en/IndexedDB/IDBSuccessEvent" title="en/IndexedDB/IDBSuccessEvent">IDBSuccessEvent</a>, <a href="mks://localhost/en/IndexedDB/IDBTransactionEvent" title="en/IndexedDB/IDBTransactionEvent">IDBTransactionEvent</a></td>
		</tr>
	</tbody>
</table> -->
<h2 id="Derived_interface">Derived interface</h2>
<ul>
  <li><code><a href="/en/IndexedDB/IDBOpenDBRequest" title="en/IndexedDB/IDBOpenDBRequest">IDBOpenDBRequest</a></code></li>
</ul>
<h2 id="Browser_Compatibility" name="Browser_Compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Chrome</th>
        <th>Firefox (Gecko)</th>
        <th>Internet Explorer</th>
        <th>Opera</th>
        <th>Safari (WebKit)</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>12 {{ property_prefix("-webkit") }}</td>
        <td>{{ CompatGeckoDesktop("2.0") }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE&nbsp;Phone</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatGeckoMobile("6.0") }}</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatNo() }}</td>
        <td>{{ CompatNo() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<p>&nbsp;</p>
Revert to this revision