Clean up IDBKeyRange and the places it can/should be used. Also make .get() on index and objectStore use the proper algorithms as to define how their requests are executed. Fixes bugs 10396 and 10397.
authorJonas Sicking <jonas@sicking.cc>
Fri, 29 Oct 2010 16:16:24 -0700
changeset 74e5a08025e518
parent 73 26e7d99ab935
child 75 9cee20f99c8e
Clean up IDBKeyRange and the places it can/should be used. Also make .get() on index and objectStore use the proper algorithms as to define how their requests are executed. Fixes bugs 10396 and 10397.
Overview.html
Speclet_020_IDB_API_Constructs.html
Speclet_021_IDB_API_Algorithms.html
Speclet_023_IDB_API_Asynchronous_APIs.html
     1.1 --- a/Overview.html	Fri Oct 29 09:13:37 2010 -0700
     1.2 +++ b/Overview.html	Fri Oct 29 16:16:24 2010 -0700
     1.3 @@ -349,22 +349,29 @@
     1.4              In order to efficiently retrieve <a title="record">records</a> 
     1.5              stored in an indexed database, a user agent needs to organize each 
     1.6              <a>record</a> according to its key. <a>Conforming user agents</a>
     1.7 -            MUST support the use of the following values as keys: IDL data types
     1.8 -            <code>DOMString</code>, <code>long</code>, and <code>float</code> [[!WEBIDL]]; the <code>Date</code> JavaScript object [[!ECMA-262]]; as well as the value <code>null</code>.
     1.9 +            MUST support the use of the following types as <dfn>key value</dfn>s: IDL data types
    1.10 +            <code>DOMString</code>, <code>long</code>, and <code>float</code> [[!WEBIDL]]; the
    1.11 +            <code>Date</code> JavaScript object [[!ECMA-262]]; as well as the value <code>null</code>.
    1.12 +            For the particular case of <code>float</code>, the value NaN is not allowed.
    1.13            </p>
    1.14 -          
    1.15 +          <p class="note">
    1.16 +            Inifinite <code>float</code> values are allowed.
    1.17 +          </p>
    1.18            <p>
    1.19              For purposes of comparison, all <code>DOMString</code> values are evaluated as greater than 
    1.20              <code>long</code>, <code>float</code>, and <code>Date</code> values; <code>Date</code> values are evaluated as greater than <code>long</code> 
    1.21              and <code>float</code> values; and <code>long</code> and <code>float</code> values are evaluated by their numeric 
    1.22              value with no need to separate them by type. Moreover, <code>null</code> always evaluates 
    1.23 -            less than any other key value that is a non-null value. For the particular case 
    1.24 -            of floating point numbers, the value NaN is not allowed.
    1.25 +            less than any other key value that is a non-null value.
    1.26            </p>
    1.27 -          <div class="note">
    1.28 +          <p>
    1.29 +            The terms <dfn>greater than</dfn>, <dfn>less than</dfn> and <dfn>equal to</dfn> is defined in the terms of
    1.30 +            the above comparisons.
    1.31 +          </p>
    1.32 +          <p class="note">
    1.33              Only data types with natural ordering can be used as keys. 
    1.34              The ECMAScript <code>undefined</code> MUST NOT be used as a key.
    1.35 -          </div>
    1.36 +          </p>
    1.37          </section>
    1.38          
    1.39          <section id="value-construct" class="section">
    1.40 @@ -746,21 +753,16 @@
    1.41          <section class="section" id="range-concept">
    1.42            <h4>Key Range</h4>
    1.43            <p>
    1.44 -            An individual <a>record</a> can be retrieved from an 
    1.45 -            <a>object store</a> using either the record's key or the key 
    1.46 -            applicable for some <a>index</a> that 
    1.47 -            <a title="referenced">references</a> that <a>object store</a>. 
    1.48 -            Multiple records can be fetched using a <a>key range</a>. A 
    1.49 -            <dfn>key range</dfn> is a continuous interval over some data type 
    1.50 +            Records can be retrived from <a>object store</a>s and <a>index</a>es
    1.51 +            using either <a>key value</a>s or <dfn>key range</dfn>s. A 
    1.52 +            key range is a continuous interval over some data type 
    1.53              used for keys.
    1.54            </p>
    1.55            <p>
    1.56 -            A <a>key range</a> MAY be left-bounded or right-bounded if there is 
    1.57 +            A <a>key range</a> MAY be lower-bounded or upper-bounded if there is 
    1.58              a value that is, respectively, smaller than or larger than all its 
    1.59              elements. A <a>key range</a> is said to be bounded if it is both 
    1.60 -            left- and right-bounded and unbounded otherwise. A 
    1.61 -            <dfn title="valid key range">valid</dfn> <a>key range</a> MUST be 
    1.62 -            either half-bounded or bounded. A <a>key range</a> MAY be open, 
    1.63 +            lower- and upper-bounded and unbounded otherwise. A <a>key range</a> MAY be open, 
    1.64              i.e., not including its endpoints or closed, i.e., including
    1.65              its endpoints. A <a>key range</a> MAY consist of a single value.
    1.66            </p>
    1.67 @@ -769,62 +771,107 @@
    1.68              <a>key range</a>.
    1.69            </p>
    1.70            <dl class="idl" title="interface IDBKeyRange"> 
    1.71 -            <dt>const     unsigned short SINGLE = 0</dt>
    1.72 -            <dd>This flag indicates a single-valued <a>key range</a>.</dd>
    1.73 -            <dt>const     unsigned short LEFT_OPEN = 1</dt>
    1.74 -            <dd>This flag indicates a left-open <a>key range</a>.</dd>
    1.75 -            <dt>const     unsigned short RIGHT_OPEN = 2</dt>
    1.76 -            <dd>This flag indicates a right-open <a>key range</a>.</dd>
    1.77 -            <dt>const     unsigned short LEFT_BOUND = 4</dt>
    1.78 -            <dd>This flag indicates a left-bound <a>key range</a>.</dd>
    1.79 -            <dt>const     unsigned short RIGHT_BOUND = 8</dt>
    1.80 -            <dd>This flag indicates a right-bound <a>key range</a>.</dd>
    1.81 -            <dt>readonly attribute any left</dt>
    1.82 -            <dd>This value is the left-bound of the <a>key range</a>.</dd>
    1.83 -            <dt>readonly attribute any right</dt>
    1.84 -            <dd>This value is the right-bound of the <a>key range</a>.</dd>
    1.85 -            <dt>readonly attribute unsigned short flags</dt>
    1.86 -            <dd>Flags for bounding values</dd>
    1.87 +            <dt>readonly attribute any lower</dt>
    1.88 +            <dd>This value is the lower-bound of the <a>key range</a>.</dd>
    1.89 +            <dt>readonly attribute any upper</dt>
    1.90 +            <dd>This value is the upper-bound of the <a>key range</a>.</dd>
    1.91 +            <dt>readonly attribute boolean lowerOpen</dt>
    1.92 +            <dd>Returns false if the lower-bound value is included in the <a>key range</a>.</dd>
    1.93 +            <dt>readonly attribute boolean upperOpen</dt>
    1.94 +            <dd>Returns false if the upper-bound value is included in the <a>key range</a>.</dd>
    1.95 +          </dl>
    1.96 +          <p>
    1.97 +            A <a><var>key value</var></a> is <dfn>in a <a>key range</a></dfn> if both the following conditions are
    1.98 +            fulfilled:
    1.99 +          </p>
   1.100 +          <ul>
   1.101 +            <li>
   1.102 +              The <a>key range</a> <a href="#widl-IDBKeyRange-lower"><code>lower</code></a> value is <code>undefined</code> or
   1.103 +              <a>less than</a> <var>key value</var>. It may also be <a>equal to</a> <var>key value</var> if
   1.104 +              <a href="#widl-IDBKeyRange-lowerOpen"><code>lowerOpen</code></a> is <code>false</code>.
   1.105 +            </li>
   1.106 +            <li>
   1.107 +              The <a>key range</a> <a href="#widl-IDBKeyRange-upper"><code>upper</code></a> value is <code>undefined</code> or
   1.108 +              <a>greater than</a> <var>key value</var>. It may also be <a>equal to</a> <var>key value</var> if
   1.109 +              <a href="#widl-IDBKeyRange-upperOpen"><code>upperOpen</code></a> is <code>false</code>.
   1.110 +            </li>
   1.111 +          </ul>
   1.112 +
   1.113 +          <p>
   1.114 +            To construct a <a>key range</a> a set of constructors are available. In languages with
   1.115 +            interface objects [[!WEBIDL]], these constructors are available on the <code>IDBKeyRange</code>
   1.116 +            interface object. In other languages these constructors are available through language specific
   1.117 +            means, for example as static functions.
   1.118 +          </p>
   1.119 +          <dl class="idl" title="[NoInterfaceObject] interface IDBKeyRangeConstructors"> 
   1.120              <dt>IDBKeyRange only()</dt>
   1.121              <dd>
   1.122 -              Create a new single-valued <a>key range</a>.
   1.123 +              Creates and returns a new <a>key range</a> with both <a href="#widl-IDBKeyRange-lower">lower</a> and
   1.124 +              <a href="#widl-IDBKeyRange-upper">upper</a> set to <var>value</var> and both
   1.125 +              <a href="#widl-IDBKeyRange-lowerOpen">lowerOpen</a> and <a href="#widl-IDBKeyRange-upperOpen">upperOpen</a>
   1.126 +              set to false.
   1.127                <dl class="parameters">
   1.128                  <dt>any value</dt>
   1.129                  <dd>The only value</dd>
   1.130                </dl>
   1.131 +              <dl class="exception" title="IDBDatabaseException">
   1.132 +                <dt>DATA_ERR</dt>
   1.133 +                <dd>The <var>value</var> parameter was not passed a valid <a>key value</a>.</dd>
   1.134 +              </dl>
   1.135              </dd>
   1.136 -            <dt>IDBKeyRange leftBound()</dt>
   1.137 +            <dt>IDBKeyRange lowerBound()</dt>
   1.138              <dd>
   1.139 -              Create a new left-bound <a>key range</a>.
   1.140 +              Creates and returns a new <a>key range</a> with <a href="#widl-IDBKeyRange-lower">lower</a> set to
   1.141 +              <var>lower</var>, <a href="#widl-IDBKeyRange-lowerOpen">lowerOpen</a> set to <var>open</var>,
   1.142 +              <a href="#widl-IDBKeyRange-upper">upper</a> set to <code>undefined</code> and
   1.143 +              and <a href="#widl-IDBKeyRange-upperOpen">upperOpen</a> set to false.
   1.144                <dl class="parameters">
   1.145                  <dt>any bound</dt>
   1.146 -                <dd>The left bound value</dd>
   1.147 +                <dd>The lower bound value</dd>
   1.148                  <dt>optional boolean open</dt>
   1.149 -                <dd>Is the left-bound value included in the <a>key range</a>.</dd>
   1.150 +                <dd>Is the lower-bound value included in the <a>key range</a>. Defaults to false.</dd>
   1.151 +              </dl>
   1.152 +              <dl class="exception" title="IDBDatabaseException">
   1.153 +                <dt>DATA_ERR</dt>
   1.154 +                <dd>The <var>value</var> parameter was not passed a valid <a>key value</a>.</dd>
   1.155                </dl>
   1.156              </dd>
   1.157 -            <dt>IDBKeyRange rightBound()</dt>
   1.158 +            <dt>IDBKeyRange upperBound()</dt>
   1.159              <dd>
   1.160 -              Create a new right-bound <a>key range</a>.
   1.161 +              Creates and returns a new <a>key range</a> with <a href="#widl-IDBKeyRange-lower">lower</a> set to
   1.162 +              <code>undefined</code>, <a href="#widl-IDBKeyRange-lowerOpen">lowerOpen</a> set to false,
   1.163 +              <a href="#widl-IDBKeyRange-upper">upper</a> set to <var>value</var> and
   1.164 +              and <a href="#widl-IDBKeyRange-upperOpen">upperOpen</a> set to <var>open</var>.
   1.165                <dl class="parameters">
   1.166                  <dt>any bound</dt>
   1.167 -                <dd>The right bound value</dd>
   1.168 +                <dd>The upper bound value</dd>
   1.169                  <dt>optional boolean open</dt>
   1.170 -                <dd>Is the right-bound value included in the <a>key range</a>.</dd>
   1.171 +                <dd>Is the upper-bound value included in the <a>key range</a>. Defaults to false.</dd>
   1.172 +              </dl>
   1.173 +              <dl class="exception" title="IDBDatabaseException">
   1.174 +                <dt>DATA_ERR</dt>
   1.175 +                <dd>The <var>value</var> parameter was not passed a valid <a>key value</a>.</dd>
   1.176                </dl>
   1.177              </dd>
   1.178              <dt>IDBKeyRange bound()</dt>
   1.179              <dd>
   1.180 -              Create a new left- and right-bound <a>key range</a>.
   1.181 +              Creates and returns a new <a>key range</a> with <a href="#widl-IDBKeyRange-lower">lower</a> set to
   1.182 +              <var>lower</var>, <a href="#widl-IDBKeyRange-lowerOpen">lowerOpen</a> set to false,
   1.183 +              <a href="#widl-IDBKeyRange-upper">upper</a> set to <var>value</var> and
   1.184 +              and <a href="#widl-IDBKeyRange-upperOpen">upperOpen</a> set to <var>open</var>.
   1.185                <dl class="parameters">
   1.186 -                <dt>any left</dt>
   1.187 -                <dd>The left-bound value</dd>
   1.188 -                <dt>any right</dt>
   1.189 -                <dd>The right-bound value</dd>
   1.190 -                <dt>optional boolean openLeft</dt>
   1.191 -                <dd>Is the left-bound value included in the <a>key range</a>.</dd>
   1.192 -                <dt>optional boolean openRight</dt>
   1.193 -                <dd>Is the right-bound value included in the <a>key range</a>.</dd>
   1.194 +                <dt>any lower</dt>
   1.195 +                <dd>The lower-bound value</dd>
   1.196 +                <dt>any upper</dt>
   1.197 +                <dd>The upper-bound value</dd>
   1.198 +                <dt>optional boolean openLower</dt>
   1.199 +                <dd>Is the lower-bound value included in the <a>key range</a>. Defaults to false.</dd>
   1.200 +                <dt>optional boolean openUpper</dt>
   1.201 +                <dd>Is the upper-bound value included in the <a>key range</a>. Defaults to false.</dd>
   1.202 +              </dl>
   1.203 +              <dl class="exception" title="IDBDatabaseException">
   1.204 +                <dt>DATA_ERR</dt>
   1.205 +                <dd>The <var>lower</var> or <var>upper</var> parameters were not passed a valid <a>key value</a>.</dd>
   1.206                </dl>
   1.207              </dd>
   1.208            </dl>
   1.209 @@ -1440,63 +1487,60 @@
   1.210              </dd>
   1.211              <dt>IDBRequest get()</dt>
   1.212              <dd>
   1.213 -              This method returns immediately and retrieves the value from this 
   1.214 -              <a>object store</a> for the record corresponding to the given key 
   1.215 -              by following the 
   1.216 -              <a>steps for retrieving a record from an object store</a>. 
   1.217 -              If the operation is successful, then the 
   1.218 -              <a class="idlType" href="#widl-IDBRequest-result"><code>result</code></a> of this object's request
   1.219 -              is set to the retrieved value. If a record did not exist in this 
   1.220 -              <a>object store</a> for the key <var>key</var> parameter, then an 
   1.221 -              <a title="event-error">error event</a> is fired on this method's
   1.222 -              returned object with its 
   1.223 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   1.224 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>
   1.225 -              and a suitable 
   1.226 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>. If the <a>record</a> can be successfully 
   1.227 -              retrieved from the <a>object store</a>, then a 
   1.228 -              <a title="event-success">success event</a> is fired on this 
   1.229 -              method's returned object using the 
   1.230 -              <a><code>IDBTransactionEvent</code></a> interface with its 
   1.231 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to
   1.232 -              the value of the retrieved <a>record</a> and <a class="idlType" href="#widl-IDBTransactionEvent-transaction"><code>transaction</code></a> 
   1.233 -              set to the <a>transaction</a> in which this <a>object store</a> is 
   1.234 -              opened. 
   1.235 +              If the <var>key</var> parameter is not a valid <a>key value</a> or a <a>key range</a>, this method
   1.236 +              throws a DATA_ERR exception. Otherwise, this method runs the <a>steps for asynchronously executing
   1.237 +              a request</a> and returns the <a>IDBRequest</a> created by these steps. The steps are run with this
   1.238 +              <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for retrieving a record from an
   1.239 +              object store</a> as <var>operation</var>, using this <a>IDBObjectStore</a> as <var>store</var> and the
   1.240 +              <var>key</var> parameter as <var>key</var>.
   1.241                <dl class="parameters">
   1.242                  <dt>any key</dt>
   1.243 -                <dd>Key identifying the <a>record</a> to be retrieved</dd>
   1.244 +                <dd>Key identifying the <a>record</a> to be retrieved. This can also be a <a>IDBKeyRange</a> in which case
   1.245 +                the function retreives the first existing value in that range.</dd>
   1.246                </dl>
   1.247                <dl class="exception" title="IDBDatabaseException">
   1.248 -                <dt>NOT_ALLOWED_ERR</dt>
   1.249 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
   1.250 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   1.251 +                <dd>The <a>transaction</a> this <a>IDBObjectStore</a> belongs to is not <a>active</a>.</dd>
   1.252 +                <dt>DATA_ERR</dt>
   1.253 +                <dd>The <var>key</var> parameter was not passed a valid value.</dd>
   1.254                </dl>
   1.255              </dd>
   1.256              <dt>IDBRequest openCursor()</dt>
   1.257              <dd>
   1.258 -              This method returns immediately and creates a <a>cursor</a> over the 
   1.259 -              <a>records</a> of this <a>object store</a>. The <a>range</a> of this
   1.260 -              <a>cursor</a> matches the <a>key range</a> specified as the
   1.261 -              <var>range</var> parameter, or if that parameter is not specified or
   1.262 -              <code>null</code>, then the range includes all the <a>records</a>. 
   1.263 -              If there is even a single record that matches the <a>key range</a>, then a
   1.264 -              <a title="event-success">success event</a> is fired on this method's
   1.265 -              returned object with its 
   1.266 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
   1.267 -              <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   1.268 -              records match the <a>key range</a>, then an 
   1.269 -              <a title="event-success">success event</a> is fired on this method's
   1.270 -              returned object with its
   1.271 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   1.272 -              set to <code>null</code>.
   1.273 +              <p>
   1.274 +                This method returns immediately and creates a <a>cursor</a> over the 
   1.275 +                <a>records</a> of this <a>object store</a>.
   1.276 +              </p>
   1.277 +              <p>
   1.278 +                If the <var>range</var> parameter passed to the funciton is a <a><code>IDBKeyRange</code></a>,
   1.279 +                the <a>range</a> of this <a>cursor</a> matches that <a>key range</a>. If the <var>range</var>
   1.280 +                is a <a>key value</a> then the range matches a <a>key range</a> which includes only that
   1.281 +                value. If the <var>range</var> parameter is not specified, or is <code>null</code> then the
   1.282 +                range includes all the <a>records</a>. Otherwise, throw a DATA_ERR exception.
   1.283 +              </p>
   1.284 +              <p>
   1.285 +                If there is even a single record that matches the <a>key range</a>, then a
   1.286 +                <a title="event-success">success event</a> is fired on this method's
   1.287 +                returned object with its 
   1.288 +                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
   1.289 +                <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   1.290 +                records match the <a>key range</a>, then an 
   1.291 +                <a title="event-success">success event</a> is fired on this method's
   1.292 +                returned object with its
   1.293 +                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   1.294 +                set to <code>null</code>.
   1.295 +              </p>
   1.296                <dl class="parameters">
   1.297 -                <dt>optional IDBKeyRange    range</dt>
   1.298 +                <dt>optional any            range</dt>
   1.299                  <dd>The <a>key range</a> to use as the <a>cursor</a>'s <a>range</a></dd>
   1.300                  <dt>optional unsigned short direction</dt>
   1.301                  <dd>The <a>cursor</a>'s required <a>direction</a></dd>
   1.302                </dl>
   1.303                <dl class="exception" title="IDBDatabaseException">
   1.304 -                <dt>NOT_ALLOWED_ERR</dt>
   1.305 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
   1.306 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   1.307 +                <dd>The <a>transaction</a> this <a>IDBObjectStore</a> belongs to is not <a>active</a>.</dd>
   1.308 +                <dt>DATA_ERR</dt>
   1.309 +                <dd>The <var>range</var> parameter was not passed a valid value.</dd>
   1.310                </dl>
   1.311              </dd>
   1.312              <dt>IDBIndex createIndex()</dt>
   1.313 @@ -1601,24 +1645,30 @@
   1.314              </dd>
   1.315              <dt>IDBRequest openCursor()</dt>
   1.316              <dd>
   1.317 -              This method returns immediately and creates a <a>cursor</a> over the 
   1.318 -              <a>records</a> of this <a>index</a>'s <a>referenced</a> <a>object store</a> 
   1.319 -              as arranged by this <a>index</a>. The <a>range</a> of this <a>cursor</a> 
   1.320 -              matches the <a>key range</a> specified as the <var>range</var> parameter, or
   1.321 -              if that parameter is not specified or <code>null</code>, then the 
   1.322 -              range includes all the <a>records</a>.
   1.323 -              If there is even a single record that matches the <a>key range</a>, then a
   1.324 -              <a title="event-success">success event</a> is fired on this method's
   1.325 -              returned object with its 
   1.326 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
   1.327 -              <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   1.328 -              records match the <a>key range</a>, then an
   1.329 -              <a title="event-error">error event</a> is fired on this method's
   1.330 -              returned object with its 
   1.331 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   1.332 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>
   1.333 -              and a suitable 
   1.334 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>.
   1.335 +              <p>
   1.336 +                This method returns immediately and creates a <a>cursor</a> over the 
   1.337 +                <a>records</a> of this <a>index</a>'s <a>referenced</a> <a>object store</a> 
   1.338 +                as arranged by this <a>index</a>.
   1.339 +              </p>
   1.340 +              <p>
   1.341 +                If the <var>range</var> parameter passed to the funciton is a <a><code>IDBKeyRange</code></a>,
   1.342 +                the <a>range</a> of this <a>cursor</a> matches that <a>key range</a>. If the <var>range</var>
   1.343 +                is a <a>key value</a> then the range matches a <a>key range</a> which includes only that
   1.344 +                value. If the <var>range</var> parameter is not specified, or is <code>null</code> then the
   1.345 +                range includes all the <a>records</a>. Otherwise, throw a DATA_ERR exception.
   1.346 +              </p>
   1.347 +              <p>
   1.348 +                If there is even a single record that matches the <a>key range</a>, then a
   1.349 +                <a title="event-success">success event</a> is fired on this method's
   1.350 +                returned object with its 
   1.351 +                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
   1.352 +                <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   1.353 +                records match the <a>key range</a>, then an 
   1.354 +                <a title="event-success">success event</a> is fired on this method's
   1.355 +                returned object with its
   1.356 +                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   1.357 +                set to <code>null</code>.
   1.358 +              </p>
   1.359                <dl class="parameters">
   1.360                  <dt>optional IDBKeyRange    range</dt>
   1.361                  <dd>The <a>key range</a> to use as the <a>cursor</a>'s <a>range</a></dd>
   1.362 @@ -1626,29 +1676,37 @@
   1.363                  <dd>The <a>cursor</a>'s required <a>direction</a></dd>
   1.364                </dl>
   1.365                <dl class="exception" title="IDBDatabaseException">
   1.366 -                <dt>NOT_ALLOWED_ERR</dt>
   1.367 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
   1.368 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   1.369 +                <dd>The transaction this <a>IDBIndex</a> belongs to is not <a>active</a>.</dd>
   1.370 +                <dt>DATA_ERR</dt>
   1.371 +                <dd>The <var>range</var> parameter was not passed a valid value.</dd>
   1.372                </dl>
   1.373              </dd>
   1.374              <dt>IDBRequest openKeyCursor()</dt>
   1.375              <dd>
   1.376 -              This method returns immediately and creates a <a>cursor</a> over the 
   1.377 -              <a>records</a> of this <a>index</a>. The <a>range</a> of this <a>cursor</a>
   1.378 -              matches the <a>key range</a> specified as the <var>range</var> parameter, or
   1.379 -              if that parameter is not specified or <code>null</code>, then the 
   1.380 -              range includes all the <a>records</a>. 
   1.381 -              If there is even a single record that matches the <a>key range</a>, then a
   1.382 -              <a title="event-success">success event</a> is fired on this method's
   1.383 -              returned object with its 
   1.384 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the 
   1.385 -              <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   1.386 -              records match the <a>key range</a>, then an
   1.387 -              <a title="event-error">error event</a> is fired on this method's
   1.388 -              returned object with its 
   1.389 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   1.390 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>
   1.391 -              and a suitable 
   1.392 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>.
   1.393 +              <p>
   1.394 +                This method returns immediately and creates a <a>cursor</a> over the 
   1.395 +                <a>records</a> of this <a>index</a>.
   1.396 +              </p>
   1.397 +              <p>
   1.398 +                If the <var>range</var> parameter passed to the funciton is a <a><code>IDBKeyRange</code></a>,
   1.399 +                the <a>range</a> of this <a>cursor</a> matches that <a>key range</a>. If the <var>range</var>
   1.400 +                is a <a>key value</a> then the range matches a <a>key range</a> which includes only that
   1.401 +                value. If the <var>range</var> parameter is not specified, or is <code>null</code> then the
   1.402 +                range includes all the <a>records</a>. Otherwise, throw a DATA_ERR exception.
   1.403 +              </p>
   1.404 +              <p>
   1.405 +                If there is even a single record that matches the <a>key range</a>, then a
   1.406 +                <a title="event-success">success event</a> is fired on this method's
   1.407 +                returned object with its 
   1.408 +                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
   1.409 +                <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   1.410 +                records match the <a>key range</a>, then an 
   1.411 +                <a title="event-success">success event</a> is fired on this method's
   1.412 +                returned object with its
   1.413 +                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   1.414 +                set to <code>null</code>.
   1.415 +              </p>
   1.416                <dl class="parameters">
   1.417                  <dt>optional IDBKeyRange    range</dt>
   1.418                  <dd>The <a>key range</a> to use as the <a>cursor</a>'s <a>range</a></dd>
   1.419 @@ -1656,56 +1714,50 @@
   1.420                  <dd>The <a>cursor</a>'s required <a>direction</a></dd>
   1.421                </dl>
   1.422                <dl class="exception" title="IDBDatabaseException">
   1.423 -                <dt>NOT_ALLOWED_ERR</dt>
   1.424 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
   1.425 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   1.426 +                <dd>The transaction this <a>IDBIndex</a> belongs to is not <a>active</a>.</dd>
   1.427 +                <dt>DATA_ERR</dt>
   1.428 +                <dd>The <var>range</var> parameter was not passed a valid value.</dd>
   1.429                </dl>
   1.430              </dd>
   1.431              <dt>IDBRequest get()</dt>
   1.432              <dd>
   1.433 -              This method returns immediately and retrieves the value from this <a>index</a>'s
   1.434 -              <a>referenced</a> <a>object store</a> for the record corresponding to the given
   1.435 -              key by following the <a>steps for retrieving a record from an index</a>.
   1.436 -              If the operation is successful, then the 
   1.437 -              <a class="idlType" href="#widl-IDBRequest-result"><code>result</code></a> of this object's request
   1.438 -              is set to the retrieved value. If a record did not exist in this 
   1.439 -              <a>index</a> for the key <var>key</var> parameter, then an
   1.440 -              <a title="event-error">error event</a> is fired on this method's
   1.441 -              returned object with its 
   1.442 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   1.443 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>
   1.444 -              and a suitable 
   1.445 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>.
   1.446 +              If the <var>key</var> parameter is not a valid <a>key value</a> or a <a>key range</a>, this method
   1.447 +              throws a DATA_ERR exception. This method runs the <a>steps for asynchronously executing a request</a>
   1.448 +              and returns the <a>IDBRequest</a> created by these steps. The steps are run with this
   1.449 +              <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for retrieving a record from an
   1.450 +              index</a> as <var>operation</var>, using this <a>IDBIndex</a> as <var>index</var> and the
   1.451 +              <var>key</var> parameter as <var>key</var>.
   1.452                <dl class="parameters">
   1.453                  <dt>any key</dt>
   1.454 -                <dd>Key identifying the record to be retrieved</dd>
   1.455 +                <dd>Key identifying the record to be retrieved. This can also be a <a>IDBKeyRange</a> in which case
   1.456 +                the function retreives the first existing value in that range.</dd>
   1.457                </dl>
   1.458                <dl class="exception" title="IDBDatabaseException">
   1.459 -                <dt>NOT_ALLOWED_ERR</dt>
   1.460 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
   1.461 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   1.462 +                <dd>The transaction this <a>IDBIndex</a> belongs to is not <a>active</a>.</dd>
   1.463 +                <dt>DATA_ERR</dt>
   1.464 +                <dd>The <var>key</var> parameter was not passed a valid value.</dd>
   1.465                </dl>
   1.466              </dd>
   1.467              <dt>IDBRequest getKey()</dt>
   1.468              <dd>
   1.469 -              This method returns immediately and retrieves the value from this <a>index</a>
   1.470 -              for the record corresponding to the given <var>key</var> parameter by 
   1.471 -              following the <a>steps for retrieving a value from an index</a>.
   1.472 -              If the operation is successful, then the 
   1.473 -              <a class="idlType" href="#widl-IDBRequest-result"><code>result</code></a> of this object's request
   1.474 -              is set to the retrieved value. If a record did not exist in this 
   1.475 -              <a>index</a> for the key <var>key</var> parameter, then an
   1.476 -              <a title="event-error">error event</a> is fired on this method's
   1.477 -              returned object with its 
   1.478 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   1.479 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>
   1.480 -              and a suitable 
   1.481 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>.
   1.482 +              If the <var>key</var> parameter is not a valid <a>key value</a> or a <a>key range</a>, this method
   1.483 +              throws a DATA_ERR exception. This method runs the <a>steps for asynchronously executing a request</a>
   1.484 +              and returns the <a>IDBRequest</a> created by these steps. The steps are run with this
   1.485 +              <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for retrieving a value from an
   1.486 +              index</a> as <var>operation</var>, using this <a>IDBIndex</a> as <var>index</var> and the
   1.487 +              <var>key</var> parameter as <var>key</var>.
   1.488                <dl class="parameters">
   1.489                  <dt>any key</dt>
   1.490 -                <dd>Key identifying the record to be retrieved</dd>
   1.491 +                <dd>Key identifying the record to be retrieved. This can also be a <a>IDBKeyRange</a> in which case
   1.492 +                the function retreives the first existing value in that range.</dd>
   1.493                </dl>
   1.494                <dl class="exception" title="IDBDatabaseException">
   1.495 -                <dt>NOT_ALLOWED_ERR</dt>
   1.496 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
   1.497 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   1.498 +                <dd>The transaction this <a>IDBIndex</a> belongs to is not <a>active</a>.</dd>
   1.499 +                <dt>DATA_ERR</dt>
   1.500 +                <dd>The <var>key</var> parameter was not passed a valid value.</dd>
   1.501                </dl>
   1.502              </dd>
   1.503            </dl>
   1.504 @@ -2881,13 +2933,17 @@
   1.505                store</a> passed to these steps.
   1.506              </li>
   1.507              <li>
   1.508 -              If no record exists with key <var>key</var> in <var>store</var>,
   1.509 +              If <var>key</var> is not a <a>key range</a> then retreive the <a>record</a>
   1.510 +              with key <var>key</var> from <var>store</var>. If <var>key</var> is a <a>key range</a>, then
   1.511 +              retreive the first <a>record</a> from <var>store</var> whose key is <a title="in a key range">in</a> <var>key</var>.
   1.512 +            </li>
   1.513 +            <li>
   1.514 +              If no record was found in the previous step,
   1.515                then terminate these steps and set error code
   1.516                <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
   1.517              </li>
   1.518              <li>
   1.519 -              Return the a new <a>structured clone</a> of the value in the record with 
   1.520 -              key <var>key</var> in <var>store</var>.
   1.521 +              Return the a new <a>structured clone</a> of the value in the found record.
   1.522              </li>
   1.523            </ol>
   1.524          </section>
   1.525 @@ -2906,17 +2962,18 @@
   1.526                passed to these steps.
   1.527              </li>
   1.528              <li>
   1.529 -              If no record exists with key <var>key</var> in <var>index</var>,
   1.530 -              then terminate these steps and set error code
   1.531 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
   1.532 +              If <var>key</var> is not a <a>key range</a> then retreive the <a>record</a>
   1.533 +              with key <var>key</var> from <var>index</var>. If <var>key</var> is a <a>key range</a>, then
   1.534 +              retreive the first <a>record</a> from <var>index</var> whose key is <a title="in a key range">in</a> <var>key</var>.
   1.535              </li>
   1.536              <li>
   1.537 -              Let <var>value</var> be the value of the record with key <var>key</var>
   1.538 -              in <var>index</var>.
   1.539 +              If no record was found in the previous step, then the algorithm failed with a
   1.540 +              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> error</a>.
   1.541              </li>
   1.542              <li>
   1.543 -              Return the value for the record with key <var>value</var> in 
   1.544 -              <var>index</var>'s <a>referenced</a> <a>object store</a>.
   1.545 +              If a record was found, let <var>value</var> be the value of the found record. The result of
   1.546 +              this algorithm is a new <a>structured clone</a> of the value for the record with key
   1.547 +              <var>value</val> in <var>index</var>'s <a>referenced</a> <a>object store</a>
   1.548              </li>
   1.549            </ol>
   1.550          </section>
   1.551 @@ -2935,13 +2992,16 @@
   1.552                passed to these steps.
   1.553              </li>
   1.554              <li>
   1.555 -              If no record exists with key <var>key</var> in <var>index</var>,
   1.556 -              then terminate these steps and set error code
   1.557 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
   1.558 +              If <var>key</var> is not a <a>key range</a> then retreive the <a>record</a>
   1.559 +              with key <var>key</var> from <var>index</var>. If <var>key</var> is a <a>key range</a>, then
   1.560 +              retreive the first <a>record</a> from <var>index</var> whose key is <a title="in a key range">in</a> <var>key</var>.
   1.561              </li>
   1.562              <li>
   1.563 -              Return the value of the record with key <var>key</var>
   1.564 -              in <var>index</var>.
   1.565 +              If no record was found in the previous step, then the algorithm failed with a
   1.566 +              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> error</a>.
   1.567 +            </li>
   1.568 +            <li>
   1.569 +              If a record was found, the result of this algorithm is the value of the found <a>record</a>.
   1.570              </li>
   1.571            </ol>
   1.572          </section>
   1.573 @@ -3067,7 +3127,7 @@
   1.574          <section class="section">
   1.575            <h4>Steps for asynchronously executing a <a>request</a></h4>
   1.576            <p>
   1.577 -            When taking the <dfn>steps to a asynchronously execute a request</dfn> the implementation MUST run the
   1.578 +            When taking the <dfn>steps for asynchronously executing a request</dfn> the implementation MUST run the
   1.579              following algorithm. The algorithm takes a <var>source</var> object and a <var>operation</var> to
   1.580              perform on a database.
   1.581            </p>
   1.582 @@ -3080,6 +3140,9 @@
   1.583                Set <var>transaction</var> to the <a>transaction</a> associated with <var>source</var>.
   1.584              </li>
   1.585              <li>
   1.586 +              If <var>transaction</var> is not <a>active</a> throw a TRANSACTION_INACTIVE_ERR exception.
   1.587 +            </li>
   1.588 +            <li>
   1.589                Create a <a>IDBRequest</a> object and set <var>request</var> to this object. Set <var>request</var>'s
   1.590                <a title="request source">source</a> to <var>source</var> and add <var>request</var> to the end of the
   1.591                <a title="request list">list</a> of <a>request</a>s in <var>transaction</var>. Return
     2.1 --- a/Speclet_020_IDB_API_Constructs.html	Fri Oct 29 09:13:37 2010 -0700
     2.2 +++ b/Speclet_020_IDB_API_Constructs.html	Fri Oct 29 16:16:24 2010 -0700
     2.3 @@ -146,22 +146,29 @@
     2.4              In order to efficiently retrieve <a title="record">records</a> 
     2.5              stored in an indexed database, a user agent needs to organize each 
     2.6              <a>record</a> according to its key. <a>Conforming user agents</a>
     2.7 -            MUST support the use of the following values as keys: IDL data types
     2.8 -            <code>DOMString</code>, <code>long</code>, and <code>float</code> [[!WEBIDL]]; the <code>Date</code> JavaScript object [[!ECMA-262]]; as well as the value <code>null</code>.
     2.9 +            MUST support the use of the following types as <dfn>key value</dfn>s: IDL data types
    2.10 +            <code>DOMString</code>, <code>long</code>, and <code>float</code> [[!WEBIDL]]; the
    2.11 +            <code>Date</code> JavaScript object [[!ECMA-262]]; as well as the value <code>null</code>.
    2.12 +            For the particular case of <code>float</code>, the value NaN is not allowed.
    2.13            </p>
    2.14 -          
    2.15 +          <p class="note">
    2.16 +            Inifinite <code>float</code> values are allowed.
    2.17 +          </p>
    2.18            <p>
    2.19              For purposes of comparison, all <code>DOMString</code> values are evaluated as greater than 
    2.20              <code>long</code>, <code>float</code>, and <code>Date</code> values; <code>Date</code> values are evaluated as greater than <code>long</code> 
    2.21              and <code>float</code> values; and <code>long</code> and <code>float</code> values are evaluated by their numeric 
    2.22              value with no need to separate them by type. Moreover, <code>null</code> always evaluates 
    2.23 -            less than any other key value that is a non-null value. For the particular case 
    2.24 -            of floating point numbers, the value NaN is not allowed.
    2.25 +            less than any other key value that is a non-null value.
    2.26            </p>
    2.27 -          <div class="note">
    2.28 +          <p>
    2.29 +            The terms <dfn>greater than</dfn>, <dfn>less than</dfn> and <dfn>equal to</dfn> is defined in the terms of
    2.30 +            the above comparisons.
    2.31 +          </p>
    2.32 +          <p class="note">
    2.33              Only data types with natural ordering can be used as keys. 
    2.34              The ECMAScript <code>undefined</code> MUST NOT be used as a key.
    2.35 -          </div>
    2.36 +          </p>
    2.37          </section>
    2.38          
    2.39          <section id="value-construct" class="section">
    2.40 @@ -543,21 +550,16 @@
    2.41          <section class="section" id="range-concept">
    2.42            <h4>Key Range</h4>
    2.43            <p>
    2.44 -            An individual <a>record</a> can be retrieved from an 
    2.45 -            <a>object store</a> using either the record's key or the key 
    2.46 -            applicable for some <a>index</a> that 
    2.47 -            <a title="referenced">references</a> that <a>object store</a>. 
    2.48 -            Multiple records can be fetched using a <a>key range</a>. A 
    2.49 -            <dfn>key range</dfn> is a continuous interval over some data type 
    2.50 +            Records can be retrived from <a>object store</a>s and <a>index</a>es
    2.51 +            using either <a>key value</a>s or <dfn>key range</dfn>s. A 
    2.52 +            key range is a continuous interval over some data type 
    2.53              used for keys.
    2.54            </p>
    2.55            <p>
    2.56 -            A <a>key range</a> MAY be left-bounded or right-bounded if there is 
    2.57 +            A <a>key range</a> MAY be lower-bounded or upper-bounded if there is 
    2.58              a value that is, respectively, smaller than or larger than all its 
    2.59              elements. A <a>key range</a> is said to be bounded if it is both 
    2.60 -            left- and right-bounded and unbounded otherwise. A 
    2.61 -            <dfn title="valid key range">valid</dfn> <a>key range</a> MUST be 
    2.62 -            either half-bounded or bounded. A <a>key range</a> MAY be open, 
    2.63 +            lower- and upper-bounded and unbounded otherwise. A <a>key range</a> MAY be open, 
    2.64              i.e., not including its endpoints or closed, i.e., including
    2.65              its endpoints. A <a>key range</a> MAY consist of a single value.
    2.66            </p>
    2.67 @@ -566,62 +568,107 @@
    2.68              <a>key range</a>.
    2.69            </p>
    2.70            <dl class="idl" title="interface IDBKeyRange"> 
    2.71 -            <dt>const     unsigned short SINGLE = 0</dt>
    2.72 -            <dd>This flag indicates a single-valued <a>key range</a>.</dd>
    2.73 -            <dt>const     unsigned short LEFT_OPEN = 1</dt>
    2.74 -            <dd>This flag indicates a left-open <a>key range</a>.</dd>
    2.75 -            <dt>const     unsigned short RIGHT_OPEN = 2</dt>
    2.76 -            <dd>This flag indicates a right-open <a>key range</a>.</dd>
    2.77 -            <dt>const     unsigned short LEFT_BOUND = 4</dt>
    2.78 -            <dd>This flag indicates a left-bound <a>key range</a>.</dd>
    2.79 -            <dt>const     unsigned short RIGHT_BOUND = 8</dt>
    2.80 -            <dd>This flag indicates a right-bound <a>key range</a>.</dd>
    2.81 -            <dt>readonly attribute any left</dt>
    2.82 -            <dd>This value is the left-bound of the <a>key range</a>.</dd>
    2.83 -            <dt>readonly attribute any right</dt>
    2.84 -            <dd>This value is the right-bound of the <a>key range</a>.</dd>
    2.85 -            <dt>readonly attribute unsigned short flags</dt>
    2.86 -            <dd>Flags for bounding values</dd>
    2.87 +            <dt>readonly attribute any lower</dt>
    2.88 +            <dd>This value is the lower-bound of the <a>key range</a>.</dd>
    2.89 +            <dt>readonly attribute any upper</dt>
    2.90 +            <dd>This value is the upper-bound of the <a>key range</a>.</dd>
    2.91 +            <dt>readonly attribute boolean lowerOpen</dt>
    2.92 +            <dd>Returns false if the lower-bound value is included in the <a>key range</a>.</dd>
    2.93 +            <dt>readonly attribute boolean upperOpen</dt>
    2.94 +            <dd>Returns false if the upper-bound value is included in the <a>key range</a>.</dd>
    2.95 +          </dl>
    2.96 +          <p>
    2.97 +            A <a><var>key value</var></a> is <dfn>in a <a>key range</a></dfn> if both the following conditions are
    2.98 +            fulfilled:
    2.99 +          </p>
   2.100 +          <ul>
   2.101 +            <li>
   2.102 +              The <a>key range</a> <a href="#widl-IDBKeyRange-lower"><code>lower</code></a> value is <code>undefined</code> or
   2.103 +              <a>less than</a> <var>key value</var>. It may also be <a>equal to</a> <var>key value</var> if
   2.104 +              <a href="#widl-IDBKeyRange-lowerOpen"><code>lowerOpen</code></a> is <code>false</code>.
   2.105 +            </li>
   2.106 +            <li>
   2.107 +              The <a>key range</a> <a href="#widl-IDBKeyRange-upper"><code>upper</code></a> value is <code>undefined</code> or
   2.108 +              <a>greater than</a> <var>key value</var>. It may also be <a>equal to</a> <var>key value</var> if
   2.109 +              <a href="#widl-IDBKeyRange-upperOpen"><code>upperOpen</code></a> is <code>false</code>.
   2.110 +            </li>
   2.111 +          </ul>
   2.112 +
   2.113 +          <p>
   2.114 +            To construct a <a>key range</a> a set of constructors are available. In languages with
   2.115 +            interface objects [[!WEBIDL]], these constructors are available on the <code>IDBKeyRange</code>
   2.116 +            interface object. In other languages these constructors are available through language specific
   2.117 +            means, for example as static functions.
   2.118 +          </p>
   2.119 +          <dl class="idl" title="[NoInterfaceObject] interface IDBKeyRangeConstructors"> 
   2.120              <dt>IDBKeyRange only()</dt>
   2.121              <dd>
   2.122 -              Create a new single-valued <a>key range</a>.
   2.123 +              Creates and returns a new <a>key range</a> with both <a href="#widl-IDBKeyRange-lower">lower</a> and
   2.124 +              <a href="#widl-IDBKeyRange-upper">upper</a> set to <var>value</var> and both
   2.125 +              <a href="#widl-IDBKeyRange-lowerOpen">lowerOpen</a> and <a href="#widl-IDBKeyRange-upperOpen">upperOpen</a>
   2.126 +              set to false.
   2.127                <dl class="parameters">
   2.128                  <dt>any value</dt>
   2.129                  <dd>The only value</dd>
   2.130                </dl>
   2.131 +              <dl class="exception" title="IDBDatabaseException">
   2.132 +                <dt>DATA_ERR</dt>
   2.133 +                <dd>The <var>value</var> parameter was not passed a valid <a>key value</a>.</dd>
   2.134 +              </dl>
   2.135              </dd>
   2.136 -            <dt>IDBKeyRange leftBound()</dt>
   2.137 +            <dt>IDBKeyRange lowerBound()</dt>
   2.138              <dd>
   2.139 -              Create a new left-bound <a>key range</a>.
   2.140 +              Creates and returns a new <a>key range</a> with <a href="#widl-IDBKeyRange-lower">lower</a> set to
   2.141 +              <var>lower</var>, <a href="#widl-IDBKeyRange-lowerOpen">lowerOpen</a> set to <var>open</var>,
   2.142 +              <a href="#widl-IDBKeyRange-upper">upper</a> set to <code>undefined</code> and
   2.143 +              and <a href="#widl-IDBKeyRange-upperOpen">upperOpen</a> set to false.
   2.144                <dl class="parameters">
   2.145                  <dt>any bound</dt>
   2.146 -                <dd>The left bound value</dd>
   2.147 +                <dd>The lower bound value</dd>
   2.148                  <dt>optional boolean open</dt>
   2.149 -                <dd>Is the left-bound value included in the <a>key range</a>.</dd>
   2.150 +                <dd>Is the lower-bound value included in the <a>key range</a>. Defaults to false.</dd>
   2.151 +              </dl>
   2.152 +              <dl class="exception" title="IDBDatabaseException">
   2.153 +                <dt>DATA_ERR</dt>
   2.154 +                <dd>The <var>value</var> parameter was not passed a valid <a>key value</a>.</dd>
   2.155                </dl>
   2.156              </dd>
   2.157 -            <dt>IDBKeyRange rightBound()</dt>
   2.158 +            <dt>IDBKeyRange upperBound()</dt>
   2.159              <dd>
   2.160 -              Create a new right-bound <a>key range</a>.
   2.161 +              Creates and returns a new <a>key range</a> with <a href="#widl-IDBKeyRange-lower">lower</a> set to
   2.162 +              <code>undefined</code>, <a href="#widl-IDBKeyRange-lowerOpen">lowerOpen</a> set to false,
   2.163 +              <a href="#widl-IDBKeyRange-upper">upper</a> set to <var>value</var> and
   2.164 +              and <a href="#widl-IDBKeyRange-upperOpen">upperOpen</a> set to <var>open</var>.
   2.165                <dl class="parameters">
   2.166                  <dt>any bound</dt>
   2.167 -                <dd>The right bound value</dd>
   2.168 +                <dd>The upper bound value</dd>
   2.169                  <dt>optional boolean open</dt>
   2.170 -                <dd>Is the right-bound value included in the <a>key range</a>.</dd>
   2.171 +                <dd>Is the upper-bound value included in the <a>key range</a>. Defaults to false.</dd>
   2.172 +              </dl>
   2.173 +              <dl class="exception" title="IDBDatabaseException">
   2.174 +                <dt>DATA_ERR</dt>
   2.175 +                <dd>The <var>value</var> parameter was not passed a valid <a>key value</a>.</dd>
   2.176                </dl>
   2.177              </dd>
   2.178              <dt>IDBKeyRange bound()</dt>
   2.179              <dd>
   2.180 -              Create a new left- and right-bound <a>key range</a>.
   2.181 +              Creates and returns a new <a>key range</a> with <a href="#widl-IDBKeyRange-lower">lower</a> set to
   2.182 +              <var>lower</var>, <a href="#widl-IDBKeyRange-lowerOpen">lowerOpen</a> set to false,
   2.183 +              <a href="#widl-IDBKeyRange-upper">upper</a> set to <var>value</var> and
   2.184 +              and <a href="#widl-IDBKeyRange-upperOpen">upperOpen</a> set to <var>open</var>.
   2.185                <dl class="parameters">
   2.186 -                <dt>any left</dt>
   2.187 -                <dd>The left-bound value</dd>
   2.188 -                <dt>any right</dt>
   2.189 -                <dd>The right-bound value</dd>
   2.190 -                <dt>optional boolean openLeft</dt>
   2.191 -                <dd>Is the left-bound value included in the <a>key range</a>.</dd>
   2.192 -                <dt>optional boolean openRight</dt>
   2.193 -                <dd>Is the right-bound value included in the <a>key range</a>.</dd>
   2.194 +                <dt>any lower</dt>
   2.195 +                <dd>The lower-bound value</dd>
   2.196 +                <dt>any upper</dt>
   2.197 +                <dd>The upper-bound value</dd>
   2.198 +                <dt>optional boolean openLower</dt>
   2.199 +                <dd>Is the lower-bound value included in the <a>key range</a>. Defaults to false.</dd>
   2.200 +                <dt>optional boolean openUpper</dt>
   2.201 +                <dd>Is the upper-bound value included in the <a>key range</a>. Defaults to false.</dd>
   2.202 +              </dl>
   2.203 +              <dl class="exception" title="IDBDatabaseException">
   2.204 +                <dt>DATA_ERR</dt>
   2.205 +                <dd>The <var>lower</var> or <var>upper</var> parameters were not passed a valid <a>key value</a>.</dd>
   2.206                </dl>
   2.207              </dd>
   2.208            </dl>
     3.1 --- a/Speclet_021_IDB_API_Algorithms.html	Fri Oct 29 09:13:37 2010 -0700
     3.2 +++ b/Speclet_021_IDB_API_Algorithms.html	Fri Oct 29 16:16:24 2010 -0700
     3.3 @@ -257,13 +257,17 @@
     3.4                store</a> passed to these steps.
     3.5              </li>
     3.6              <li>
     3.7 -              If no record exists with key <var>key</var> in <var>store</var>,
     3.8 +              If <var>key</var> is not a <a>key range</a> then retreive the <a>record</a>
     3.9 +              with key <var>key</var> from <var>store</var>. If <var>key</var> is a <a>key range</a>, then
    3.10 +              retreive the first <a>record</a> from <var>store</var> whose key is <a title="in a key range">in</a> <var>key</var>.
    3.11 +            </li>
    3.12 +            <li>
    3.13 +              If no record was found in the previous step,
    3.14                then terminate these steps and set error code
    3.15                <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
    3.16              </li>
    3.17              <li>
    3.18 -              Return the a new <a>structured clone</a> of the value in the record with 
    3.19 -              key <var>key</var> in <var>store</var>.
    3.20 +              Return the a new <a>structured clone</a> of the value in the found record.
    3.21              </li>
    3.22            </ol>
    3.23          </section>
    3.24 @@ -282,17 +286,18 @@
    3.25                passed to these steps.
    3.26              </li>
    3.27              <li>
    3.28 -              If no record exists with key <var>key</var> in <var>index</var>,
    3.29 -              then terminate these steps and set error code
    3.30 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
    3.31 +              If <var>key</var> is not a <a>key range</a> then retreive the <a>record</a>
    3.32 +              with key <var>key</var> from <var>index</var>. If <var>key</var> is a <a>key range</a>, then
    3.33 +              retreive the first <a>record</a> from <var>index</var> whose key is <a title="in a key range">in</a> <var>key</var>.
    3.34              </li>
    3.35              <li>
    3.36 -              Let <var>value</var> be the value of the record with key <var>key</var>
    3.37 -              in <var>index</var>.
    3.38 +              If no record was found in the previous step, then the algorithm failed with a
    3.39 +              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> error</a>.
    3.40              </li>
    3.41              <li>
    3.42 -              Return the value for the record with key <var>value</var> in 
    3.43 -              <var>index</var>'s <a>referenced</a> <a>object store</a>.
    3.44 +              If a record was found, let <var>value</var> be the value of the found record. The result of
    3.45 +              this algorithm is a new <a>structured clone</a> of the value for the record with key
    3.46 +              <var>value</val> in <var>index</var>'s <a>referenced</a> <a>object store</a>
    3.47              </li>
    3.48            </ol>
    3.49          </section>
    3.50 @@ -311,13 +316,16 @@
    3.51                passed to these steps.
    3.52              </li>
    3.53              <li>
    3.54 -              If no record exists with key <var>key</var> in <var>index</var>,
    3.55 -              then terminate these steps and set error code
    3.56 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
    3.57 +              If <var>key</var> is not a <a>key range</a> then retreive the <a>record</a>
    3.58 +              with key <var>key</var> from <var>index</var>. If <var>key</var> is a <a>key range</a>, then
    3.59 +              retreive the first <a>record</a> from <var>index</var> whose key is <a title="in a key range">in</a> <var>key</var>.
    3.60              </li>
    3.61              <li>
    3.62 -              Return the value of the record with key <var>key</var>
    3.63 -              in <var>index</var>.
    3.64 +              If no record was found in the previous step, then the algorithm failed with a
    3.65 +              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> error</a>.
    3.66 +            </li>
    3.67 +            <li>
    3.68 +              If a record was found, the result of this algorithm is the value of the found <a>record</a>.
    3.69              </li>
    3.70            </ol>
    3.71          </section>
    3.72 @@ -443,7 +451,7 @@
    3.73          <section class="section">
    3.74            <h4>Steps for asynchronously executing a <a>request</a></h4>
    3.75            <p>
    3.76 -            When taking the <dfn>steps to a asynchronously execute a request</dfn> the implementation MUST run the
    3.77 +            When taking the <dfn>steps for asynchronously executing a request</dfn> the implementation MUST run the
    3.78              following algorithm. The algorithm takes a <var>source</var> object and a <var>operation</var> to
    3.79              perform on a database.
    3.80            </p>
    3.81 @@ -456,6 +464,9 @@
    3.82                Set <var>transaction</var> to the <a>transaction</a> associated with <var>source</var>.
    3.83              </li>
    3.84              <li>
    3.85 +              If <var>transaction</var> is not <a>active</a> throw a TRANSACTION_INACTIVE_ERR exception.
    3.86 +            </li>
    3.87 +            <li>
    3.88                Create a <a>IDBRequest</a> object and set <var>request</var> to this object. Set <var>request</var>'s
    3.89                <a title="request source">source</a> to <var>source</var> and add <var>request</var> to the end of the
    3.90                <a title="request list">list</a> of <a>request</a>s in <var>transaction</var>. Return
     4.1 --- a/Speclet_023_IDB_API_Asynchronous_APIs.html	Fri Oct 29 09:13:37 2010 -0700
     4.2 +++ b/Speclet_023_IDB_API_Asynchronous_APIs.html	Fri Oct 29 16:16:24 2010 -0700
     4.3 @@ -650,63 +650,60 @@
     4.4              </dd>
     4.5              <dt>IDBRequest get()</dt>
     4.6              <dd>
     4.7 -              This method returns immediately and retrieves the value from this 
     4.8 -              <a>object store</a> for the record corresponding to the given key 
     4.9 -              by following the 
    4.10 -              <a>steps for retrieving a record from an object store</a>. 
    4.11 -              If the operation is successful, then the 
    4.12 -              <a class="idlType" href="#widl-IDBRequest-result"><code>result</code></a> of this object's request
    4.13 -              is set to the retrieved value. If a record did not exist in this 
    4.14 -              <a>object store</a> for the key <var>key</var> parameter, then an 
    4.15 -              <a title="event-error">error event</a> is fired on this method's
    4.16 -              returned object with its 
    4.17 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
    4.18 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>
    4.19 -              and a suitable 
    4.20 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>. If the <a>record</a> can be successfully 
    4.21 -              retrieved from the <a>object store</a>, then a 
    4.22 -              <a title="event-success">success event</a> is fired on this 
    4.23 -              method's returned object using the 
    4.24 -              <a><code>IDBTransactionEvent</code></a> interface with its 
    4.25 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to
    4.26 -              the value of the retrieved <a>record</a> and <a class="idlType" href="#widl-IDBTransactionEvent-transaction"><code>transaction</code></a> 
    4.27 -              set to the <a>transaction</a> in which this <a>object store</a> is 
    4.28 -              opened. 
    4.29 +              If the <var>key</var> parameter is not a valid <a>key value</a> or a <a>key range</a>, this method
    4.30 +              throws a DATA_ERR exception. Otherwise, this method runs the <a>steps for asynchronously executing
    4.31 +              a request</a> and returns the <a>IDBRequest</a> created by these steps. The steps are run with this
    4.32 +              <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for retrieving a record from an
    4.33 +              object store</a> as <var>operation</var>, using this <a>IDBObjectStore</a> as <var>store</var> and the
    4.34 +              <var>key</var> parameter as <var>key</var>.
    4.35                <dl class="parameters">
    4.36                  <dt>any key</dt>
    4.37 -                <dd>Key identifying the <a>record</a> to be retrieved</dd>
    4.38 +                <dd>Key identifying the <a>record</a> to be retrieved. This can also be a <a>IDBKeyRange</a> in which case
    4.39 +                the function retreives the first existing value in that range.</dd>
    4.40                </dl>
    4.41                <dl class="exception" title="IDBDatabaseException">
    4.42 -                <dt>NOT_ALLOWED_ERR</dt>
    4.43 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
    4.44 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
    4.45 +                <dd>The <a>transaction</a> this <a>IDBObjectStore</a> belongs to is not <a>active</a>.</dd>
    4.46 +                <dt>DATA_ERR</dt>
    4.47 +                <dd>The <var>key</var> parameter was not passed a valid value.</dd>
    4.48                </dl>
    4.49              </dd>
    4.50              <dt>IDBRequest openCursor()</dt>
    4.51              <dd>
    4.52 -              This method returns immediately and creates a <a>cursor</a> over the 
    4.53 -              <a>records</a> of this <a>object store</a>. The <a>range</a> of this
    4.54 -              <a>cursor</a> matches the <a>key range</a> specified as the
    4.55 -              <var>range</var> parameter, or if that parameter is not specified or
    4.56 -              <code>null</code>, then the range includes all the <a>records</a>. 
    4.57 -              If there is even a single record that matches the <a>key range</a>, then a
    4.58 -              <a title="event-success">success event</a> is fired on this method's
    4.59 -              returned object with its 
    4.60 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
    4.61 -              <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
    4.62 -              records match the <a>key range</a>, then an 
    4.63 -              <a title="event-success">success event</a> is fired on this method's
    4.64 -              returned object with its
    4.65 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
    4.66 -              set to <code>null</code>.
    4.67 +              <p>
    4.68 +                This method returns immediately and creates a <a>cursor</a> over the 
    4.69 +                <a>records</a> of this <a>object store</a>.
    4.70 +              </p>
    4.71 +              <p>
    4.72 +                If the <var>range</var> parameter passed to the funciton is a <a><code>IDBKeyRange</code></a>,
    4.73 +                the <a>range</a> of this <a>cursor</a> matches that <a>key range</a>. If the <var>range</var>
    4.74 +                is a <a>key value</a> then the range matches a <a>key range</a> which includes only that
    4.75 +                value. If the <var>range</var> parameter is not specified, or is <code>null</code> then the
    4.76 +                range includes all the <a>records</a>. Otherwise, throw a DATA_ERR exception.
    4.77 +              </p>
    4.78 +              <p>
    4.79 +                If there is even a single record that matches the <a>key range</a>, then a
    4.80 +                <a title="event-success">success event</a> is fired on this method's
    4.81 +                returned object with its 
    4.82 +                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
    4.83 +                <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
    4.84 +                records match the <a>key range</a>, then an 
    4.85 +                <a title="event-success">success event</a> is fired on this method's
    4.86 +                returned object with its
    4.87 +                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
    4.88 +                set to <code>null</code>.
    4.89 +              </p>
    4.90                <dl class="parameters">
    4.91 -                <dt>optional IDBKeyRange    range</dt>
    4.92 +                <dt>optional any            range</dt>
    4.93                  <dd>The <a>key range</a> to use as the <a>cursor</a>'s <a>range</a></dd>
    4.94                  <dt>optional unsigned short direction</dt>
    4.95                  <dd>The <a>cursor</a>'s required <a>direction</a></dd>
    4.96                </dl>
    4.97                <dl class="exception" title="IDBDatabaseException">
    4.98 -                <dt>NOT_ALLOWED_ERR</dt>
    4.99 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
   4.100 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   4.101 +                <dd>The <a>transaction</a> this <a>IDBObjectStore</a> belongs to is not <a>active</a>.</dd>
   4.102 +                <dt>DATA_ERR</dt>
   4.103 +                <dd>The <var>range</var> parameter was not passed a valid value.</dd>
   4.104                </dl>
   4.105              </dd>
   4.106              <dt>IDBIndex createIndex()</dt>
   4.107 @@ -811,24 +808,30 @@
   4.108              </dd>
   4.109              <dt>IDBRequest openCursor()</dt>
   4.110              <dd>
   4.111 -              This method returns immediately and creates a <a>cursor</a> over the 
   4.112 -              <a>records</a> of this <a>index</a>'s <a>referenced</a> <a>object store</a> 
   4.113 -              as arranged by this <a>index</a>. The <a>range</a> of this <a>cursor</a> 
   4.114 -              matches the <a>key range</a> specified as the <var>range</var> parameter, or
   4.115 -              if that parameter is not specified or <code>null</code>, then the 
   4.116 -              range includes all the <a>records</a>.
   4.117 -              If there is even a single record that matches the <a>key range</a>, then a
   4.118 -              <a title="event-success">success event</a> is fired on this method's
   4.119 -              returned object with its 
   4.120 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
   4.121 -              <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   4.122 -              records match the <a>key range</a>, then an
   4.123 -              <a title="event-error">error event</a> is fired on this method's
   4.124 -              returned object with its 
   4.125 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   4.126 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>
   4.127 -              and a suitable 
   4.128 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>.
   4.129 +              <p>
   4.130 +                This method returns immediately and creates a <a>cursor</a> over the 
   4.131 +                <a>records</a> of this <a>index</a>'s <a>referenced</a> <a>object store</a> 
   4.132 +                as arranged by this <a>index</a>.
   4.133 +              </p>
   4.134 +              <p>
   4.135 +                If the <var>range</var> parameter passed to the funciton is a <a><code>IDBKeyRange</code></a>,
   4.136 +                the <a>range</a> of this <a>cursor</a> matches that <a>key range</a>. If the <var>range</var>
   4.137 +                is a <a>key value</a> then the range matches a <a>key range</a> which includes only that
   4.138 +                value. If the <var>range</var> parameter is not specified, or is <code>null</code> then the
   4.139 +                range includes all the <a>records</a>. Otherwise, throw a DATA_ERR exception.
   4.140 +              </p>
   4.141 +              <p>
   4.142 +                If there is even a single record that matches the <a>key range</a>, then a
   4.143 +                <a title="event-success">success event</a> is fired on this method's
   4.144 +                returned object with its 
   4.145 +                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
   4.146 +                <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   4.147 +                records match the <a>key range</a>, then an 
   4.148 +                <a title="event-success">success event</a> is fired on this method's
   4.149 +                returned object with its
   4.150 +                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   4.151 +                set to <code>null</code>.
   4.152 +              </p>
   4.153                <dl class="parameters">
   4.154                  <dt>optional IDBKeyRange    range</dt>
   4.155                  <dd>The <a>key range</a> to use as the <a>cursor</a>'s <a>range</a></dd>
   4.156 @@ -836,29 +839,37 @@
   4.157                  <dd>The <a>cursor</a>'s required <a>direction</a></dd>
   4.158                </dl>
   4.159                <dl class="exception" title="IDBDatabaseException">
   4.160 -                <dt>NOT_ALLOWED_ERR</dt>
   4.161 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
   4.162 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   4.163 +                <dd>The transaction this <a>IDBIndex</a> belongs to is not <a>active</a>.</dd>
   4.164 +                <dt>DATA_ERR</dt>
   4.165 +                <dd>The <var>range</var> parameter was not passed a valid value.</dd>
   4.166                </dl>
   4.167              </dd>
   4.168              <dt>IDBRequest openKeyCursor()</dt>
   4.169              <dd>
   4.170 -              This method returns immediately and creates a <a>cursor</a> over the 
   4.171 -              <a>records</a> of this <a>index</a>. The <a>range</a> of this <a>cursor</a>
   4.172 -              matches the <a>key range</a> specified as the <var>range</var> parameter, or
   4.173 -              if that parameter is not specified or <code>null</code>, then the 
   4.174 -              range includes all the <a>records</a>. 
   4.175 -              If there is even a single record that matches the <a>key range</a>, then a
   4.176 -              <a title="event-success">success event</a> is fired on this method's
   4.177 -              returned object with its 
   4.178 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the 
   4.179 -              <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   4.180 -              records match the <a>key range</a>, then an
   4.181 -              <a title="event-error">error event</a> is fired on this method's
   4.182 -              returned object with its 
   4.183 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   4.184 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>
   4.185 -              and a suitable 
   4.186 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>.
   4.187 +              <p>
   4.188 +                This method returns immediately and creates a <a>cursor</a> over the 
   4.189 +                <a>records</a> of this <a>index</a>.
   4.190 +              </p>
   4.191 +              <p>
   4.192 +                If the <var>range</var> parameter passed to the funciton is a <a><code>IDBKeyRange</code></a>,
   4.193 +                the <a>range</a> of this <a>cursor</a> matches that <a>key range</a>. If the <var>range</var>
   4.194 +                is a <a>key value</a> then the range matches a <a>key range</a> which includes only that
   4.195 +                value. If the <var>range</var> parameter is not specified, or is <code>null</code> then the
   4.196 +                range includes all the <a>records</a>. Otherwise, throw a DATA_ERR exception.
   4.197 +              </p>
   4.198 +              <p>
   4.199 +                If there is even a single record that matches the <a>key range</a>, then a
   4.200 +                <a title="event-success">success event</a> is fired on this method's
   4.201 +                returned object with its 
   4.202 +                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
   4.203 +                <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   4.204 +                records match the <a>key range</a>, then an 
   4.205 +                <a title="event-success">success event</a> is fired on this method's
   4.206 +                returned object with its
   4.207 +                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   4.208 +                set to <code>null</code>.
   4.209 +              </p>
   4.210                <dl class="parameters">
   4.211                  <dt>optional IDBKeyRange    range</dt>
   4.212                  <dd>The <a>key range</a> to use as the <a>cursor</a>'s <a>range</a></dd>
   4.213 @@ -866,56 +877,50 @@
   4.214                  <dd>The <a>cursor</a>'s required <a>direction</a></dd>
   4.215                </dl>
   4.216                <dl class="exception" title="IDBDatabaseException">
   4.217 -                <dt>NOT_ALLOWED_ERR</dt>
   4.218 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
   4.219 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   4.220 +                <dd>The transaction this <a>IDBIndex</a> belongs to is not <a>active</a>.</dd>
   4.221 +                <dt>DATA_ERR</dt>
   4.222 +                <dd>The <var>range</var> parameter was not passed a valid value.</dd>
   4.223                </dl>
   4.224              </dd>
   4.225              <dt>IDBRequest get()</dt>
   4.226              <dd>
   4.227 -              This method returns immediately and retrieves the value from this <a>index</a>'s
   4.228 -              <a>referenced</a> <a>object store</a> for the record corresponding to the given
   4.229 -              key by following the <a>steps for retrieving a record from an index</a>.
   4.230 -              If the operation is successful, then the 
   4.231 -              <a class="idlType" href="#widl-IDBRequest-result"><code>result</code></a> of this object's request
   4.232 -              is set to the retrieved value. If a record did not exist in this 
   4.233 -              <a>index</a> for the key <var>key</var> parameter, then an
   4.234 -              <a title="event-error">error event</a> is fired on this method's
   4.235 -              returned object with its 
   4.236 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   4.237 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>
   4.238 -              and a suitable 
   4.239 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>.
   4.240 +              If the <var>key</var> parameter is not a valid <a>key value</a> or a <a>key range</a>, this method
   4.241 +              throws a DATA_ERR exception. This method runs the <a>steps for asynchronously executing a request</a>
   4.242 +              and returns the <a>IDBRequest</a> created by these steps. The steps are run with this
   4.243 +              <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for retrieving a record from an
   4.244 +              index</a> as <var>operation</var>, using this <a>IDBIndex</a> as <var>index</var> and the
   4.245 +              <var>key</var> parameter as <var>key</var>.
   4.246                <dl class="parameters">
   4.247                  <dt>any key</dt>
   4.248 -                <dd>Key identifying the record to be retrieved</dd>
   4.249 +                <dd>Key identifying the record to be retrieved. This can also be a <a>IDBKeyRange</a> in which case
   4.250 +                the function retreives the first existing value in that range.</dd>
   4.251                </dl>
   4.252                <dl class="exception" title="IDBDatabaseException">
   4.253 -                <dt>NOT_ALLOWED_ERR</dt>
   4.254 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
   4.255 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   4.256 +                <dd>The transaction this <a>IDBIndex</a> belongs to is not <a>active</a>.</dd>
   4.257 +                <dt>DATA_ERR</dt>
   4.258 +                <dd>The <var>key</var> parameter was not passed a valid value.</dd>
   4.259                </dl>
   4.260              </dd>
   4.261              <dt>IDBRequest getKey()</dt>
   4.262              <dd>
   4.263 -              This method returns immediately and retrieves the value from this <a>index</a>
   4.264 -              for the record corresponding to the given <var>key</var> parameter by 
   4.265 -              following the <a>steps for retrieving a value from an index</a>.
   4.266 -              If the operation is successful, then the 
   4.267 -              <a class="idlType" href="#widl-IDBRequest-result"><code>result</code></a> of this object's request
   4.268 -              is set to the retrieved value. If a record did not exist in this 
   4.269 -              <a>index</a> for the key <var>key</var> parameter, then an
   4.270 -              <a title="event-error">error event</a> is fired on this method's
   4.271 -              returned object with its 
   4.272 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   4.273 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>
   4.274 -              and a suitable 
   4.275 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>.
   4.276 +              If the <var>key</var> parameter is not a valid <a>key value</a> or a <a>key range</a>, this method
   4.277 +              throws a DATA_ERR exception. This method runs the <a>steps for asynchronously executing a request</a>
   4.278 +              and returns the <a>IDBRequest</a> created by these steps. The steps are run with this
   4.279 +              <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for retrieving a value from an
   4.280 +              index</a> as <var>operation</var>, using this <a>IDBIndex</a> as <var>index</var> and the
   4.281 +              <var>key</var> parameter as <var>key</var>.
   4.282                <dl class="parameters">
   4.283                  <dt>any key</dt>
   4.284 -                <dd>Key identifying the record to be retrieved</dd>
   4.285 +                <dd>Key identifying the record to be retrieved. This can also be a <a>IDBKeyRange</a> in which case
   4.286 +                the function retreives the first existing value in that range.</dd>
   4.287                </dl>
   4.288                <dl class="exception" title="IDBDatabaseException">
   4.289 -                <dt>NOT_ALLOWED_ERR</dt>
   4.290 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
   4.291 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   4.292 +                <dd>The transaction this <a>IDBIndex</a> belongs to is not <a>active</a>.</dd>
   4.293 +                <dt>DATA_ERR</dt>
   4.294 +                <dd>The <var>key</var> parameter was not passed a valid value.</dd>
   4.295                </dl>
   4.296              </dd>
   4.297            </dl>