Clean up IDBIndex a bit by renaming functions and removing explicit add/remove functions. Bugs 10027, 10674
authorJonas Sicking <jonas@sicking.cc>
Fri, 22 Oct 2010 21:38:59 -0700
changeset 71c2618f86a774
parent 70 eec86528f9ed
child 72 7ded3f76226c
Clean up IDBIndex a bit by renaming functions and removing explicit add/remove functions. Bugs 10027, 10674
Overview.html
Speclet_021_IDB_API_Algorithms.html
Speclet_022_IDB_API_Synchronous_APIs.html
Speclet_023_IDB_API_Asynchronous_APIs.html
     1.1 --- a/Overview.html	Fri Oct 22 14:52:26 2010 -0700
     1.2 +++ b/Overview.html	Fri Oct 22 21:38:59 2010 -0700
     1.3 @@ -1442,7 +1442,7 @@
     1.4              <dd>
     1.5                On getting, provide the <a>unique</a> flag of this <a>index</a>.
     1.6              </dd>
     1.7 -            <dt>IDBRequest openObjectCursor()</dt>
     1.8 +            <dt>IDBRequest openCursor()</dt>
     1.9              <dd>
    1.10                This method returns immediately and creates a <a>cursor</a> over the 
    1.11                <a>records</a> of this <a>index</a>'s <a>referenced</a> <a>object store</a> 
    1.12 @@ -1473,7 +1473,7 @@
    1.13                  <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
    1.14                </dl>
    1.15              </dd>
    1.16 -            <dt>IDBRequest openCursor()</dt>
    1.17 +            <dt>IDBRequest openKeyCursor()</dt>
    1.18              <dd>
    1.19                This method returns immediately and creates a <a>cursor</a> over the 
    1.20                <a>records</a> of this <a>index</a>. The <a>range</a> of this <a>cursor</a>
    1.21 @@ -1503,7 +1503,7 @@
    1.22                  <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
    1.23                </dl>
    1.24              </dd>
    1.25 -            <dt>IDBRequest getObject()</dt>
    1.26 +            <dt>IDBRequest get()</dt>
    1.27              <dd>
    1.28                This method returns immediately and retrieves the value from this <a>index</a>'s
    1.29                <a>referenced</a> <a>object store</a> for the record corresponding to the given
    1.30 @@ -1527,7 +1527,7 @@
    1.31                  <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
    1.32                </dl>
    1.33              </dd>
    1.34 -            <dt>IDBRequest get()</dt>
    1.35 +            <dt>IDBRequest getKey()</dt>
    1.36              <dd>
    1.37                This method returns immediately and retrieves the value from this <a>index</a>
    1.38                for the record corresponding to the given <var>key</var> parameter by 
    1.39 @@ -1606,7 +1606,9 @@
    1.40                <dl class="exception" title="IDBDatabaseException">
    1.41                  <dt>NOT_ALLOWED_ERR</dt>
    1.42                  <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a> or
    1.43 -                the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>.</dd>
    1.44 +                the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>. Also
    1.45 +                thrown if cursor was created using
    1.46 +                <a class="idlType" href="#widl-IDBIndex-openKeyCursor"><code>openKeyCursor</code></a>.</dd>
    1.47                  <dt>DATA_ERR</dt>
    1.48                  <dd> The underlying <a>object store</a> uses <a>in-line keys</a> and the property at the 
    1.49                  <a title="object store key path">key path</a> does not match the key in this <a>cursor</a>'s
    1.50 @@ -1650,7 +1652,9 @@
    1.51                <dl class="exception" title="IDBDatabaseException">
    1.52                  <dt>NOT_ALLOWED_ERR</dt>
    1.53                  <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a> or
    1.54 -                the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>.</dd>
    1.55 +                the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>. Also
    1.56 +                thrown if cursor was created using
    1.57 +                <a class="idlType" href="#widl-IDBIndex-openKeyCursor"><code>openKeyCursor</code></a>.</dd>
    1.58                </dl>
    1.59              </dd>
    1.60            </dl>
    1.61 @@ -2290,7 +2294,8 @@
    1.62              <dd>
    1.63                On getting, provide the <a>unique</a> flag of this <a>index</a>.
    1.64              </dd>
    1.65 -            <dt>void openObjectCursor()</dt>
    1.66 +
    1.67 +            <dt>void openCursor()</dt>
    1.68              <dd>
    1.69                Create a <a>cursor</a> over the <a>records</a> of this 
    1.70                <a>index</a>'s <a>referenced</a> <a>object store</a> as arranged by
    1.71 @@ -2311,7 +2316,8 @@
    1.72                  </dd>
    1.73                </dl>
    1.74              </dd>
    1.75 -            <dt>void openCursor()</dt>
    1.76 +
    1.77 +            <dt>void openKeyCursor()</dt>
    1.78              <dd>
    1.79                Create a <a>cursor</a> over the <a>records</a> of this 
    1.80                <a>index</a>. The <a>range</a> of this <a>cursor</a> matches 
    1.81 @@ -2331,39 +2337,7 @@
    1.82                  </dd>
    1.83                </dl>
    1.84              </dd>
    1.85 -            <dt>any put()</dt>
    1.86 -            <dd>
    1.87 -              Store the given value in this <a>index</a> by following
    1.88 -              the <a>steps for storing a record into an index</a>. The
    1.89 -              returned object from this method is the key for the stored record.
    1.90 -              <dl class="parameters">
    1.91 -                <dt>any value</dt>
    1.92 -                <dd>The value to be stored in the record</dd>
    1.93 -                <dt>optional any key</dt>
    1.94 -                <dd>The key used to identify the record</dd>
    1.95 -              </dl>
    1.96 -            </dd>
    1.97 -            <dt>any add()</dt>
    1.98 -            <dd>
    1.99 -              Store the given value in this <a>index</a> by following
   1.100 -              the <a>steps for storing a record into an index</a> and the no-overwrite flag set. The
   1.101 -              returned object from this method is the key for the stored record.
   1.102 -              <dl class="parameters">
   1.103 -                <dt>any value</dt>
   1.104 -                <dd>The value to be stored in the record</dd>
   1.105 -                <dt>optional any key</dt>
   1.106 -                <dd>The key used to identify the record</dd>
   1.107 -              </dl>
   1.108 -              <dl class="exception" title="IDBDatabaseException">
   1.109 -                <dt>CONSTRAINT_ERR</dt>
   1.110 -                <dd> 
   1.111 -                A record exists in this <a>index</a> for the key <var>key</var> 
   1.112 -                parameter or this <a>index</a> is <a>auto-populated</a> or if no
   1.113 -                record exists with key <var>value</var> parameter in the <a>index</a>'s <a>referenced</a> <a>object store</a>.
   1.114 -                </dd>
   1.115 -              </dl>
   1.116 -            </dd>
   1.117 -            <dt>any getObject()</dt>
   1.118 +            <dt>any get()</dt>
   1.119              <dd>
   1.120                Retrieve the value from this <a>index</a>'s <a>referenced</a>
   1.121                <a>object store</a> for the record corresponding to the given key
   1.122 @@ -2380,7 +2354,7 @@
   1.123                  </dd>
   1.124                </dl>
   1.125              </dd>
   1.126 -            <dt>any get()</dt>
   1.127 +            <dt>any getKey()</dt>
   1.128              <dd>
   1.129                Retrieve the value from this <a>index</a> for the record 
   1.130                corresponding to the given key by following the 
   1.131 @@ -2397,22 +2371,6 @@
   1.132                  </dd>
   1.133                </dl>
   1.134              </dd>
   1.135 -            <dt>void delete()</dt>
   1.136 -            <dd>
   1.137 -              Remove the records from this <a>index</a> by following
   1.138 -              the <a>steps for deleting a record from an index</a>
   1.139 -              corresponding to the given key.
   1.140 -              <dl class="parameters">
   1.141 -                <dt>any key</dt>
   1.142 -                <dd>Key identifying the record to be deleted</dd>
   1.143 -              </dl>
   1.144 -              <dl class="exception" title="IDBDatabaseException">
   1.145 -                <dt>NOT_FOUND_ERR</dt>
   1.146 -                <dd>A record did not exist in this <a>index</a> 
   1.147 -                for the key <var>key</var> parameter.
   1.148 -                </dd>
   1.149 -              </dl>
   1.150 -            </dd>
   1.151            </dl>
   1.152          </section>
   1.153          <section class="section" id="cursor-sync">  
   1.154 @@ -2744,50 +2702,6 @@
   1.155          </section>
   1.156          
   1.157          <section class="section">
   1.158 -          <h4>Index Storage steps</h4>
   1.159 -          <p>
   1.160 -            The <dfn>steps for storing a record into an index</dfn> are as follows. 
   1.161 -            These steps MUST be run with four parameters: the <a>index</a>,
   1.162 -            a key, a value, and a no-overwrite flag.
   1.163 -          </p>
   1.164 -          <ol>
   1.165 -            <li>
   1.166 -              Let <var>index</var> be the <a>index</a>, <var>key</var> be
   1.167 -              the key and <var>value</var> be the value passed to these steps.
   1.168 -            </li>
   1.169 -            <li>
   1.170 -              If <var>index</var> has a <a title="index key path">key path</a>,
   1.171 -              then terminate these steps and set error code <a class="idlType" href="#widl-IDBDatabaseException-CONSTRAINT_ERR"><code>CONSTRAINT_ERR</code></a>.
   1.172 -            </li>
   1.173 -            <li>
   1.174 -              If the no-overwrite flag was passed to these steps and is set, and 
   1.175 -              a record already exists in <var>index</var> with its key being 
   1.176 -              <var>key</var>, then terminate these steps and set error code 
   1.177 -              <a class="idlType" href="#widl-IDBDatabaseException-CONSTRAINT_ERR"><code>CONSTRAINT_ERR</code></a>.
   1.178 -            </li>
   1.179 -            <li>
   1.180 -              If no record exists in <var>index</var>'s <a>referenced</a>
   1.181 -              <a>object store</a> whose key is <var>value</var>, then terminate
   1.182 -              these steps and set error code <a class="idlType" href="#widl-IDBDatabaseException-CONSTRAINT_ERR"><code>CONSTRAINT_ERR</code></a>.
   1.183 -            </li>
   1.184 -            <li>
   1.185 -              <p>
   1.186 -                Store a record in <var>index</var> containing <var>key</var> as its key  
   1.187 -                and <var>value</var> as its value. 
   1.188 -              </p>
   1.189 -              <div class="note">
   1.190 -                Storing would mean inserting if no record exists for that key
   1.191 -                or updating an existing record, otherwise. 
   1.192 -              </div>
   1.193 -            </li>
   1.194 -            
   1.195 -            <li>
   1.196 -              Return the <var>key</var>.
   1.197 -            </li>
   1.198 -          </ol>        
   1.199 -        </section>
   1.200 -        
   1.201 -        <section class="section">
   1.202            <h4>Object Store Retrieval steps</h4>
   1.203            <p>
   1.204              The <dfn>steps for retrieving a record from an object store</dfn> are
     2.1 --- a/Speclet_021_IDB_API_Algorithms.html	Fri Oct 22 14:52:26 2010 -0700
     2.2 +++ b/Speclet_021_IDB_API_Algorithms.html	Fri Oct 22 21:38:59 2010 -0700
     2.3 @@ -236,50 +236,6 @@
     2.4          </section>
     2.5          
     2.6          <section class="section">
     2.7 -          <h4>Index Storage steps</h4>
     2.8 -          <p>
     2.9 -            The <dfn>steps for storing a record into an index</dfn> are as follows. 
    2.10 -            These steps MUST be run with four parameters: the <a>index</a>,
    2.11 -            a key, a value, and a no-overwrite flag.
    2.12 -          </p>
    2.13 -          <ol>
    2.14 -            <li>
    2.15 -              Let <var>index</var> be the <a>index</a>, <var>key</var> be
    2.16 -              the key and <var>value</var> be the value passed to these steps.
    2.17 -            </li>
    2.18 -            <li>
    2.19 -              If <var>index</var> has a <a title="index key path">key path</a>,
    2.20 -              then terminate these steps and set error code <a class="idlType" href="#widl-IDBDatabaseException-CONSTRAINT_ERR"><code>CONSTRAINT_ERR</code></a>.
    2.21 -            </li>
    2.22 -            <li>
    2.23 -              If the no-overwrite flag was passed to these steps and is set, and 
    2.24 -              a record already exists in <var>index</var> with its key being 
    2.25 -              <var>key</var>, then terminate these steps and set error code 
    2.26 -              <a class="idlType" href="#widl-IDBDatabaseException-CONSTRAINT_ERR"><code>CONSTRAINT_ERR</code></a>.
    2.27 -            </li>
    2.28 -            <li>
    2.29 -              If no record exists in <var>index</var>'s <a>referenced</a>
    2.30 -              <a>object store</a> whose key is <var>value</var>, then terminate
    2.31 -              these steps and set error code <a class="idlType" href="#widl-IDBDatabaseException-CONSTRAINT_ERR"><code>CONSTRAINT_ERR</code></a>.
    2.32 -            </li>
    2.33 -            <li>
    2.34 -              <p>
    2.35 -                Store a record in <var>index</var> containing <var>key</var> as its key  
    2.36 -                and <var>value</var> as its value. 
    2.37 -              </p>
    2.38 -              <div class="note">
    2.39 -                Storing would mean inserting if no record exists for that key
    2.40 -                or updating an existing record, otherwise. 
    2.41 -              </div>
    2.42 -            </li>
    2.43 -            
    2.44 -            <li>
    2.45 -              Return the <var>key</var>.
    2.46 -            </li>
    2.47 -          </ol>        
    2.48 -        </section>
    2.49 -        
    2.50 -        <section class="section">
    2.51            <h4>Object Store Retrieval steps</h4>
    2.52            <p>
    2.53              The <dfn>steps for retrieving a record from an object store</dfn> are
     3.1 --- a/Speclet_022_IDB_API_Synchronous_APIs.html	Fri Oct 22 14:52:26 2010 -0700
     3.2 +++ b/Speclet_022_IDB_API_Synchronous_APIs.html	Fri Oct 22 21:38:59 2010 -0700
     3.3 @@ -666,7 +666,8 @@
     3.4              <dd>
     3.5                On getting, provide the <a>unique</a> flag of this <a>index</a>.
     3.6              </dd>
     3.7 -            <dt>void openObjectCursor()</dt>
     3.8 +
     3.9 +            <dt>void openCursor()</dt>
    3.10              <dd>
    3.11                Create a <a>cursor</a> over the <a>records</a> of this 
    3.12                <a>index</a>'s <a>referenced</a> <a>object store</a> as arranged by
    3.13 @@ -687,7 +688,8 @@
    3.14                  </dd>
    3.15                </dl>
    3.16              </dd>
    3.17 -            <dt>void openCursor()</dt>
    3.18 +
    3.19 +            <dt>void openKeyCursor()</dt>
    3.20              <dd>
    3.21                Create a <a>cursor</a> over the <a>records</a> of this 
    3.22                <a>index</a>. The <a>range</a> of this <a>cursor</a> matches 
    3.23 @@ -707,39 +709,7 @@
    3.24                  </dd>
    3.25                </dl>
    3.26              </dd>
    3.27 -            <dt>any put()</dt>
    3.28 -            <dd>
    3.29 -              Store the given value in this <a>index</a> by following
    3.30 -              the <a>steps for storing a record into an index</a>. The
    3.31 -              returned object from this method is the key for the stored record.
    3.32 -              <dl class="parameters">
    3.33 -                <dt>any value</dt>
    3.34 -                <dd>The value to be stored in the record</dd>
    3.35 -                <dt>optional any key</dt>
    3.36 -                <dd>The key used to identify the record</dd>
    3.37 -              </dl>
    3.38 -            </dd>
    3.39 -            <dt>any add()</dt>
    3.40 -            <dd>
    3.41 -              Store the given value in this <a>index</a> by following
    3.42 -              the <a>steps for storing a record into an index</a> and the no-overwrite flag set. The
    3.43 -              returned object from this method is the key for the stored record.
    3.44 -              <dl class="parameters">
    3.45 -                <dt>any value</dt>
    3.46 -                <dd>The value to be stored in the record</dd>
    3.47 -                <dt>optional any key</dt>
    3.48 -                <dd>The key used to identify the record</dd>
    3.49 -              </dl>
    3.50 -              <dl class="exception" title="IDBDatabaseException">
    3.51 -                <dt>CONSTRAINT_ERR</dt>
    3.52 -                <dd> 
    3.53 -                A record exists in this <a>index</a> for the key <var>key</var> 
    3.54 -                parameter or this <a>index</a> is <a>auto-populated</a> or if no
    3.55 -                record exists with key <var>value</var> parameter in the <a>index</a>'s <a>referenced</a> <a>object store</a>.
    3.56 -                </dd>
    3.57 -              </dl>
    3.58 -            </dd>
    3.59 -            <dt>any getObject()</dt>
    3.60 +            <dt>any get()</dt>
    3.61              <dd>
    3.62                Retrieve the value from this <a>index</a>'s <a>referenced</a>
    3.63                <a>object store</a> for the record corresponding to the given key
    3.64 @@ -756,7 +726,7 @@
    3.65                  </dd>
    3.66                </dl>
    3.67              </dd>
    3.68 -            <dt>any get()</dt>
    3.69 +            <dt>any getKey()</dt>
    3.70              <dd>
    3.71                Retrieve the value from this <a>index</a> for the record 
    3.72                corresponding to the given key by following the 
    3.73 @@ -773,22 +743,6 @@
    3.74                  </dd>
    3.75                </dl>
    3.76              </dd>
    3.77 -            <dt>void delete()</dt>
    3.78 -            <dd>
    3.79 -              Remove the records from this <a>index</a> by following
    3.80 -              the <a>steps for deleting a record from an index</a>
    3.81 -              corresponding to the given key.
    3.82 -              <dl class="parameters">
    3.83 -                <dt>any key</dt>
    3.84 -                <dd>Key identifying the record to be deleted</dd>
    3.85 -              </dl>
    3.86 -              <dl class="exception" title="IDBDatabaseException">
    3.87 -                <dt>NOT_FOUND_ERR</dt>
    3.88 -                <dd>A record did not exist in this <a>index</a> 
    3.89 -                for the key <var>key</var> parameter.
    3.90 -                </dd>
    3.91 -              </dl>
    3.92 -            </dd>
    3.93            </dl>
    3.94          </section>
    3.95          <section class="section" id="cursor-sync">  
     4.1 --- a/Speclet_023_IDB_API_Asynchronous_APIs.html	Fri Oct 22 14:52:26 2010 -0700
     4.2 +++ b/Speclet_023_IDB_API_Asynchronous_APIs.html	Fri Oct 22 21:38:59 2010 -0700
     4.3 @@ -814,7 +814,7 @@
     4.4              <dd>
     4.5                On getting, provide the <a>unique</a> flag of this <a>index</a>.
     4.6              </dd>
     4.7 -            <dt>IDBRequest openObjectCursor()</dt>
     4.8 +            <dt>IDBRequest openCursor()</dt>
     4.9              <dd>
    4.10                This method returns immediately and creates a <a>cursor</a> over the 
    4.11                <a>records</a> of this <a>index</a>'s <a>referenced</a> <a>object store</a> 
    4.12 @@ -845,7 +845,7 @@
    4.13                  <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
    4.14                </dl>
    4.15              </dd>
    4.16 -            <dt>IDBRequest openCursor()</dt>
    4.17 +            <dt>IDBRequest openKeyCursor()</dt>
    4.18              <dd>
    4.19                This method returns immediately and creates a <a>cursor</a> over the 
    4.20                <a>records</a> of this <a>index</a>. The <a>range</a> of this <a>cursor</a>
    4.21 @@ -875,7 +875,7 @@
    4.22                  <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
    4.23                </dl>
    4.24              </dd>
    4.25 -            <dt>IDBRequest getObject()</dt>
    4.26 +            <dt>IDBRequest get()</dt>
    4.27              <dd>
    4.28                This method returns immediately and retrieves the value from this <a>index</a>'s
    4.29                <a>referenced</a> <a>object store</a> for the record corresponding to the given
    4.30 @@ -899,7 +899,7 @@
    4.31                  <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a>.</dd>
    4.32                </dl>
    4.33              </dd>
    4.34 -            <dt>IDBRequest get()</dt>
    4.35 +            <dt>IDBRequest getKey()</dt>
    4.36              <dd>
    4.37                This method returns immediately and retrieves the value from this <a>index</a>
    4.38                for the record corresponding to the given <var>key</var> parameter by 
    4.39 @@ -978,7 +978,9 @@
    4.40                <dl class="exception" title="IDBDatabaseException">
    4.41                  <dt>NOT_ALLOWED_ERR</dt>
    4.42                  <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a> or
    4.43 -                the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>.</dd>
    4.44 +                the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>. Also
    4.45 +                thrown if cursor was created using
    4.46 +                <a class="idlType" href="#widl-IDBIndex-openKeyCursor"><code>openKeyCursor</code></a>.</dd>
    4.47                  <dt>DATA_ERR</dt>
    4.48                  <dd> The underlying <a>object store</a> uses <a>in-line keys</a> and the property at the 
    4.49                  <a title="object store key path">key path</a> does not match the key in this <a>cursor</a>'s
    4.50 @@ -1022,7 +1024,9 @@
    4.51                <dl class="exception" title="IDBDatabaseException">
    4.52                  <dt>NOT_ALLOWED_ERR</dt>
    4.53                  <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a> or
    4.54 -                the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>.</dd>
    4.55 +                the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>. Also
    4.56 +                thrown if cursor was created using
    4.57 +                <a class="idlType" href="#widl-IDBIndex-openKeyCursor"><code>openKeyCursor</code></a>.</dd>
    4.58                </dl>
    4.59              </dd>
    4.60            </dl>