Rewrite transaction handling. Bugs 10305, 9562, 10007, 10765
authorJonas Sicking <jonas@sicking.cc>
Fri, 29 Oct 2010 09:13:37 -0700
changeset 7326e7d99ab935
parent 72 7ded3f76226c
child 74 e5a08025e518
Rewrite transaction handling. Bugs 10305, 9562, 10007, 10765
Overview.html
Speclet_020_IDB_API_Constructs.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	Mon Oct 25 11:08:37 2010 -0700
     1.2 +++ b/Overview.html	Fri Oct 29 09:13:37 2010 -0700
     1.3 @@ -474,45 +474,275 @@
     1.4              Each <a>origin</a> has an associated set of 
     1.5              <a title="database">databases</a>. A <dfn>database</dfn> comprises
     1.6              one or more <a title="object store">object stores</a>.
     1.7 +          </p>
     1.8            <p>
     1.9 -            Each <a>database</a> has a <a title="valid-name">valid</a> 
    1.10 -            <dfn title="database name">name</dfn> and a human readable 
    1.11 -            description. A <dfn title="valid-name">valid name</dfn> is any 
    1.12 -            string including the empty string. An exact match of names means 
    1.13 -            that their UTF-8 encodings are identical.
    1.14 +            Every <a>database</a> has a <dfn title="database name">name</dfn> which identifies it
    1.15 +            within a specific <a>origin</a>. The name can be any string value, including the empty string, and
    1.16 +            stays constant for the lifetime of the database. Each <a>database</a> also has a current
    1.17 +            <dfn>version</dfn>.
    1.18            </p>
    1.19 -          
    1.20 -          <div class="note">
    1.21 -            If an implementation does not support all sets of strings, it may 
    1.22 -            implement support for arbitrary strings by mapping
    1.23 -            database names (e.g. using a hashing algorithm) to the supported
    1.24 -            set of names.
    1.25 -          </div>
    1.26 -          <p>
    1.27 -            Each <a>database</a> also has a current <dfn>version</dfn>.
    1.28 +          <p class="note">
    1.29 +            Implementations MUST support all names. If a implementation
    1.30 +            uses a storage mechanism which can't handle arbitrary database names,
    1.31 +            the implementation must use an escaping mechanism or something similar
    1.32 +            to map the provided name to a name that it can handle.
    1.33            </p>
    1.34            <div class="note">
    1.35              Each <a>database</a> has one version at a time; a <a>database</a> 
    1.36 -            can't exist in multiple versions at once. 
    1.37 +            can't exist in multiple versions at once. The only way to change the version is using a VERSION_CHANGE
    1.38 +            <a>transaction</a>.
    1.39            </div>
    1.40            <p>
    1.41 -            The act of opening a <a>database</a> creates a database 
    1.42 -            <dfn>connection</dfn>. There MAY be multiple 
    1.43 -            <a title="connection">connections</a> to a given <a>database</a> 
    1.44 -            at any given time. An operation that is attempting to read a 
    1.45 -            given piece of data in a <a>database</a> is called a 
    1.46 -            <dfn>reader</dfn> and one that is attempting to write a piece of 
    1.47 -            data is called a <dfn>writer</dfn>.
    1.48 -            <a title="reader">Readers</a> and <a title="writer">writers</a> SHOULD only operate through
    1.49 -            <a title="transaction">transactions</a>. A <a>connection</a> MAY have 
    1.50 -            any number of <dfn>active</dfn> <a title="transaction">transactions</a>.
    1.51 +            Each database contain a set of <a>object store</a>s. The set of <a>object store</a>s
    1.52 +            can changed, but can only be changed using VERSION_CHANGE transactions. When a new database is
    1.53 +            created it doesn't contain any <a>object store</a>s and has the empty string as <a>version</a>.
    1.54            </p>
    1.55            <p>
    1.56 -            <a><code>IDBDatabase</code></a> and <a><code>IDBDatabaseSync</code></a>
    1.57 -            interfaces represent <a title="connection">connections</a> to a <a>database</a>. 
    1.58 +            The act of opening a <a>database</a> creates a <dfn>connection</dfn>. There MAY be multiple 
    1.59 +            <a>connection</a>s to a given <a>database</a> at any given time. Each connection has a
    1.60 +            <dfn>closePending</dfn> flag which initially is set to false.
    1.61 +          </p>
    1.62 +          <p>
    1.63 +            When a <a>connection</a> is initially created it is in <var>opened</var> state. The connection
    1.64 +            can be <dfn title="database close">closed</dfn> through several means. If the connection is GCed
    1.65 +            or execution context where the <a>connection</a> is created is destroyed (for example due to the
    1.66 +            user navigating away from that page), the connection is closed. The connection can also be closed
    1.67 +            explicitly using the <a>steps for closing a database connection</a>. When the connection is closed
    1.68 +            the <a>closePending</a> flag is always set to true if it hasn't already been.
    1.69 +          </p>
    1.70 +          <p>
    1.71 +            The <a><code>IDBDatabase</code></a> and <a><code>IDBDatabaseSync</code></a>
    1.72 +            interfaces represent a <a>connection</a> to a <a>database</a>. 
    1.73            </p>
    1.74          </section>  <!-- IDBDatabase -->
    1.75 -        
    1.76 +
    1.77 +        <section id="transaction-concept" class="section">
    1.78 +          <h4>Transaction</h4>
    1.79 +          <p>
    1.80 +            A <dfn>transaction</dfn> is used to interact with the data in a <a>database</a>.
    1.81 +            Whenever data is read or written to the database this is done using a <a>transaction</a>.
    1.82 +          </p>
    1.83 +          <p>
    1.84 +            All transactions are created using a <a>connection</a>.
    1.85 +            The transaction has a <a>mode</a> which determines which types of interactions can be performed
    1.86 +            using the transaction. The <a>mode</a> is set when the transaction is created and remains
    1.87 +            constant for the lifetime of the transaction. The transaction also has a <dfn>scope</dfn> which
    1.88 +            determines which <a>object store</a>s the transaction can interact with. Finally, transactions
    1.89 +            have a <dfn>active</dfn> flag, which determines if new <a>request</a>s can currently be placed
    1.90 +            against the transaction. Finally, transactions also contain a <dfn>request list<dfn> of
    1.91 +            <a>request</a>s which have been placed against the transaction.
    1.92 +          </p>
    1.93 +          <p>
    1.94 +            Transactions are either static or dynamic which determines if the <a>scope</a> of the transaction
    1.95 +            can change during the lifetime of the transaction. <dfn>Static</dfn> transactions have a constant
    1.96 +            scope which is determined when the transaction is created and remains contant for the lifetime of
    1.97 +            the transaction. <dfn>Dynamic</dfn> transactions scope can change during the lifetime of the
    1.98 +            transaction.
    1.99 +          </p>
   1.100 +          <p class="issue">TODO: decide what happens when dynamic transactions need to lock a database
   1.101 +            object that is already exclusively locked by another transaction.
   1.102 +          </p>
   1.103 +          <p>
   1.104 +            <a title="transaction">Transactions</a> offer some protection from 
   1.105 +            application and system failures. A <a>transaction</a> may be used to
   1.106 +            store multiple data records or to conditionally modify certain data 
   1.107 +            records. A <a>transaction</a> represents an atomic and durable set 
   1.108 +            of data access and mutation operations. 
   1.109 +          </p>
   1.110 +          <p>
   1.111 +            <a title="transaction">Transactions</a> are expected to be short lived. This is encouraged
   1.112 +            using the automatically committing functionality described below. Authors can still cause
   1.113 +            transactions to run for a long time, however this is generally not a usage pattern which
   1.114 +            is recommended and can lead to bad user experience in some implementations.
   1.115 +          </p>
   1.116 +          <p>
   1.117 +            The <dfn title="transaction lifetime">lifetime</dfn> of a <a>transaction</a> is as follows:
   1.118 +          </p>
   1.119 +          <ol>
   1.120 +            <li>
   1.121 +              A transaction is <dfn title="transaction create">created</dfn> using of one of the available explicit
   1.122 +              APIs, for example <a class="idlType" href="#widl-IDBDatabase-transaction">IDBDatabase.transaction</a>.
   1.123 +              Which constructor is used, and the arguments passed to that constructor, determines if the transaction
   1.124 +              is <a>static</a> or <a>dynamic</a>, as well as which <a>mode</a> the transaction uses. If the transaction
   1.125 +              is <a>static</a>, the constructor arguments also determine what the <a>scope</a> of the transaction is.
   1.126 +              When a transaction is created its <a>active</a> flag is initially set to true.
   1.127 +            </li>
   1.128 +            <li>
   1.129 +              The implementation MUST allow <a>request</a>s to be <a title="place request">placed</a> against the transaction
   1.130 +              whenever the <a>active</a> flag is true. This is the case even if the transaction has not yet been
   1.131 +              <a title="transaction start">started</a>. Until the transaction is <a title="transaction start">started</a>
   1.132 +              the implementation MUST NOT execute these requests, but the implementation MUST still keep track of the
   1.133 +              <a>request</a>s and their order. Requests may only be placed against the transaction while the transaction
   1.134 +              is <a>active</a>. If a request is attempted to be placed against a transaction when it is not
   1.135 +              <a>active</a>, the implementation MUST reject the attempt by throwing a TRANSACTION_INACTIVE_ERR exception.
   1.136 +            </li>
   1.137 +            <li>
   1.138 +              Once an implementation is able to enforce the constraints defined for the <a>mode</a> of
   1.139 +              the transaction, defined below, the implementation MUST asynchronously
   1.140 +              <dfn title="transaction start">start</dfn> the transaction. When this happens is affected
   1.141 +              by the <a>mode</a> in which the transaction is opened, and which <a>object store</a>s are
   1.142 +              included in <a>scope</a> of the transaction.
   1.143 +            </li>
   1.144 +            <li class="issue">
   1.145 +              <p>
   1.146 +                Should we also define that if an implementation can't run two transactions at the same time,
   1.147 +                it MUST <a title="transaction start">start</a> them in the order they were
   1.148 +                <a title="transaction create">created</a>. Maybe only specify this if they have any overlapping
   1.149 +                <a>scope</a>. If we don't do this then starting two write transactions at the same time could
   1.150 +                result in the second one that's created running before the first one that is created.
   1.151 +              </p>
   1.152 +              <p>
   1.153 +                At least we need to ensure that a READ_ONLY transaction which is created after a READ_WRITE
   1.154 +                transaction has started sees the data that the READ_WRITE transaction wrote, and not a snapshot
   1.155 +                of what the object store looked like before the READ_WRITE transaction was started.
   1.156 +              </p>
   1.157 +              <p>
   1.158 +                Might be best to define this as part of the <a>mode</a> restrictions.
   1.159 +              </p>
   1.160 +            </li>
   1.161 +            <li>
   1.162 +              Once the transaction has been <a title="transaction start">started</a> the implementation can
   1.163 +              start executing the <a>request</a>s placed against the transaction. Unless otherwise defined requests
   1.164 +              MUST be executed in the order they are placed against the transaction. Likewise, their result MUST
   1.165 +              be returned in the order the request was placed against a specific transaction.
   1.166 +              There is no guarentee about the order that results from requests in different transactions are returned.
   1.167 +              Similarly, the isolation <a>mode</a> ensure that it doesn't matter which order requests placed against
   1.168 +              different transactions are executed.
   1.169 +            </li>
   1.170 +            <li>
   1.171 +              At any time a transaction can be <dfn>abort</dfn>ed, even if the transaction isn't currently
   1.172 +              <a>active</a>. When a transaction is aborted the implementation MUST undo (roll back) any changes
   1.173 +              made to the <a>database</a> using the transaction. This includes both changes to the contents of
   1.174 +              <a>object store</a>s as well as additions and removals of <a>object store</a>s and <a>index</a>es.
   1.175 +              <p class="note">
   1.176 +                A transaction can be aborted at any time before it is <a title="transaction finish">finished</a>.
   1.177 +                Including if it isn't <a>active</a> or hasn't yet
   1.178 +                <a title="transaction start">started</a>.
   1.179 +            </li>
   1.180 +            <li>
   1.181 +              Once a transaction no longer can become <a>active</a>, and if the transaction
   1.182 +              hasn't been <a>abort</a>ed, the implementation MUST automatically attempt to
   1.183 +              <dfn title="commit">commit</dfn> it. This usually happens after all requests placed against the
   1.184 +              transaction has been executed and their returned results handled, but no new requests has been placed
   1.185 +              against the transaction. When a transaction is committed implementation MUST atomically write
   1.186 +              any changes to the <a>database</a> made by requests placed against the transaction. That is, either all
   1.187 +              of the changes MUST be written, or if an error occurs, such as a disk write error, the implementation
   1.188 +              MUST NOT write any of the changes to the database. If such an error occurs the implementation MUST
   1.189 +              <a>abort</a> the transaction.
   1.190 +            </li>
   1.191 +            <li>
   1.192 +              When a transaction is <a>commit</a>ted or <a>abort</a>ed, it is said to be
   1.193 +              <def title="transaction finish">finished</def>. If a transaction can't be finished, for example
   1.194 +              due to the implementation crashing or the user taking some explicit action to cancel it, the
   1.195 +              implementation MUST <a>abort</a> the transaction.
   1.196 +            </li>
   1.197 +          </ol>
   1.198 +          <p>
   1.199 +            Transactions are opened in one of three <dfn title="mode">modes</dfn>. The mode
   1.200 +            determine how concurrent access to <a>object store</a>s in the transaction is isolated.
   1.201 +          </p>
   1.202 +          <ol>
   1.203 +            <li><code><dfn>READ_ONLY</dfn></code></li>
   1.204 +            <li><code><dfn>READ_WRITE</dfn></code></li>
   1.205 +            <li><code><dfn>VERSION_CHANGE</dfn></code></li>
   1.206 +          </ol>
   1.207 +
   1.208 +          <p>
   1.209 +            The transaction <a>mode</a> determines both which operations are allowed to be performed
   1.210 +            during the transaction, as well whether two transactions can run concurrently or not.
   1.211 +            Which operations are allowed be be performed are defined in detail below, but in general
   1.212 +            transactions opened in <code><a>READ_ONLY</a><code> mode are only allowed to perform
   1.213 +            reading operations which does not change data. READ_WRITE transactions are allowed to
   1.214 +            perform reading and writing transactions to existing <a>object store</a>s, where as
   1.215 +            VERSION_CHANGE transactions are allowed to perform any operations, including ones that
   1.216 +            delete and create <a>object store</a>s and <a>index</a>es.
   1.217 +          </p>
   1.218 +          
   1.219 +          <p>
   1.220 +            A VERSION_CHANGE transaction can never run concurrently with other transactions. When
   1.221 +            a VERSION_CHANGE transaction is created, the implementation MUST wait to
   1.222 +            <a title="transaction start">start</a> the VERSION_CHANGE transaction until no other transactions
   1.223 +            against the same <a>database</a> are running. As long as the VERSION_CHANGE transaction, the implementation
   1.224 +            MUST wait with <a title="transaction start">starting</a> any other transactions against the same <a>database</a>
   1.225 +            until the VERSION_CHANGE transaction is finished.
   1.226 +          </p>
   1.227 +          <p>
   1.228 +            Any number of transactions opened in <a>READ_ONLY</a> mode are allowed to run concurrently,
   1.229 +            even if the transaction's <a>scope</a> overlap and include the same <a>object store</a>s.
   1.230 +            As long as a READ_ONLY transaction is running, the data that the implementation returns
   1.231 +            through <a>request</a>s created with that transaction MUST remain
   1.232 +            constant. That is, two requests to read the same piece of data MUST yield the same result
   1.233 +            both for the case when data is found and the result is that data, and for the case when data
   1.234 +            is not found and a lack of data is indicated.
   1.235 +          </p>
   1.236 +          <p>
   1.237 +            There are a number of ways that an implementation ensure this. It can prevent
   1.238 +            READ_WRITE transactions whose scope overlap the scope of the READ_ONLY transaction from
   1.239 +            starting until the READ_ONLY transaction is finished. Or it can allow the READ_ONLY
   1.240 +            transaction to see a snapshot of contents of the <a>object store</a>s which is taken when
   1.241 +            the READ_ONLY transaction is started.
   1.242 +          </p>
   1.243 +          <p>
   1.244 +            Similarly, implementations MUST ensure that a READ_WRITE transaction is only affected by
   1.245 +            changes to <a>object store</a>s that are made using the transaction itself. I.e. the
   1.246 +            implementation MUST ensure that another transaction does not modify the contents of
   1.247 +            <a>object store</a>s in the READ_WRITE transactions <a>scope</a>. The implementation
   1.248 +            MUST also ensure that if the READ_WRITE transaction completes successfully, that the
   1.249 +            changes written to <a>object store</a>s using the transaction can be comitted to the
   1.250 +            <a>database</a> without merge conflicts. An implementation MUST NOT abort a transaction
   1.251 +            due to merge conflicts.
   1.252 +          </p>
   1.253 +          <p>
   1.254 +            A result of these requirements is that an implementation MUST NOT allow two READ_WRITE
   1.255 +            transactions access the same <a>object store</a> at the same time. Even to perform just
   1.256 +            read operations. One implementation strategy is to never start a READ_WRITE transaction
   1.257 +            until all other READ_WRITE transactions with overlapping <a>scope</a>s have finished.
   1.258 +          </p>
   1.259 +          <p class="issue">
   1.260 +            TODO: This requirement could be tightened further. Currently two READ_WRITE transactions
   1.261 +            with <b>partially</b> overlapping scopes can run in paralell, until both (or "the second") of
   1.262 +            them touch object stores in the overlapping scope.
   1.263 +          </p>
   1.264 +          <p>
   1.265 +            User agents MUST ensure a reasonable level of fairness across transactions to prevent
   1.266 +            starvation. For example if multiple READ_ONLY transaction are started one after another
   1.267 +            the implementation MUST ensure that that doesn't indefinitely prevent a pending READ_WRITE
   1.268 +            transaction from <a title="transaction start">starting</a>.
   1.269 +          </p>
   1.270 +          <p>
   1.271 +            Conforming user agents MUST automatically abort a <a>transaction</a> at
   1.272 +            the end of the scope in which it was created, if an exception is propagated to that scope.
   1.273 +          </p>
   1.274 +          <p>
   1.275 +            Static <a>transaction</a> objects implement the 
   1.276 +            <a><code>IDBTransaction</code></a> or the
   1.277 +            <a><code>IDBTransactionSync</code></a> interfaces.
   1.278 +          </p>
   1.279 +          <p>
   1.280 +             Dynamic <a>transaction</a> objects implement the 
   1.281 +            <a><code>IDBDynamicTransaction</code></a> or the
   1.282 +            <a><code>IDBDynamicTransactionSync</code></a> interfaces.
   1.283 +          </p>
   1.284 +          <div class="issue">
   1.285 +            <p>Define dynamic transactions if we agree they should be part of this specification.</p>
   1.286 +          </div>
   1.287 +        </section> <!-- IDBTransaction -->
   1.288 +
   1.289 +        <section class="section" id="request-concept">
   1.290 +          <h4>Requests</h4>
   1.291 +          <p>
   1.292 +            Each reading and writing operation on a <a>database</a> is done using a <dfn>request</dfn>.
   1.293 +            Every request represents one read or write operation. <a>Request</a>s are always belong to
   1.294 +            a <a>transaction</a>. The only exception to this is the request created when a <a>connection</a>
   1.295 +            is opened. <a>Request</a>s have a <dfn title="request done"><var>done</var></dfn> flag which
   1.296 +            initially is false, and a <dfn title="request source">source</dfn> object.
   1.297 +          </p>
   1.298 +          <p>
   1.299 +            When a request is created, it is always <dfn title="place request">placed</a> against a
   1.300 +            <a>transaction</a> using either the <a>steps to a asynchronously execute a request</a> or
   1.301 +            the <a>steps to a synchronously execute a request</a>.
   1.302 +        </section>
   1.303 +
   1.304          <section class="section" id="range-concept">
   1.305            <h4>Key Range</h4>
   1.306            <p>
   1.307 @@ -622,80 +852,6 @@
   1.308            </p>
   1.309          </section> <!-- IDBCursor -->
   1.310  
   1.311 -        <section id="transaction-concept" class="section">
   1.312 -          <h4>Transaction</h4>
   1.313 -          <p>
   1.314 -            A <dfn>transaction</dfn> is defined on a <a>database</a>. A 
   1.315 -            <a>transaction</a>'s <a>scope</a> is either 
   1.316 -            <dfn>static</dfn> or <dfn>dynamic</dfn> and it MAY include a subset of the <a>object store</a>s of the <a>transaction</a>'s 
   1.317 -            <a>database</a>. If the <a>scope</a> is <a>static</a>, then it MAY 
   1.318 -            be <dfn>global</dfn>, meaning that it includes every existing and 
   1.319 -            to be created <a>object store</a>s of the <a>database</a>. There MAY 
   1.320 -            be multiple <a title="transaction">transactions</a> active in a <a>database</a>
   1.321 -            as long as their <a title="scope">scopes</a> do not overlap or the overlapping
   1.322 -            objects are locked in <a title="mode">modes</a> that are not mutually exclusive.
   1.323 -          </p>
   1.324 -          <p class="XXX">TODO: decide what happens when dynamic transactions need to lock a database
   1.325 -            object that is already exclusively locked by another transaction.
   1.326 -          </p>
   1.327 -          <p>
   1.328 -            Concurrent access to the <a title="object store">object stores</a> in a <a>transaction</a>
   1.329 -            MAY be isolated in one of three <dfn title="mode">modes</dfn>. These are:</p>
   1.330 -            <ol>
   1.331 -              <li><code>READ_ONLY</code></li>
   1.332 -              <li><code>READ_WRITE</code></li>
   1.333 -              <li><code>VERSION_CHANGE</code></li>
   1.334 -            </ol>
   1.335 -          <p>
   1.336 -          	Any number of <a title="reader">readers</a> may concurrently access all <a title="object store">object stores</a>.
   1.337 -          	A <a>writer</a> MUST behave as if there were no 
   1.338 -          	<a title="reader">readers</a> concurrently accessing the <a>object store</a>, such that 
   1.339 -          	a <a>writer</a> either cannot access the <a>object store</a> while <a title="reader">readers</a>
   1.340 -          	are accessing the <a>object store</a> or their changes are not 
   1.341 -          	visible to <a title="reader">readers</a> that were active at the time the <a>writer</a> started. 
   1.342 -          </p>
   1.343 -          <p>
   1.344 -          	User agents need to ensure a reasonable level of fairness across <a title="reader">readers</a>
   1.345 -          	and <a title="writer">writers</a> to prevent starvation.
   1.346 -          </p>
   1.347 -          <p>
   1.348 -            <a title="transaction">Transactions</a> offer some protection from 
   1.349 -            application and system failures. A <a>transaction</a> MAY be used to
   1.350 -            store multiple data records or to conditionally modify certain data 
   1.351 -            records. A <a>transaction</a> represents an atomic and durable set 
   1.352 -            of data access and mutation operations. 
   1.353 -          </p>
   1.354 -          <p>  
   1.355 -            <a title="transaction">Transactions</a> are expected to be short
   1.356 -            lived. A <a>transaction</a> may be programmatically aborted. 
   1.357 -            Conforming user agents MUST automatically:
   1.358 -          </p>
   1.359 -          <ul>
   1.360 -            <li>
   1.361 -            commit a <a>transaction</a> at the end of the scope in
   1.362 -            which it was created unless there is an active operation being 
   1.363 -            performed using that transaction, in which case, the transaction is 
   1.364 -            automatically committed when that operation is completed. 
   1.365 -            </li>
   1.366 -            <li>
   1.367 -            abort a <a>transaction</a> at the end of the scope in which it was 
   1.368 -            created, if an exception is propagated to that scope.
   1.369 -            </li>
   1.370 -          </ul>
   1.371 -          <p>
   1.372 -            Static <a>transaction</a> objects implement the 
   1.373 -            <a><code>IDBTransaction</code></a> or the
   1.374 -            <a><code>IDBTransactionSync</code></a> interfaces.
   1.375 -          </p>
   1.376 -          <p>
   1.377 -             Dynamic <a>transaction</a> objects implement the 
   1.378 -            <a><code>IDBDynamicTransaction</code></a> or the
   1.379 -            <a><code>IDBDynamicTransactionSync</code></a> interfaces.
   1.380 -          </p>
   1.381 -          <div class="issue">
   1.382 -            <p>Define dynamic transactions if we agree they should be part of this specification.</p>
   1.383 -          </div>
   1.384 -        </section> <!-- IDBTransaction -->
   1.385          <section class="section">
   1.386            <h3>The <code>IDBDatabaseException</code> Interface</h3>
   1.387            <dl class="idl" title="exception IDBDatabaseException">
   1.388 @@ -719,7 +875,13 @@
   1.389              <dd>Data provided to an operation does not meet requirements.</dd>
   1.390              <dt>const unsigned short NOT_ALLOWED_ERR = 5</dt>
   1.391              <dd>A mutation operation was attempted on a database that
   1.392 -            did not allow mutations.</dd>
   1.393 +            <dt>const unsigned short TRANSACTION_INACTIVE_ERR = 6</dt>
   1.394 +            <dd>A <a>request</a> was placed against a transaction which is
   1.395 +            currently not <a>active</a>, or which is
   1.396 +            <a title="transaction finish">finished</a>.</dd>
   1.397 +            <dt>const unsigned short ABORT_ERR = 7</dt>
   1.398 +            <dd>A <a>request</a> was aborted, for example through a call
   1.399 +            to <a href="#widl-IDBTransaction-abort"><code>IDBTransaction.abort</code></a>.</dd>
   1.400              <dt>const unsigned short SERIAL_ERR = 11</dt>
   1.401              <dd>The operation failed because of the size of the data set 
   1.402              being returned or because there was a problem in serializing or 
   1.403 @@ -839,9 +1001,9 @@
   1.404              <dd>This state indicates that a result to a previous request is available in
   1.405              the <a class="idlType" href="#widl-IDBRequest-result"><code>result</code></a> attribute.</dd>
   1.406              <dt>readonly attribute unsigned short readyState</dt>
   1.407 -            <dd>Every request starts in the 
   1.408 -            <a class="idlType" href="#widl-IDBRequest-LOADING"><code>LOADING</code></a> state.
   1.409 -            When either the request completes or fails, the state changes to 
   1.410 +            <dd>When the <a title="request done">done</a> flag is false, returns
   1.411 +            <a class="idlType" href="#widl-IDBRequest-LOADING"><code>LOADING</code></a>,
   1.412 +            otherwise returns
   1.413              <a class="idlType" href="#widl-IDBRequest-DONE"><code>DONE</code></a>.</dd>
   1.414              <dt>attribute Function onsuccess</dt>
   1.415              <dd>The event handler for the <a title="event-success">success event</a></dd>
   1.416 @@ -871,7 +1033,15 @@
   1.417              <code>error</code>, with no namespace, which does not bubble, is 
   1.418              not cancelable at each <a class="externalDFN"><code>Window</code></a> object.
   1.419            </p>
   1.420 -           
   1.421 +          <p>
   1.422 +            The <a href="#widl-IDBDatabase-setVersion">setVersion</a> function on <a>IDBDatabase</a>
   1.423 +            uses a separate interface for its <a>request</a>s in order to make use of the
   1.424 +            <code>blocked event</a> eaiser.
   1.425 +          </p>
   1.426 +          <dl class="idl" title="interface IDBVersionChangeRequest : IDBRequest"> 
   1.427 +            <dt>attribute Function onblocked</dt>
   1.428 +            <dd>The event handler for the <code>blocked event</code></dd>
   1.429 +          </dl>
   1.430            <p>
   1.431              The <span>task source</span> for these tasks is the 
   1.432              <dfn id="database-access-task-source">database access task source</dfn>.
   1.433 @@ -963,54 +1133,36 @@
   1.434              <dt>IDBRequest open()</dt>
   1.435              <dd>
   1.436                <p>
   1.437 -                This method returns immediately and runs the
   1.438 -                following steps in a different thread.
   1.439 -                If an error occurs while the <a>database</a> <a>connection</a> 
   1.440 -                is being opened, then an
   1.441 -                <a title="event-error">error event</a> is fired on this method's
   1.442 -                returned object with its 
   1.443 -                <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set
   1.444 -                to <a class="idlType" href="#widl-IDBDatabaseException-UNKNOWN_ERR"><code>UNKNOWN_ERR</code></a>
   1.445 -                and a suitable 
   1.446 -                <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>.
   1.447 +                When invoked, this method creates an <a>IDBRequest</a> and returns it.
   1.448 +                It then asynchronously runs the <a>steps for opening a database</a>.
   1.449 +                Let <var>origin</var> be the origin of the <a>IDBEnvironment</a> used to access
   1.450 +                this <a>IDBFactory</a>, <var>name</var> be the <var>name</var> argument passed
   1.451 +                to the function and <var>request</var> be the created <a>IDBRequest</a>.
   1.452                </p>
   1.453 -    
   1.454 -              <ol>
   1.455 -                <li>
   1.456 -                  Let <var>origin</var> be the origin of the active document 
   1.457 -                  from which the method was invoked.                
   1.458 -                </li>
   1.459 -                <li>
   1.460 -                  Perform the <a>steps for opening a database</a>, with 
   1.461 -                  <var>origin</var>, the <var>name</var> parameter and 
   1.462 -                  <var>description</var> parameter, and call its result as 
   1.463 -                  <var>result</var>.
   1.464 -                </li>
   1.465 -                <li>
   1.466 -                  If the steps were aborted with an error code, then set this 
   1.467 -                  request's <a class="idlType" href="#widl-IDBRequest-error"><code>error</code></a> with that 
   1.468 -                  code and abort these steps.
   1.469 -                </li>
   1.470 -                <li>
   1.471 -                  Create a <a><code>IDBDatabase</code></a> object for <var>result</var>
   1.472 -                  and call it <var>db</var>.
   1.473 -                </li>
   1.474 -                <li>
   1.475 -                  Fire a <a title="event-success">success event</a> on this 
   1.476 -                  method's returned object using the <a><code>IDBSuccessEvent</code></a> interface with its 
   1.477 -                  <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> 
   1.478 -                  set to <var>db</var>.
   1.479 -              </ol>              
   1.480 +              <p>
   1.481 +                The <var>description</var> argument is intentionally ignored. The implementation MAY
   1.482 +                use it to improve UI if so desired.
   1.483 +              </p>
   1.484 +              <p>
   1.485 +                If an error is returned from the steps above, then the implementation MUST
   1.486 +                fire an <a title="event-error">error event</a> on the <a>IDBRequest</a> returned from
   1.487 +                this method, with its 
   1.488 +                <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a>
   1.489 +                and <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a> set to
   1.490 +                appropriate values for the error.
   1.491 +              </p>
   1.492 +              <p>
   1.493 +                If the steps above are successful, the implementation MUST fire a <a title="event-success">success event</a>
   1.494 +                on the <a>IDBRequest</a> returned above. The event MUST use the <a><code>IDBSuccessEvent</code></a> interface with its 
   1.495 +                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> 
   1.496 +                set to the <var>result</var> returned from the steps.
   1.497 +              </p>
   1.498                <dl class="parameters">
   1.499                  <dt>DOMString name</dt>
   1.500                  <dd>The <a title="database name">name</a> for the <a>database</a></dd>
   1.501                  <dt>optional DOMString description</dt>
   1.502                  <dd>The description for the <a>database</a></dd>
   1.503                </dl>
   1.504 -              <dl class="exception" title="IDBDatabaseException">
   1.505 -                <dt>NON_TRANSIENT_ERR</dt>
   1.506 -                <dd>if the <var>name</var> parameter is not <a>valid</a></dd>
   1.507 -              </dl>
   1.508              </dd>
   1.509            </dl>
   1.510          </section>
   1.511 @@ -1098,31 +1250,34 @@
   1.512                  case-sensitive manner, in the  <a title="connection">connected</a> <a>database</a>.</dd>
   1.513                </dl>
   1.514              </dd>
   1.515 -            <dt>IDBRequest setVersion()</dt>
   1.516 +            <dt>IDBVersionChangeRequest setVersion()</dt>
   1.517              <dd>
   1.518 -              This method returns immediately and sets the <a>version</a> of the 
   1.519 -              <a title="connection">connected</a> <a>database</a> by following the
   1.520 -              <a>steps for running a <code>VERSION_CHANGE</code> transaction</a>. 
   1.521 +              This method updates the <a>version</a> of the <a>database</a> by following the
   1.522 +              <a>steps for running a <code>VERSION_CHANGE</code> transaction</a> using
   1.523 +              the <var>version</var> argument as <var>version</var> and the <a>IDBDatabase</a>
   1.524 +              this function was called on as <var>connection</var>. Return the <a>IDBVersionChangeRequest</a>
   1.525 +              returned by those steps.
   1.526                <dl class="parameters">
   1.527                  <dt>[TreatNullAs=EmptyString] DOMString      version</dt>
   1.528                  <dd>The <a>version</a> to store in the <a>database</a></dd>
   1.529                </dl>
   1.530              </dd>
   1.531              <dt>IDBTransaction transaction()</dt>
   1.532 -            <dd> This method returns an <a><code>IDBTransaction</code></a> object immediately and 
   1.533 -              performs the <a title="create a static transaction">steps for creating a transaction</a> with either the list of 
   1.534 -              <a>object store</a> <a title="object store name">names</a>
   1.535 -              for acquiring locks required in this <a>transaction</a> or the 
   1.536 -              global flag set to true, and an optional timeout duration. The global flag is set only if 
   1.537 -              the list is either empty, not passed or passed as  <code>null</code>. If reserving all the 
   1.538 -              <a>object store</a>s identified in the requested <a>scope</a>
   1.539 -              takes longer than the specified timeout interval, then an
   1.540 -              <a title="event-timeout">timeout event</a> is fired on this method's
   1.541 -              returned object with its 
   1.542 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   1.543 -              <a class="idlType" href="#widl-IDBDatabaseException-TIMEOUT_ERR"><code>TIMEOUT_ERR</code></a>
   1.544 -              and a suitable 
   1.545 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>.
   1.546 +            <dd>
   1.547 +              <p>
   1.548 +                This method, when called MUST execute the
   1.549 +                <a title="create a static transaction">steps for creating a transaction</a> in a asychronous
   1.550 +                fashion. If the <var>storeNames</var> argument is provided and non-empty then then use that
   1.551 +                list as the <var>names</var> argument. Otherwise use the full set of <a>object store</a>
   1.552 +                names for the <a>IDBDatabase</a> as <var>names</var> argument. The <var>mode<var> and
   1.553 +                <var>timeout</var> arguments are forwarded to the algorithm as-is. The <var>connection</var>
   1.554 +                argument is set to the <a>IDBDatabase</a> that the <code>transaction()</code> method was
   1.555 +                called on.
   1.556 +              </p>
   1.557 +              <p>
   1.558 +                The method returns a <a>IDBTransaction</a> object representing the <a>transaction</a>
   1.559 +                returned by the steps above</a>.
   1.560 +              </p>
   1.561                <dl class="parameters">
   1.562                  <dt>optional DOMStringList storeNames</dt>
   1.563                  <dd>The names of <a title="object store">object stores</a> and 
   1.564 @@ -1139,11 +1294,10 @@
   1.565                  is user agent specific</dd>
   1.566                </dl>
   1.567                <dl class="exception" title="IDBDatabaseException">
   1.568 -                <dt>TIMEOUT_ERR</dt>
   1.569 -                <dd>The required locks could not be acquired in the given timeout interval</dd>
   1.570                  <dt>NOT_ALLOWED_ERR</dt>
   1.571 -                <dd>The <code>close()</code> method has been called on this IDBDatabase instance and
   1.572 -                its internal <code>closePending</code> flag is set.</dd>
   1.573 +                <dd>The close() method has been called on this <a>IDBDatabase</a> instance.</dd>
   1.574 +                <dt>NOT_FOUND_ERR</dt>
   1.575 +                <dd>One of the names provided in the <var>storeNames</var> argument doesn't exist in this <a>database</a>.</dd>
   1.576                </dl>
   1.577              </dd>
   1.578              <dt>void close()</dt>
   1.579 @@ -1377,10 +1531,13 @@
   1.580              </dd>
   1.581              <dt>IDBIndex index()</dt>
   1.582              <dd>
   1.583 -              <p>
   1.584 -                This method returns immediately and opens the <a>index</a> with the
   1.585 -                given name in the <a title="connection">connected</a> <a>database</a>.
   1.586 -              </p>              
   1.587 +              Returns a <a>IDBIndex</a> representing a <a>index</a> that is part of the
   1.588 +              to this <a>object store</a>. Every call to this function on the same
   1.589 +              <a>IDBObjectStore</a> instance and with the same <var>name</var> returns the same <a>IDBIndex</a> instance.
   1.590 +              However the retured <a>IDBIndex</a> instance is specific to this <a>IDBObjectStore</a> instance. If this
   1.591 +              function is called on a different <a>IDBObjectStore</a> instance, a different <a>IDBIndex</a> instance is
   1.592 +              returned. A result of this is that different <a>IDBTransaction</a>s use different <a>IDBIndex</a> instances
   1.593 +              to represent the same <a>index</a>.
   1.594                <dl class="parameters">
   1.595                  <dt>DOMString name</dt>
   1.596                  <dd>The <a title="index name">name</a> of an existing <a>index</a></dd>
   1.597 @@ -1685,8 +1842,11 @@
   1.598              </dd>
   1.599              <dt>IDBObjectStore objectStore()</dt>
   1.600              <dd>
   1.601 -              Immediately returns the object store that has been already added 
   1.602 -              to the <a>scope</a> of this <a>transaction</a>. 
   1.603 +              Returns a <a>IDBObjectStore</a> representing a <a>object store</a> that is part of the
   1.604 +              to the <a>scope</a> of this <a>transaction</a>. Every call to this function on the same
   1.605 +              <a>IDBTransaction</a> instance and with the same <var>name</var> returns the same <a>IDBObjectStore</a> instance.
   1.606 +              However the retured <a>IDBObjectStore</a> instance is specific to this <a>IDBTransaction</a>. If this
   1.607 +              function is called on a different <a>IDBTransaction</a>, a different <a>IDBObjectStore</a> instance is returned.
   1.608                <dl class="parameters">
   1.609                  <dt>DOMString name</dt>
   1.610                  <dd>The requested <a>object store</a></dd>
   1.611 @@ -1701,15 +1861,13 @@
   1.612              </dd>
   1.613              <dt>void abort()</dt>
   1.614              <dd>
   1.615 -              This method returns immediately and undoes all the changes performed to 
   1.616 -              the <a>objects</a> of this <a>database</a> in this <a>transaction</a>. If this <a>transaction</a> 
   1.617 -              has already been committed or aborted,  then an
   1.618 -              <a title="event-error">error event</a> is fired on this method's
   1.619 -              returned object with its 
   1.620 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   1.621 -              <a class="idlType" href="#widl-IDBDatabaseException-NON_TRANSIENT_ERR"><code>NON_TRANSIENT_ERR</code></a>
   1.622 -              and a suitable 
   1.623 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>.
   1.624 +              If this <a>transaction</a> is <a title="transaction finish">finished</a>, throw a NOT_ALLOWED_ERR
   1.625 +              exception. Otherwise this method <a title="transaction abort">aborts</a> the transaction by running the
   1.626 +              <a>steps to abort a transaction</a> with <var>code</var> set to ABORT_ERR.
   1.627 +              <dl class="exception" title="IDBDatabaseException">
   1.628 +                <dt>NOT_ALLOWED_ERR</dt>
   1.629 +                <dd>If this <a>transaction</a> has already been committed or aborted.</dd>
   1.630 +              </dl>
   1.631              </dd>
   1.632              <dt>attribute Function onabort</dt>
   1.633              <dd>The event handler for the <a>onabort</a> event.</dd>
   1.634 @@ -1780,48 +1938,33 @@
   1.635            <dl class="idl" title="interface IDBFactorySync">
   1.636              <dt>IDBDatabaseSync open()</dt>
   1.637              <dd>
   1.638 +              <p>
   1.639 +                When invoked, this method synchronously runs the <a>steps for opening a database</a>.
   1.640 +                Let <var>origin</var> be the origin of the <a>IDBEnvironmentSync</a> used to access
   1.641 +                this <a>IDBFactorySync</a>, <var>name</var> be the <var>name</var> argument passed
   1.642 +                to the function and <var>request</var> be the created <a>IDBRequest</a>.
   1.643 +              </p>
   1.644 +              <p>
   1.645 +                The <var>description</var> argument is intentionally ignored. The implementation MAY
   1.646 +                use it to improve UI if so desired.
   1.647 +              </p>
   1.648 +              <p>
   1.649 +                If an error is returned from the steps above, then the implementation MUST
   1.650 +                throw an <a><code>IDBDatabaseException</code></a> with its 
   1.651 +                <a class="idlType" href="#widl-IDBDatabaseException-code"><code>code</code></a>
   1.652 +                and <a class="idlType" href="#widl-IDBDatabaseException-message"><code>message</code></a> set to
   1.653 +                appropriate values for the error.
   1.654 +              </p>
   1.655 +              <p>
   1.656 +                If the steps above are successful, the implementation MUST create a IDBDatabaseSync
   1.657 +                object representing the created <a>connection</a> and return it.
   1.658 +              </p>
   1.659                <dl class="parameters">
   1.660                  <dt>DOMString name</dt>
   1.661                  <dd>The <a title="database name">name</a> for the <a>database</a></dd>
   1.662 -                <dt>DOMString description</dt>
   1.663 +                <dt>optional DOMString description</dt>
   1.664                  <dd>The description for the <a>database</a></dd>
   1.665                </dl>
   1.666 -              <dl class="exception" title="IDBDatabaseException">
   1.667 -                <dt>UNKNOWN_ERR</dt>
   1.668 -                <dd>if an error occurs while the <a>database</a> <a>connection</a> 
   1.669 -                is being opened</dd>
   1.670 -                <dt>NON_TRANSIENT_ERR</dt>
   1.671 -                <dd>if the <var>name</var> parameter is not <a>valid</a></dd>
   1.672 -              </dl>
   1.673 -              <p>
   1.674 -                The synchronous API for databases blocks the calling thread until a
   1.675 -                <a><code>IDBDatabaseSync</code></a> object is ready to return.
   1.676 -                When this method is invoked, the user agent MUST run the
   1.677 -                following steps:
   1.678 -              </p>
   1.679 -    
   1.680 -              <ol>
   1.681 -                <li>
   1.682 -                  Let <var>origin</var> be the origin of the scripts in the worker.
   1.683 -                </li>
   1.684 -                <li>
   1.685 -                  Perform the <a>steps for opening a database</a>, with <var>origin</var>,
   1.686 -                  the <var>name</var> parameter and <var>description</var> parameter, and 
   1.687 -                  call its result as <var>result</var>.
   1.688 -                </li>
   1.689 -                <li>
   1.690 -                  If the steps were aborted with an error code, then throw a newly constructed
   1.691 -                  <a><code>IDBDatabaseException</code></a> 
   1.692 -                  exception with the code of that error and abort these steps.
   1.693 -                </li>
   1.694 -                <li>
   1.695 -                  Create a <a><code>IDBDatabaseSync</code></a> object using <var>result</var>
   1.696 -                  and call it <var>db</var>.
   1.697 -                </li>
   1.698 -                <li>
   1.699 -                  Return <var>db</var>.
   1.700 -                </li>
   1.701 -              </ol>              
   1.702              </dd>
   1.703            </dl>
   1.704          </section>
   1.705 @@ -1959,10 +2102,20 @@
   1.706              </dd>
   1.707              <dt>IDBTransactionSync transaction()</dt>
   1.708              <dd>
   1.709 -              Perform the <a>steps for creating a transaction</a> with the list of 
   1.710 -              database objects in the scope of this transaction and a timeout 
   1.711 -              duration in milliseconds, and return
   1.712 -              the resulting <a><code>IDBTransactionSync</code></a> object.
   1.713 +              <p>
   1.714 +                This method, when called MUST execute the
   1.715 +                <a title="create a static transaction">steps for creating a transaction</a> in a asychronous
   1.716 +                fashion. If the <var>storeNames</var> argument is provided and non-empty then then use that
   1.717 +                list as the <var>names</var> argument. Otherwise use the full set of <a>object store</a>
   1.718 +                names for the <a>IDBDatabase</a> as <var>names</var> argument. The <var>mode<var> and
   1.719 +                <var>timeout</var> arguments are forwarded to the algorithm as-is. The <var>connection</var>
   1.720 +                argument is set to the <a>IDBDatabase</a> that the <code>transaction()</code> method was
   1.721 +                called on.
   1.722 +              </p>
   1.723 +              <p>
   1.724 +                The method returns a <a>IDBTransactionSync</a> object representing the <a>transaction</a>
   1.725 +                returned by the steps above</a>.
   1.726 +              </p>
   1.727                <dl class="parameters">
   1.728                  <dt>optional DOMStringList storeNames</dt>
   1.729                  <dd>The names of <a title="object store">object stores</a> and 
   1.730 @@ -1977,10 +2130,12 @@
   1.731                <dl class="exception" title="IDBDatabaseException">
   1.732                  <dt><a class="idlType" href="#widl-IDBDatabaseException-TIMEOUT_ERR"><code>TIMEOUT_ERR</code></a></dt>
   1.733                  <dd>
   1.734 -                If reserving all the <a>database</a> objects identified in the new
   1.735 -                <a title="transaction">transaction's</a> <a>scope</a> takes longer 
   1.736 -                than the specified interval.
   1.737 +                If <a title="transaction start">starting</a> the transaction takes longer than the specified timeout.
   1.738                  </dd>
   1.739 +                <dt>NOT_ALLOWED_ERR</dt>
   1.740 +                <dd>The close() method has been called on this <a>IDBDatabase</a> instance.</dd>
   1.741 +                <dt>NOT_FOUND_ERR</dt>
   1.742 +                <dd>One of the names provided in the <var>storeNames</var> argument doesn't exist in this <a>database</a>.</dd>
   1.743                </dl>
   1.744              </dd>
   1.745            </dl>  
   1.746 @@ -2163,13 +2318,15 @@
   1.747                  <dd>The <a>unique</a> flag for the new <a>index</a>. The default
   1.748                  value of this parameter is false.</dd>
   1.749                </dl>
   1.750 -            <dt>IDBIndexSync openIndex()</dt>
   1.751 +            <dt>IDBIndexSync index()</dt>
   1.752              <dd>
   1.753 -              <p>
   1.754 -                This method opens the <a>index</a> with the given name
   1.755 -                in the <a title="connection">connected</a> <a>database</a> for the
   1.756 -                <a>mode</a> specified.
   1.757 -              </p>              
   1.758 +              Returns a <a>IDBIndexSync</a> representing a <a>index</a> that is part of the
   1.759 +              to this <a>object store</a>. Every call to this function on the same
   1.760 +              <a>IDBObjectStoreSync</a> instance and with the same <var>name</var> returns the same <a>IDBIndexSync</a> instance.
   1.761 +              However the retured <a>IDBIndexSync</a> instance is specific to this <a>IDBObjectStoreSync</a> instance. If this
   1.762 +              function is called on a different <a>IDBObjectStoreSync</a> instance, a different <a>IDBIndexSync</a> instance is
   1.763 +              returned. A result of this is that different <a>IDBTransactionSync</a>s use different <a>IDBIndexSync</a> instances
   1.764 +              to represent the same <a>index</a>.
   1.765                <dl class="parameters">
   1.766                  <dt>DOMString name</dt>
   1.767                  <dd>The <a title="index name">name</a> of an existing <a>index</a></dd>
   1.768 @@ -2541,8 +2698,11 @@
   1.769                is a part</dd>
   1.770              <dt>IDBObjectStoreSync objectStore()</dt>
   1.771              <dd>
   1.772 -              Immediately returns the object store that has been already added 
   1.773 -              to the <a>scope</a> of this <a>transaction</a>. 
   1.774 +              Returns a <a>IDBObjectStoreSync</a> representing a <a>object store</a> that is part of the
   1.775 +              to the <a>scope</a> of this <a>transaction</a>. Every call to this function on the same
   1.776 +              <a>IDBTransactionSync</a> instance and with the same <var>name</var> returns the same <a>IDBObjectStoreSync</a> instance.
   1.777 +              However the retured <a>IDBObjectStoreSync</a> instance is specific to this <a>IDBTransactionSync</a>. If this
   1.778 +              function is called on a different <a>IDBTransactionSync</a>, a different <a>IDBObjectStoreSync</a> instance is returned.
   1.779                <dl class="parameters">
   1.780                  <dt>DOMString name</dt>
   1.781                  <dd>The requested <a>object store</a></dd>
   1.782 @@ -2557,13 +2717,11 @@
   1.783              </dd>
   1.784              <dt>void abort()</dt>
   1.785              <dd>
   1.786 -              This method signals the need to cancel the effects of
   1.787 -              operations performed in this <a>transaction</a>. To perform
   1.788 -              this method, the user agent ignores all the changes performed to the
   1.789 -              <a>objects</a> of this <a>database</a> since the creation of this 
   1.790 -              <a>transaction</a>.
   1.791 +              If this <a>transaction</a> is <a title="transaction finish">finished</a>, throw a NOT_ALLOWED_ERR
   1.792 +              exception. Otherwise this method <a title="transaction abort">aborts</a> the transaction by running the
   1.793 +              <a>steps to abort a transaction</a> with <var>code</var> set to ABORT_ERR.
   1.794                <dl class="exception" title="IDBDatabaseException">
   1.795 -                <dt>NON_TRANSIENT_ERR</dt>
   1.796 +                <dt>NOT_ALLOWED_ERR</dt>
   1.797                  <dd>If this <a>transaction</a> has already been committed or aborted.</dd>
   1.798                </dl>
   1.799              </dd>
   1.800 @@ -2603,29 +2761,37 @@
   1.801          <section class="section" id="opening">
   1.802            <h4>Opening the database</h4>
   1.803            <p>
   1.804 -            The <dfn>steps for opening a database</dfn> are as follows. These 
   1.805 -            steps MUST be run with an origin, a database name and an optional
   1.806 -            description. All the steps MUST be run atomically:
   1.807 +            The <dfn>steps for opening a database</dfn> are as follows. The algorithm in these steps
   1.808 +            take three arguments. A <var>origin</var> which requested the <a>database</a> to be opened,
   1.809 +            a database <var>name</var>. It also optionally takes a <var>request</var> which represents
   1.810 +            a <a>request</a> used when opening the database is done using an asynchronous API.
   1.811            </p>
   1.812            
   1.813            <ol>
   1.814              <li>
   1.815 -              If there is already a database with the given name from the origin
   1.816 -              <var>origin</var>, then let <var>db</var> be that database. If a description is passed to these steps, set the description of <var>db</var> to that.
   1.817 +              If these steps fail for any reason, return a error with the appropriate code and abort
   1.818 +              this algorithm.
   1.819              </li>
   1.820 -            
   1.821 +            <li>
   1.822 +              If there is already a database with the given name from the origin <var>origin</var>, then
   1.823 +              let <var>db</var> be that database.
   1.824 +            </li>
   1.825              <li>
   1.826                If no database with the given name from the origin <var>origin</var>
   1.827 -              exists, then create the database <var>db</var> with the name and
   1.828 -              description passed to these steps.
   1.829 +              exists, then create the database <var>db</var> with name <var>name</var>.
   1.830              </li>
   1.831 -  
   1.832              <li>
   1.833 -              Create a <a>connection</a> to <var>db</var> and call it <var>result</var>.
   1.834 +              Wait until no already existing <a>connection</a>s to <var>db</var>, have
   1.835 +              non-<a title="transaction finish">finished</a> VERSION_CHANGE <a>transaction</a>s.
   1.836 +              <p class="note">
   1.837 +                There can potentially be several <a>connection</a>s waiting for a VERSION_CHANGE transaction
   1.838 +                to finish. Once that transaction <a title="transaction finish">finishes</a> another <a>connection</a>
   1.839 +                could be created and a new VERSION_CHANGE transaction could be started before these steps has
   1.840 +                a chance to continue. In that case the implementation MUST keep waiting at this step.
   1.841 +              </p>
   1.842              </li>
   1.843 -            
   1.844              <li>
   1.845 -              Return <var>result</var>.
   1.846 +              Create a <a>connection</a> to <var>db</var> and return it.
   1.847              </li>
   1.848            </ol>        
   1.849          </section>
   1.850 @@ -2834,55 +3000,43 @@
   1.851            <h4>Transaction Creation steps</h4>
   1.852            <p>
   1.853              When the user agent is to <dfn>create a static <a>transaction</a></dfn>
   1.854 -            it MUST run the following steps. These steps MUST be run with 
   1.855 -            two parameters - <a>database</a>, an optional global flag, and an 
   1.856 -            optional list of names of <a>database</a> <a>objects</a> to be 
   1.857 -            reserved.
   1.858 +            it MUST run the following steps. This algorithm takes four parameters:
   1.859 +            A <a><var>connection</var></a>, a <a><var>mode</var></a>, a list of <var>names</var> of
   1.860 +            <a>object store</a>s to be included in the <a>scope</a> of the transaction, and a
   1.861 +            <var>timeout</var> for the transaction <a title="transaction start">starting</a>.
   1.862            </p>
   1.863            
   1.864            <ol>
   1.865              <li>
   1.866 -              Pick the appropriate steps:
   1.867 -              <dl class="switch">
   1.868 -                <dt>If these steps are called with the global flag set</dt>
   1.869 -                <dd>Acquire a lock on the entire database.</dd>
   1.870 -                <dt>If these steps are called with a non-empty list of <a>object store</a> <a title="object store name">name</a>s</dt>
   1.871 -                <dd>
   1.872 -                    Acquire appropriate locks on each of the named 
   1.873 -                    <a>object store</a> in an ordered sequence. 
   1.874 -                    <div class="note">
   1.875 -                      A user agent MAY obtain a shared or exclusive lock on 
   1.876 -                      the database if it does not perform fine grained locking.
   1.877 -                    </div>
   1.878 -                </dd>
   1.879 -              </dl>
   1.880 -            </li>
   1.881 -
   1.882 -            <li>
   1.883 -              If a timeout duration is passed to these steps and is exceeded 
   1.884 -              when acquiring locks, then set <var>code</var> to 
   1.885 -              <a class="idlType" href="#widl-IDBDatabaseException-TIMEOUT_ERR"><code>TIMEOUT_ERR</code></a> and jump to the last step.
   1.886 -            </li>
   1.887 -
   1.888 -            <li>
   1.889 -              Open a new transaction to the database, and create a
   1.890 -              <a><code>IDBTransaction</code></a> object
   1.891 -              that represents that transaction. Let <var>transaction</var> be 
   1.892 -              this object.
   1.893 -            </li>
   1.894 -            
   1.895 -            <li>
   1.896 -              Set the current transaction of this <a><code>IDBDatabase</code></a> object
   1.897 -              to <var>transaction</var>.
   1.898 +              If any of the strings in <var>names</var> identifies an <a>object store</a> which doesn't
   1.899 +              exist, throw a NOT_FOUND_ERR exception. If the <a>closePending</a>
   1.900 +              flag is set on <var>connection</var> the throw a NOT_ALLOWED_ERR.
   1.901              </li>
   1.902              <li>
   1.903 -              Return <var>transaction</var>. End these steps.
   1.904 +              <a title="transaction create">Create</a> a <a>transaction</a> using <var>connection</var> as
   1.905 +              <a>connection</a>, <var>mode</var> as <a>mode</a>, and the <a>object store</a>s identified in
   1.906 +              <var>names</var> as <a>scope</a>.
   1.907              </li>
   1.908              <li>
   1.909 -              This step is only performed in case of error. If this step is performed
   1.910 -              synchronously, then raise a newly constructed 
   1.911 -              <a><code>IDBDatabaseException</code></a> 
   1.912 -              exception <var>exception</var> with the code <var>code</var>.
   1.913 +              If these steps are running asynchronously, return the created <a>transaction</a> and run the
   1.914 +              remaining steps asynchronously. When control is returned to the event loop, the implementation
   1.915 +              MUST set the <a>active</a> flag to false.
   1.916 +            </li>
   1.917 +            <li>
   1.918 +              Wait until the <a>transaction</a> can be <a title="transaction start">started</a> according to the
   1.919 +              <a>transaction lifetime</a> rules. If this takes longer than the specified <var>timeout</var> then:
   1.920 +              <ul>
   1.921 +                <li>
   1.922 +                  If these steps are run asynchronously, run the <a>steps for aborting a transaction</a> using
   1.923 +                  TIMEOUT_ERR as <var>code</var>.
   1.924 +                </li>
   1.925 +                <li>
   1.926 +                  If steps are run synchronously, throw a TIMEOUT_ERR exception.
   1.927 +                </li>
   1.928 +              </ul>
   1.929 +            </li>
   1.930 +            <li>
   1.931 +              If these steps are running synchronously, return the created <a>transaction</a>.
   1.932              </li>
   1.933            </ol>
   1.934            <div class="issue">
   1.935 @@ -2890,31 +3044,144 @@
   1.936            </div>     
   1.937          </section>
   1.938          <section class="section">
   1.939 +          <h4>Steps for aborting a transaction</h4>
   1.940 +          <p>
   1.941 +            When taking the <dfn>steps for aborting a <a>transaction</a></dfn> the implementation MUST
   1.942 +            execute the following algorithm. This algorithm takes two parameter, the <var>transaction</var> to abort
   1.943 +            and a <var>code</var>.
   1.944 +          </p>
   1.945 +          <ol>
   1.946 +            <li>
   1.947 +              All the changes made to the <a>database</a> the transaction uses are reverted. For VERSION_CHANGE
   1.948 +              transactions this includes changes to the set of <a>object store</a>s and <a>index</a>es, as well
   1.949 +              as the change to the <a>version</a>.
   1.950 +            </li>
   1.951 +            <li>
   1.952 +              If the transaction's <a>request list</a> contain any <a>request</a>s whose <a title="request done">done</a> flag
   1.953 +              is still false, <a>fire a error event</a> with code <var>code</code> against each such <a>request</a>
   1.954 +              and set its <a title="request done">done</a> flag to true. Also abort the <a>steps for asynchronously
   1.955 +              executing a request</a> for each such transaction.
   1.956 +            </li>
   1.957 +          </ol>
   1.958 +        </section>
   1.959 +        <section class="section">
   1.960 +          <h4>Steps for asynchronously executing a <a>request</a></h4>
   1.961 +          <p>
   1.962 +            When taking the <dfn>steps to a asynchronously execute a request</dfn> the implementation MUST run the
   1.963 +            following algorithm. The algorithm takes a <var>source</var> object and a <var>operation</var> to
   1.964 +            perform on a database.
   1.965 +          </p>
   1.966 +          <p>
   1.967 +            These steps can be aborted at any point if the <a>transaction</a> the created <a>request</a> belongs
   1.968 +            to is <a title="transaction abort">aborted</a> using the <a>steps for aborting a transaction</a>
   1.969 +          </p>
   1.970 +          <ol>
   1.971 +            <li>
   1.972 +              Set <var>transaction</var> to the <a>transaction</a> associated with <var>source</var>.
   1.973 +            </li>
   1.974 +            <li>
   1.975 +              Create a <a>IDBRequest</a> object and set <var>request</var> to this object. Set <var>request</var>'s
   1.976 +              <a title="request source">source</a> to <var>source</var> and add <var>request</var> to the end of the
   1.977 +              <a title="request list">list</a> of <a>request</a>s in <var>transaction</var>. Return
   1.978 +              this object and run the remaining steps in this algorithm asynchronously.
   1.979 +              <p class="note">
   1.980 +                Cursors override this step to reuse an existing <a>IDBRequest</a>. However they still put the
   1.981 +                <a>IDBRequest</a> at the end of the list of <a>request</a>s in <var>transaction</var>.
   1.982 +              </p>
   1.983 +            </li>
   1.984 +            <li>
   1.985 +              Wait until all previously added <a>requests<a> in <var>transaction</var> have their
   1.986 +              <a title="request done">done</a> flag set to true.
   1.987 +            </li>
   1.988 +            <li>
   1.989 +              Perform <var>operation</var>.
   1.990 +            </li>
   1.991 +            <li>
   1.992 +              If performing <var>operation</var> succeeded then set the <a title="request done">done</a> flag
   1.993 +              on the <var>request</var> to true and <a>fire a success event</a> at <var>request</var> with
   1.994 +              the result of the operation.
   1.995 +            </li>
   1.996 +            <li>
   1.997 +              If performing <var>operation</var> failed then set the <a title="request done">done</a> flag
   1.998 +              on the <var>request</var> to true and <a>fire a error event</a> at <var>request</var> with
   1.999 +              the code of the error from <var>operation</var>.
  1.1000 +            </li>
  1.1001 +          </ol>
  1.1002 +        </section>
  1.1003 +        <section class="section">
  1.1004 +          <h4>Steps for synchronously executing a <a>request</a></h4>
  1.1005 +          <p>
  1.1006 +            When taking the <dfn>steps to a synchronously execute a request</dfn> the implementation MUST run the
  1.1007 +            following algorithm. The algorithm takes a <var>transaction</var> object and a <var>operation</var> to
  1.1008 +            perform on a database.
  1.1009 +          </p>
  1.1010 +          <ol>
  1.1011 +            <li>
  1.1012 +              Perform <var>operation</var>.
  1.1013 +            </li>
  1.1014 +            <li>
  1.1015 +              If performing <var>operation</var> succeeded then set return the result of the operation.
  1.1016 +            </li>
  1.1017 +            <li>
  1.1018 +              If performing <var>operation</var> failed then throw a IDBDatabaseException with the code
  1.1019 +              of the error from <var>operation</var>.
  1.1020 +            </li>
  1.1021 +          </ol>
  1.1022 +        </section>
  1.1023 +        <section class="section">
  1.1024            <h4>VERSION_CHANGE transaction steps</h4>
  1.1025            <p>
  1.1026              The <dfn>steps for running a <code>VERSION_CHANGE</code> transaction</dfn> are
  1.1027 -            as follows. These steps MUST be run with three parameters - a <var>database</var>,
  1.1028 -            a new <var>version number</var> to be set for the <var>database</var> and a <var>request</var>
  1.1029 -            object representing the <a><code>IDBRequest</code></a> instance associated with this transaction.
  1.1030 +            as follows. This algorithm takes two parameters - a <var>connection</var> object which is used
  1.1031 +            to update the <a>database</a> and a new <var>version number</var> to be set for the <a>database</a>.
  1.1032            </p>
  1.1033            <ol>
  1.1034              <li>
  1.1035 -              Let <var>openDatabases</var> be the set of all <a><code>IDBDatabase</code></a> object representing
  1.1036 -              the given <var>database</var>.
  1.1037 +              Create a new <a>transaction</a> with <a>mode</a> set to VERSION_CHANGE and <var>connection</var> used as <a>connection</a>.
  1.1038 +              The <a>scope</a> of the transaction includes every <a>object store</a> in <var>connection</var>. Set its
  1.1039 +              <a>active</a> flag to false.
  1.1040              </li>
  1.1041              <li>
  1.1042 -              Fire a <a><code>versionchange</code></a> event targeted at each object in the <var>openDatabases</var> set.
  1.1043 -              The <code>version</code> property of this event must be set to the given <var>version number</var>.
  1.1044 +              Create a new <a>request</a> which uses the <a>IDBVersionChangeRequest</a> interface and return it.
  1.1045 +              The remaining steps in this algorithm are run asynchronously.
  1.1046              </li>
  1.1047              <li>
  1.1048 -              Wait until all objects in <var>openDatabases</var> are closed.
  1.1049 +              Let <var>openDatabases</var> be the set of all <a><code>IDBDatabase</code></a> and <a><code>IDBDatabaseSync</code></a>
  1.1050 +              objects, except <var>connection</var>, connected to the same <a>database</a> as <var>connection</var>.
  1.1051              </li>
  1.1052              <li>
  1.1053 -              Start a new <a><code>transaction</code></a> with <a><code>mode</code></a> set to <a><code>VERSION_CHANGE</code></a>.
  1.1054 -              Note that as long as this transaction is running, no other <a><code>IDBDatabase</code></a> objects can be open.
  1.1055 +              <p>
  1.1056 +                Fire a <code>versionchange</code> event at each object in <var>openDatabases</var> that is open. The event MUST NOT
  1.1057 +                be fired on objects which has the <code>closePending</code> flag set. The event MUST use the
  1.1058 +                <a><code>IDBVersionChangeEvent</code></a> interface and have the
  1.1059 +                <a href="#widl-IDBVersionChangeEvent-version"><code>version</code></a> property set to <var>version number</var>.
  1.1060 +                This event MUST NOT bubble or be cancelable.
  1.1061 +              </p>
  1.1062 +              <p class="note">
  1.1063 +                Firing this event might cause one or more of the other objects in <var>openDatabases</var> to be closed, in which case
  1.1064 +                the <code>versionchange</code> event MUST NOT be fired at those objects if that hasn't yet been done.
  1.1065 +              </p>
  1.1066              </li>
  1.1067              <li>
  1.1068 -              Set the version of the <var>database</var> to the given <var>version number</var>.
  1.1069 +              <p>
  1.1070 +                If any of the <a>connection</a>s in <var>openDatabases</var> are still not closed, fire a <code>blocked</code> event at
  1.1071 +                <var>request</var>. The event MUST use the <a><code>IDBVersionChangeEvent</code></a> interface and have the
  1.1072 +                <a href="#widl-IDBVersionChangeEvent-version"><code>version</code></a> property set to <var>version number</var>.
  1.1073 +                This event MUST NOT bubble or be cancelable.
  1.1074 +              </p>
  1.1075 +            </li>
  1.1076 +            <li>
  1.1077 +              Wait until all objects in <var>openDatabases</var> are <a title="database close">closed</a> and all of
  1.1078 +              their transactions are <a title="transaction finish">finished</a>.
  1.1079 +              <p class="issue">Should we allow <code>blocked</code> to be fired here too, if waiting takes "too long"?</p>.
  1.1080 +            </li>
  1.1081 +            <li>
  1.1082 +              Start a the <a>transaction</a> created above. Note that until this <a>transaction</a> is finished, no other <a>connection</a>s
  1.1083 +              can be opened to the same <a>database</a>.
  1.1084 +            </li>
  1.1085 +            <li>
  1.1086 +              Set the version of <var>database</var> to the given <var>version number</var>. This change is considered part of the
  1.1087 +              <a><code>transaction</code></a>, and so if the transaction is <a>abort</a>ed, this change is reverted.
  1.1088              </li>
  1.1089              <li>
  1.1090                Fire a <a><code>success</code></a> event targeted at the <var>request</var> object. The <a><code>result</code></a>
  1.1091 @@ -2922,30 +3189,84 @@
  1.1092                <a><code>VERSION_CHANGE</code></a> transaction created in step 4.
  1.1093              </li>
  1.1094              <li>
  1.1095 -              Follow the normal steps for executing a <a><code>transaction</code></a> and let the  <a><code>transaction</code></a>
  1.1096 -              complete normally.
  1.1097 +              Follow the normal steps for executing a <a><code>transaction</code></a> and let the <a><code>transaction</code></a>
  1.1098 +              finish normally.
  1.1099              </li>
  1.1100            </ol>
  1.1101          </section>
  1.1102          <section class="section">
  1.1103            <h4>Database closing steps</h4>
  1.1104 -          <p>The <dfn>steps for closing a database connection</dfn> are as follows. These steps MUST be run with one parameter
  1.1105 -            - a <var>database</var> object of type <a><code>IDBDatabase</code></a>.</p>
  1.1106 +          <p>The <dfn>steps for closing a database connection</dfn> are as follows. These steps take one argument, a <var>connection</var> object.
  1.1107            <ol>
  1.1108              <li>
  1.1109 -              Set the internal <code>closePending</code> flag of the <var>database</var> object to true. If the <code>transaction()</code> method
  1.1110 -              is called on the <var>database</var> object while the <code>closePending</code> is set, an exception will be thrown.
  1.1111 +              Set the internal <a><code>closePending</code></a> flag of <var>connection</var> to true.
  1.1112              </li>
  1.1113              <li>
  1.1114 -              Wait for all pending transactions on the <var>database</var> to complete. Once they are complete, the <var>database</var> is
  1.1115 -              fully closed.
  1.1116 +              Wait for all transactions <a title="transaction create">created</a> using <var>connection</var> to complete.
  1.1117 +              Once they are complete, <var>connection</var> is <dfn title="database close">closed</dfn>.
  1.1118 +            </li>
  1.1119 +          </ol>
  1.1120 +          <p class="note">
  1.1121 +            Once the <a><code>closePending</code></a> flag has ben set to true no new transactions can be
  1.1122 +            <a title="transaction create">created</a> using <var>connection</var>. All functions that
  1.1123 +            <a title="transaction create">create</a> transactions first check the the <a>closePending</a> flag first and
  1.1124 +            throw an exception if it is true.
  1.1125 +          </p>
  1.1126 +        </section>
  1.1127 +        <section class="section">
  1.1128 +          <h4>Fire a success event</h4>
  1.1129 +          <p>
  1.1130 +            To <dfn title="fire a success event">fire a success event with result <var>result</var></dfn> at a <a>request</a>,
  1.1131 +            the implementation MUST run the following steps:
  1.1132 +          </p>
  1.1133 +          <ol>
  1.1134 +            <li>
  1.1135 +              Set <var>transaction</var> to the <a>transaction</a> associated with the <a title="request source">source</a>.
  1.1136              </li>
  1.1137              <li>
  1.1138 -              Unblock any pending <code>setVersion()</code> calls made on other <a><code>IDBDatabase</code></a> objects connected to the same
  1.1139 -              database.
  1.1140 +              Set the <a>active</a> flag of <var>transaction</var> to true.
  1.1141 +            </li>
  1.1142 +            <li>
  1.1143 +              Dispatch a <a title="event-success">success event</a>, which does not bubble and is not
  1.1144 +              cancelable, at <a>request</a>. The event must use the <a><code>IDBSuccessEvent</code></a> interface and have its 
  1.1145 +              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to <var>result</var>. The
  1.1146 +              <a class="idlType" href="#widl-IDBEvent-source"><code>source</code></a> is set to <var>request</var>s
  1.1147 +              <a title="request source">source</a>. And <a class="idlType" href="#widl-IDBTransactionEvent-result"><code>transaction</code></a>
  1.1148 +              is set to <var>transaction</var>.
  1.1149 +            </li>
  1.1150 +            <li>
  1.1151 +              Set the <a>active</a> flag of <var>transaction</var> to false.
  1.1152              </li>
  1.1153            </ol>
  1.1154          </section>
  1.1155 +        <section class="section">
  1.1156 +          <h4>Fire an error event</h4>
  1.1157 +          <p>
  1.1158 +            To <dfn title="fire a error event">fire a error event with code <var>code</var></dfn> at a <a>request</a>,
  1.1159 +            the implementation MUST run the following steps:
  1.1160 +          </p>
  1.1161 +          <ol>
  1.1162 +            <li>
  1.1163 +              Set <var>transaction</var> to the <a>transaction</a> associated with the <a title="request source">source</a>.
  1.1164 +            </li>
  1.1165 +            <li>
  1.1166 +              Set the <a>active</a> flag of <var>transaction</var> to true.
  1.1167 +            </li>
  1.1168 +            <li>
  1.1169 +              Dispatch a <a title="event-error">error event</a> at <a>request</a>. The event must use
  1.1170 +              the <a><code>IDBErrorEvent</code></a> interface and have its 
  1.1171 +              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to <var>code</var>. The
  1.1172 +              <a class="idlType" href="#widl-IDBEvent-source"><code>source</code></a> is set to <var>request</var>s internal
  1.1173 +              <a title="request source">source</a>. The <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a> is
  1.1174 +              set to a string appropriate for <var>code</var>.
  1.1175 +            <li>
  1.1176 +              Set the <a>active</a> flag of <var>transaction</var> to false.
  1.1177 +            </li>
  1.1178 +          </ol>
  1.1179 +          <p class="issue">
  1.1180 +            TODO: need to define more error handling here.
  1.1181 +          </p>
  1.1182 +        </section>
  1.1183        </section>
  1.1184  
  1.1185    <!-- database-api -->
     2.1 --- a/Speclet_020_IDB_API_Constructs.html	Mon Oct 25 11:08:37 2010 -0700
     2.2 +++ b/Speclet_020_IDB_API_Constructs.html	Fri Oct 29 09:13:37 2010 -0700
     2.3 @@ -271,45 +271,275 @@
     2.4              Each <a>origin</a> has an associated set of 
     2.5              <a title="database">databases</a>. A <dfn>database</dfn> comprises
     2.6              one or more <a title="object store">object stores</a>.
     2.7 +          </p>
     2.8            <p>
     2.9 -            Each <a>database</a> has a <a title="valid-name">valid</a> 
    2.10 -            <dfn title="database name">name</dfn> and a human readable 
    2.11 -            description. A <dfn title="valid-name">valid name</dfn> is any 
    2.12 -            string including the empty string. An exact match of names means 
    2.13 -            that their UTF-8 encodings are identical.
    2.14 +            Every <a>database</a> has a <dfn title="database name">name</dfn> which identifies it
    2.15 +            within a specific <a>origin</a>. The name can be any string value, including the empty string, and
    2.16 +            stays constant for the lifetime of the database. Each <a>database</a> also has a current
    2.17 +            <dfn>version</dfn>.
    2.18            </p>
    2.19 -          
    2.20 -          <div class="note">
    2.21 -            If an implementation does not support all sets of strings, it may 
    2.22 -            implement support for arbitrary strings by mapping
    2.23 -            database names (e.g. using a hashing algorithm) to the supported
    2.24 -            set of names.
    2.25 -          </div>
    2.26 -          <p>
    2.27 -            Each <a>database</a> also has a current <dfn>version</dfn>.
    2.28 +          <p class="note">
    2.29 +            Implementations MUST support all names. If a implementation
    2.30 +            uses a storage mechanism which can't handle arbitrary database names,
    2.31 +            the implementation must use an escaping mechanism or something similar
    2.32 +            to map the provided name to a name that it can handle.
    2.33            </p>
    2.34            <div class="note">
    2.35              Each <a>database</a> has one version at a time; a <a>database</a> 
    2.36 -            can't exist in multiple versions at once. 
    2.37 +            can't exist in multiple versions at once. The only way to change the version is using a VERSION_CHANGE
    2.38 +            <a>transaction</a>.
    2.39            </div>
    2.40            <p>
    2.41 -            The act of opening a <a>database</a> creates a database 
    2.42 -            <dfn>connection</dfn>. There MAY be multiple 
    2.43 -            <a title="connection">connections</a> to a given <a>database</a> 
    2.44 -            at any given time. An operation that is attempting to read a 
    2.45 -            given piece of data in a <a>database</a> is called a 
    2.46 -            <dfn>reader</dfn> and one that is attempting to write a piece of 
    2.47 -            data is called a <dfn>writer</dfn>.
    2.48 -            <a title="reader">Readers</a> and <a title="writer">writers</a> SHOULD only operate through
    2.49 -            <a title="transaction">transactions</a>. A <a>connection</a> MAY have 
    2.50 -            any number of <dfn>active</dfn> <a title="transaction">transactions</a>.
    2.51 +            Each database contain a set of <a>object store</a>s. The set of <a>object store</a>s
    2.52 +            can changed, but can only be changed using VERSION_CHANGE transactions. When a new database is
    2.53 +            created it doesn't contain any <a>object store</a>s and has the empty string as <a>version</a>.
    2.54            </p>
    2.55            <p>
    2.56 -            <a><code>IDBDatabase</code></a> and <a><code>IDBDatabaseSync</code></a>
    2.57 -            interfaces represent <a title="connection">connections</a> to a <a>database</a>. 
    2.58 +            The act of opening a <a>database</a> creates a <dfn>connection</dfn>. There MAY be multiple 
    2.59 +            <a>connection</a>s to a given <a>database</a> at any given time. Each connection has a
    2.60 +            <dfn>closePending</dfn> flag which initially is set to false.
    2.61 +          </p>
    2.62 +          <p>
    2.63 +            When a <a>connection</a> is initially created it is in <var>opened</var> state. The connection
    2.64 +            can be <dfn title="database close">closed</dfn> through several means. If the connection is GCed
    2.65 +            or execution context where the <a>connection</a> is created is destroyed (for example due to the
    2.66 +            user navigating away from that page), the connection is closed. The connection can also be closed
    2.67 +            explicitly using the <a>steps for closing a database connection</a>. When the connection is closed
    2.68 +            the <a>closePending</a> flag is always set to true if it hasn't already been.
    2.69 +          </p>
    2.70 +          <p>
    2.71 +            The <a><code>IDBDatabase</code></a> and <a><code>IDBDatabaseSync</code></a>
    2.72 +            interfaces represent a <a>connection</a> to a <a>database</a>. 
    2.73            </p>
    2.74          </section>  <!-- IDBDatabase -->
    2.75 -        
    2.76 +
    2.77 +        <section id="transaction-concept" class="section">
    2.78 +          <h4>Transaction</h4>
    2.79 +          <p>
    2.80 +            A <dfn>transaction</dfn> is used to interact with the data in a <a>database</a>.
    2.81 +            Whenever data is read or written to the database this is done using a <a>transaction</a>.
    2.82 +          </p>
    2.83 +          <p>
    2.84 +            All transactions are created using a <a>connection</a>.
    2.85 +            The transaction has a <a>mode</a> which determines which types of interactions can be performed
    2.86 +            using the transaction. The <a>mode</a> is set when the transaction is created and remains
    2.87 +            constant for the lifetime of the transaction. The transaction also has a <dfn>scope</dfn> which
    2.88 +            determines which <a>object store</a>s the transaction can interact with. Finally, transactions
    2.89 +            have a <dfn>active</dfn> flag, which determines if new <a>request</a>s can currently be placed
    2.90 +            against the transaction. Finally, transactions also contain a <dfn>request list<dfn> of
    2.91 +            <a>request</a>s which have been placed against the transaction.
    2.92 +          </p>
    2.93 +          <p>
    2.94 +            Transactions are either static or dynamic which determines if the <a>scope</a> of the transaction
    2.95 +            can change during the lifetime of the transaction. <dfn>Static</dfn> transactions have a constant
    2.96 +            scope which is determined when the transaction is created and remains contant for the lifetime of
    2.97 +            the transaction. <dfn>Dynamic</dfn> transactions scope can change during the lifetime of the
    2.98 +            transaction.
    2.99 +          </p>
   2.100 +          <p class="issue">TODO: decide what happens when dynamic transactions need to lock a database
   2.101 +            object that is already exclusively locked by another transaction.
   2.102 +          </p>
   2.103 +          <p>
   2.104 +            <a title="transaction">Transactions</a> offer some protection from 
   2.105 +            application and system failures. A <a>transaction</a> may be used to
   2.106 +            store multiple data records or to conditionally modify certain data 
   2.107 +            records. A <a>transaction</a> represents an atomic and durable set 
   2.108 +            of data access and mutation operations. 
   2.109 +          </p>
   2.110 +          <p>
   2.111 +            <a title="transaction">Transactions</a> are expected to be short lived. This is encouraged
   2.112 +            using the automatically committing functionality described below. Authors can still cause
   2.113 +            transactions to run for a long time, however this is generally not a usage pattern which
   2.114 +            is recommended and can lead to bad user experience in some implementations.
   2.115 +          </p>
   2.116 +          <p>
   2.117 +            The <dfn title="transaction lifetime">lifetime</dfn> of a <a>transaction</a> is as follows:
   2.118 +          </p>
   2.119 +          <ol>
   2.120 +            <li>
   2.121 +              A transaction is <dfn title="transaction create">created</dfn> using of one of the available explicit
   2.122 +              APIs, for example <a class="idlType" href="#widl-IDBDatabase-transaction">IDBDatabase.transaction</a>.
   2.123 +              Which constructor is used, and the arguments passed to that constructor, determines if the transaction
   2.124 +              is <a>static</a> or <a>dynamic</a>, as well as which <a>mode</a> the transaction uses. If the transaction
   2.125 +              is <a>static</a>, the constructor arguments also determine what the <a>scope</a> of the transaction is.
   2.126 +              When a transaction is created its <a>active</a> flag is initially set to true.
   2.127 +            </li>
   2.128 +            <li>
   2.129 +              The implementation MUST allow <a>request</a>s to be <a title="place request">placed</a> against the transaction
   2.130 +              whenever the <a>active</a> flag is true. This is the case even if the transaction has not yet been
   2.131 +              <a title="transaction start">started</a>. Until the transaction is <a title="transaction start">started</a>
   2.132 +              the implementation MUST NOT execute these requests, but the implementation MUST still keep track of the
   2.133 +              <a>request</a>s and their order. Requests may only be placed against the transaction while the transaction
   2.134 +              is <a>active</a>. If a request is attempted to be placed against a transaction when it is not
   2.135 +              <a>active</a>, the implementation MUST reject the attempt by throwing a TRANSACTION_INACTIVE_ERR exception.
   2.136 +            </li>
   2.137 +            <li>
   2.138 +              Once an implementation is able to enforce the constraints defined for the <a>mode</a> of
   2.139 +              the transaction, defined below, the implementation MUST asynchronously
   2.140 +              <dfn title="transaction start">start</dfn> the transaction. When this happens is affected
   2.141 +              by the <a>mode</a> in which the transaction is opened, and which <a>object store</a>s are
   2.142 +              included in <a>scope</a> of the transaction.
   2.143 +            </li>
   2.144 +            <li class="issue">
   2.145 +              <p>
   2.146 +                Should we also define that if an implementation can't run two transactions at the same time,
   2.147 +                it MUST <a title="transaction start">start</a> them in the order they were
   2.148 +                <a title="transaction create">created</a>. Maybe only specify this if they have any overlapping
   2.149 +                <a>scope</a>. If we don't do this then starting two write transactions at the same time could
   2.150 +                result in the second one that's created running before the first one that is created.
   2.151 +              </p>
   2.152 +              <p>
   2.153 +                At least we need to ensure that a READ_ONLY transaction which is created after a READ_WRITE
   2.154 +                transaction has started sees the data that the READ_WRITE transaction wrote, and not a snapshot
   2.155 +                of what the object store looked like before the READ_WRITE transaction was started.
   2.156 +              </p>
   2.157 +              <p>
   2.158 +                Might be best to define this as part of the <a>mode</a> restrictions.
   2.159 +              </p>
   2.160 +            </li>
   2.161 +            <li>
   2.162 +              Once the transaction has been <a title="transaction start">started</a> the implementation can
   2.163 +              start executing the <a>request</a>s placed against the transaction. Unless otherwise defined requests
   2.164 +              MUST be executed in the order they are placed against the transaction. Likewise, their result MUST
   2.165 +              be returned in the order the request was placed against a specific transaction.
   2.166 +              There is no guarentee about the order that results from requests in different transactions are returned.
   2.167 +              Similarly, the isolation <a>mode</a> ensure that it doesn't matter which order requests placed against
   2.168 +              different transactions are executed.
   2.169 +            </li>
   2.170 +            <li>
   2.171 +              At any time a transaction can be <dfn>abort</dfn>ed, even if the transaction isn't currently
   2.172 +              <a>active</a>. When a transaction is aborted the implementation MUST undo (roll back) any changes
   2.173 +              made to the <a>database</a> using the transaction. This includes both changes to the contents of
   2.174 +              <a>object store</a>s as well as additions and removals of <a>object store</a>s and <a>index</a>es.
   2.175 +              <p class="note">
   2.176 +                A transaction can be aborted at any time before it is <a title="transaction finish">finished</a>.
   2.177 +                Including if it isn't <a>active</a> or hasn't yet
   2.178 +                <a title="transaction start">started</a>.
   2.179 +            </li>
   2.180 +            <li>
   2.181 +              Once a transaction no longer can become <a>active</a>, and if the transaction
   2.182 +              hasn't been <a>abort</a>ed, the implementation MUST automatically attempt to
   2.183 +              <dfn title="commit">commit</dfn> it. This usually happens after all requests placed against the
   2.184 +              transaction has been executed and their returned results handled, but no new requests has been placed
   2.185 +              against the transaction. When a transaction is committed implementation MUST atomically write
   2.186 +              any changes to the <a>database</a> made by requests placed against the transaction. That is, either all
   2.187 +              of the changes MUST be written, or if an error occurs, such as a disk write error, the implementation
   2.188 +              MUST NOT write any of the changes to the database. If such an error occurs the implementation MUST
   2.189 +              <a>abort</a> the transaction.
   2.190 +            </li>
   2.191 +            <li>
   2.192 +              When a transaction is <a>commit</a>ted or <a>abort</a>ed, it is said to be
   2.193 +              <def title="transaction finish">finished</def>. If a transaction can't be finished, for example
   2.194 +              due to the implementation crashing or the user taking some explicit action to cancel it, the
   2.195 +              implementation MUST <a>abort</a> the transaction.
   2.196 +            </li>
   2.197 +          </ol>
   2.198 +          <p>
   2.199 +            Transactions are opened in one of three <dfn title="mode">modes</dfn>. The mode
   2.200 +            determine how concurrent access to <a>object store</a>s in the transaction is isolated.
   2.201 +          </p>
   2.202 +          <ol>
   2.203 +            <li><code><dfn>READ_ONLY</dfn></code></li>
   2.204 +            <li><code><dfn>READ_WRITE</dfn></code></li>
   2.205 +            <li><code><dfn>VERSION_CHANGE</dfn></code></li>
   2.206 +          </ol>
   2.207 +
   2.208 +          <p>
   2.209 +            The transaction <a>mode</a> determines both which operations are allowed to be performed
   2.210 +            during the transaction, as well whether two transactions can run concurrently or not.
   2.211 +            Which operations are allowed be be performed are defined in detail below, but in general
   2.212 +            transactions opened in <code><a>READ_ONLY</a><code> mode are only allowed to perform
   2.213 +            reading operations which does not change data. READ_WRITE transactions are allowed to
   2.214 +            perform reading and writing transactions to existing <a>object store</a>s, where as
   2.215 +            VERSION_CHANGE transactions are allowed to perform any operations, including ones that
   2.216 +            delete and create <a>object store</a>s and <a>index</a>es.
   2.217 +          </p>
   2.218 +          
   2.219 +          <p>
   2.220 +            A VERSION_CHANGE transaction can never run concurrently with other transactions. When
   2.221 +            a VERSION_CHANGE transaction is created, the implementation MUST wait to
   2.222 +            <a title="transaction start">start</a> the VERSION_CHANGE transaction until no other transactions
   2.223 +            against the same <a>database</a> are running. As long as the VERSION_CHANGE transaction, the implementation
   2.224 +            MUST wait with <a title="transaction start">starting</a> any other transactions against the same <a>database</a>
   2.225 +            until the VERSION_CHANGE transaction is finished.
   2.226 +          </p>
   2.227 +          <p>
   2.228 +            Any number of transactions opened in <a>READ_ONLY</a> mode are allowed to run concurrently,
   2.229 +            even if the transaction's <a>scope</a> overlap and include the same <a>object store</a>s.
   2.230 +            As long as a READ_ONLY transaction is running, the data that the implementation returns
   2.231 +            through <a>request</a>s created with that transaction MUST remain
   2.232 +            constant. That is, two requests to read the same piece of data MUST yield the same result
   2.233 +            both for the case when data is found and the result is that data, and for the case when data
   2.234 +            is not found and a lack of data is indicated.
   2.235 +          </p>
   2.236 +          <p>
   2.237 +            There are a number of ways that an implementation ensure this. It can prevent
   2.238 +            READ_WRITE transactions whose scope overlap the scope of the READ_ONLY transaction from
   2.239 +            starting until the READ_ONLY transaction is finished. Or it can allow the READ_ONLY
   2.240 +            transaction to see a snapshot of contents of the <a>object store</a>s which is taken when
   2.241 +            the READ_ONLY transaction is started.
   2.242 +          </p>
   2.243 +          <p>
   2.244 +            Similarly, implementations MUST ensure that a READ_WRITE transaction is only affected by
   2.245 +            changes to <a>object store</a>s that are made using the transaction itself. I.e. the
   2.246 +            implementation MUST ensure that another transaction does not modify the contents of
   2.247 +            <a>object store</a>s in the READ_WRITE transactions <a>scope</a>. The implementation
   2.248 +            MUST also ensure that if the READ_WRITE transaction completes successfully, that the
   2.249 +            changes written to <a>object store</a>s using the transaction can be comitted to the
   2.250 +            <a>database</a> without merge conflicts. An implementation MUST NOT abort a transaction
   2.251 +            due to merge conflicts.
   2.252 +          </p>
   2.253 +          <p>
   2.254 +            A result of these requirements is that an implementation MUST NOT allow two READ_WRITE
   2.255 +            transactions access the same <a>object store</a> at the same time. Even to perform just
   2.256 +            read operations. One implementation strategy is to never start a READ_WRITE transaction
   2.257 +            until all other READ_WRITE transactions with overlapping <a>scope</a>s have finished.
   2.258 +          </p>
   2.259 +          <p class="issue">
   2.260 +            TODO: This requirement could be tightened further. Currently two READ_WRITE transactions
   2.261 +            with <b>partially</b> overlapping scopes can run in paralell, until both (or "the second") of
   2.262 +            them touch object stores in the overlapping scope.
   2.263 +          </p>
   2.264 +          <p>
   2.265 +            User agents MUST ensure a reasonable level of fairness across transactions to prevent
   2.266 +            starvation. For example if multiple READ_ONLY transaction are started one after another
   2.267 +            the implementation MUST ensure that that doesn't indefinitely prevent a pending READ_WRITE
   2.268 +            transaction from <a title="transaction start">starting</a>.
   2.269 +          </p>
   2.270 +          <p>
   2.271 +            Conforming user agents MUST automatically abort a <a>transaction</a> at
   2.272 +            the end of the scope in which it was created, if an exception is propagated to that scope.
   2.273 +          </p>
   2.274 +          <p>
   2.275 +            Static <a>transaction</a> objects implement the 
   2.276 +            <a><code>IDBTransaction</code></a> or the
   2.277 +            <a><code>IDBTransactionSync</code></a> interfaces.
   2.278 +          </p>
   2.279 +          <p>
   2.280 +             Dynamic <a>transaction</a> objects implement the 
   2.281 +            <a><code>IDBDynamicTransaction</code></a> or the
   2.282 +            <a><code>IDBDynamicTransactionSync</code></a> interfaces.
   2.283 +          </p>
   2.284 +          <div class="issue">
   2.285 +            <p>Define dynamic transactions if we agree they should be part of this specification.</p>
   2.286 +          </div>
   2.287 +        </section> <!-- IDBTransaction -->
   2.288 +
   2.289 +        <section class="section" id="request-concept">
   2.290 +          <h4>Requests</h4>
   2.291 +          <p>
   2.292 +            Each reading and writing operation on a <a>database</a> is done using a <dfn>request</dfn>.
   2.293 +            Every request represents one read or write operation. <a>Request</a>s are always belong to
   2.294 +            a <a>transaction</a>. The only exception to this is the request created when a <a>connection</a>
   2.295 +            is opened. <a>Request</a>s have a <dfn title="request done"><var>done</var></dfn> flag which
   2.296 +            initially is false, and a <dfn title="request source">source</dfn> object.
   2.297 +          </p>
   2.298 +          <p>
   2.299 +            When a request is created, it is always <dfn title="place request">placed</a> against a
   2.300 +            <a>transaction</a> using either the <a>steps to a asynchronously execute a request</a> or
   2.301 +            the <a>steps to a synchronously execute a request</a>.
   2.302 +        </section>
   2.303 +
   2.304          <section class="section" id="range-concept">
   2.305            <h4>Key Range</h4>
   2.306            <p>
   2.307 @@ -419,80 +649,6 @@
   2.308            </p>
   2.309          </section> <!-- IDBCursor -->
   2.310  
   2.311 -        <section id="transaction-concept" class="section">
   2.312 -          <h4>Transaction</h4>
   2.313 -          <p>
   2.314 -            A <dfn>transaction</dfn> is defined on a <a>database</a>. A 
   2.315 -            <a>transaction</a>'s <a>scope</a> is either 
   2.316 -            <dfn>static</dfn> or <dfn>dynamic</dfn> and it MAY include a subset of the <a>object store</a>s of the <a>transaction</a>'s 
   2.317 -            <a>database</a>. If the <a>scope</a> is <a>static</a>, then it MAY 
   2.318 -            be <dfn>global</dfn>, meaning that it includes every existing and 
   2.319 -            to be created <a>object store</a>s of the <a>database</a>. There MAY 
   2.320 -            be multiple <a title="transaction">transactions</a> active in a <a>database</a>
   2.321 -            as long as their <a title="scope">scopes</a> do not overlap or the overlapping
   2.322 -            objects are locked in <a title="mode">modes</a> that are not mutually exclusive.
   2.323 -          </p>
   2.324 -          <p class="XXX">TODO: decide what happens when dynamic transactions need to lock a database
   2.325 -            object that is already exclusively locked by another transaction.
   2.326 -          </p>
   2.327 -          <p>
   2.328 -            Concurrent access to the <a title="object store">object stores</a> in a <a>transaction</a>
   2.329 -            MAY be isolated in one of three <dfn title="mode">modes</dfn>. These are:</p>
   2.330 -            <ol>
   2.331 -              <li><code>READ_ONLY</code></li>
   2.332 -              <li><code>READ_WRITE</code></li>
   2.333 -              <li><code>VERSION_CHANGE</code></li>
   2.334 -            </ol>
   2.335 -          <p>
   2.336 -          	Any number of <a title="reader">readers</a> may concurrently access all <a title="object store">object stores</a>.
   2.337 -          	A <a>writer</a> MUST behave as if there were no 
   2.338 -          	<a title="reader">readers</a> concurrently accessing the <a>object store</a>, such that 
   2.339 -          	a <a>writer</a> either cannot access the <a>object store</a> while <a title="reader">readers</a>
   2.340 -          	are accessing the <a>object store</a> or their changes are not 
   2.341 -          	visible to <a title="reader">readers</a> that were active at the time the <a>writer</a> started. 
   2.342 -          </p>
   2.343 -          <p>
   2.344 -          	User agents need to ensure a reasonable level of fairness across <a title="reader">readers</a>
   2.345 -          	and <a title="writer">writers</a> to prevent starvation.
   2.346 -          </p>
   2.347 -          <p>
   2.348 -            <a title="transaction">Transactions</a> offer some protection from 
   2.349 -            application and system failures. A <a>transaction</a> MAY be used to
   2.350 -            store multiple data records or to conditionally modify certain data 
   2.351 -            records. A <a>transaction</a> represents an atomic and durable set 
   2.352 -            of data access and mutation operations. 
   2.353 -          </p>
   2.354 -          <p>  
   2.355 -            <a title="transaction">Transactions</a> are expected to be short
   2.356 -            lived. A <a>transaction</a> may be programmatically aborted. 
   2.357 -            Conforming user agents MUST automatically:
   2.358 -          </p>
   2.359 -          <ul>
   2.360 -            <li>
   2.361 -            commit a <a>transaction</a> at the end of the scope in
   2.362 -            which it was created unless there is an active operation being 
   2.363 -            performed using that transaction, in which case, the transaction is 
   2.364 -            automatically committed when that operation is completed. 
   2.365 -            </li>
   2.366 -            <li>
   2.367 -            abort a <a>transaction</a> at the end of the scope in which it was 
   2.368 -            created, if an exception is propagated to that scope.
   2.369 -            </li>
   2.370 -          </ul>
   2.371 -          <p>
   2.372 -            Static <a>transaction</a> objects implement the 
   2.373 -            <a><code>IDBTransaction</code></a> or the
   2.374 -            <a><code>IDBTransactionSync</code></a> interfaces.
   2.375 -          </p>
   2.376 -          <p>
   2.377 -             Dynamic <a>transaction</a> objects implement the 
   2.378 -            <a><code>IDBDynamicTransaction</code></a> or the
   2.379 -            <a><code>IDBDynamicTransactionSync</code></a> interfaces.
   2.380 -          </p>
   2.381 -          <div class="issue">
   2.382 -            <p>Define dynamic transactions if we agree they should be part of this specification.</p>
   2.383 -          </div>
   2.384 -        </section> <!-- IDBTransaction -->
   2.385          <section class="section">
   2.386            <h3>The <code>IDBDatabaseException</code> Interface</h3>
   2.387            <dl class="idl" title="exception IDBDatabaseException">
   2.388 @@ -516,7 +672,13 @@
   2.389              <dd>Data provided to an operation does not meet requirements.</dd>
   2.390              <dt>const unsigned short NOT_ALLOWED_ERR = 5</dt>
   2.391              <dd>A mutation operation was attempted on a database that
   2.392 -            did not allow mutations.</dd>
   2.393 +            <dt>const unsigned short TRANSACTION_INACTIVE_ERR = 6</dt>
   2.394 +            <dd>A <a>request</a> was placed against a transaction which is
   2.395 +            currently not <a>active</a>, or which is
   2.396 +            <a title="transaction finish">finished</a>.</dd>
   2.397 +            <dt>const unsigned short ABORT_ERR = 7</dt>
   2.398 +            <dd>A <a>request</a> was aborted, for example through a call
   2.399 +            to <a href="#widl-IDBTransaction-abort"><code>IDBTransaction.abort</code></a>.</dd>
   2.400              <dt>const unsigned short SERIAL_ERR = 11</dt>
   2.401              <dd>The operation failed because of the size of the data set 
   2.402              being returned or because there was a problem in serializing or 
     3.1 --- a/Speclet_021_IDB_API_Algorithms.html	Mon Oct 25 11:08:37 2010 -0700
     3.2 +++ b/Speclet_021_IDB_API_Algorithms.html	Fri Oct 29 09:13:37 2010 -0700
     3.3 @@ -137,29 +137,37 @@
     3.4          <section class="section" id="opening">
     3.5            <h4>Opening the database</h4>
     3.6            <p>
     3.7 -            The <dfn>steps for opening a database</dfn> are as follows. These 
     3.8 -            steps MUST be run with an origin, a database name and an optional
     3.9 -            description. All the steps MUST be run atomically:
    3.10 +            The <dfn>steps for opening a database</dfn> are as follows. The algorithm in these steps
    3.11 +            take three arguments. A <var>origin</var> which requested the <a>database</a> to be opened,
    3.12 +            a database <var>name</var>. It also optionally takes a <var>request</var> which represents
    3.13 +            a <a>request</a> used when opening the database is done using an asynchronous API.
    3.14            </p>
    3.15            
    3.16            <ol>
    3.17              <li>
    3.18 -              If there is already a database with the given name from the origin
    3.19 -              <var>origin</var>, then let <var>db</var> be that database. If a description is passed to these steps, set the description of <var>db</var> to that.
    3.20 +              If these steps fail for any reason, return a error with the appropriate code and abort
    3.21 +              this algorithm.
    3.22              </li>
    3.23 -            
    3.24 +            <li>
    3.25 +              If there is already a database with the given name from the origin <var>origin</var>, then
    3.26 +              let <var>db</var> be that database.
    3.27 +            </li>
    3.28              <li>
    3.29                If no database with the given name from the origin <var>origin</var>
    3.30 -              exists, then create the database <var>db</var> with the name and
    3.31 -              description passed to these steps.
    3.32 +              exists, then create the database <var>db</var> with name <var>name</var>.
    3.33              </li>
    3.34 -  
    3.35              <li>
    3.36 -              Create a <a>connection</a> to <var>db</var> and call it <var>result</var>.
    3.37 +              Wait until no already existing <a>connection</a>s to <var>db</var>, have
    3.38 +              non-<a title="transaction finish">finished</a> VERSION_CHANGE <a>transaction</a>s.
    3.39 +              <p class="note">
    3.40 +                There can potentially be several <a>connection</a>s waiting for a VERSION_CHANGE transaction
    3.41 +                to finish. Once that transaction <a title="transaction finish">finishes</a> another <a>connection</a>
    3.42 +                could be created and a new VERSION_CHANGE transaction could be started before these steps has
    3.43 +                a chance to continue. In that case the implementation MUST keep waiting at this step.
    3.44 +              </p>
    3.45              </li>
    3.46 -            
    3.47              <li>
    3.48 -              Return <var>result</var>.
    3.49 +              Create a <a>connection</a> to <var>db</var> and return it.
    3.50              </li>
    3.51            </ol>        
    3.52          </section>
    3.53 @@ -368,55 +376,43 @@
    3.54            <h4>Transaction Creation steps</h4>
    3.55            <p>
    3.56              When the user agent is to <dfn>create a static <a>transaction</a></dfn>
    3.57 -            it MUST run the following steps. These steps MUST be run with 
    3.58 -            two parameters - <a>database</a>, an optional global flag, and an 
    3.59 -            optional list of names of <a>database</a> <a>objects</a> to be 
    3.60 -            reserved.
    3.61 +            it MUST run the following steps. This algorithm takes four parameters:
    3.62 +            A <a><var>connection</var></a>, a <a><var>mode</var></a>, a list of <var>names</var> of
    3.63 +            <a>object store</a>s to be included in the <a>scope</a> of the transaction, and a
    3.64 +            <var>timeout</var> for the transaction <a title="transaction start">starting</a>.
    3.65            </p>
    3.66            
    3.67            <ol>
    3.68              <li>
    3.69 -              Pick the appropriate steps:
    3.70 -              <dl class="switch">
    3.71 -                <dt>If these steps are called with the global flag set</dt>
    3.72 -                <dd>Acquire a lock on the entire database.</dd>
    3.73 -                <dt>If these steps are called with a non-empty list of <a>object store</a> <a title="object store name">name</a>s</dt>
    3.74 -                <dd>
    3.75 -                    Acquire appropriate locks on each of the named 
    3.76 -                    <a>object store</a> in an ordered sequence. 
    3.77 -                    <div class="note">
    3.78 -                      A user agent MAY obtain a shared or exclusive lock on 
    3.79 -                      the database if it does not perform fine grained locking.
    3.80 -                    </div>
    3.81 -                </dd>
    3.82 -              </dl>
    3.83 -            </li>
    3.84 -
    3.85 -            <li>
    3.86 -              If a timeout duration is passed to these steps and is exceeded 
    3.87 -              when acquiring locks, then set <var>code</var> to 
    3.88 -              <a class="idlType" href="#widl-IDBDatabaseException-TIMEOUT_ERR"><code>TIMEOUT_ERR</code></a> and jump to the last step.
    3.89 -            </li>
    3.90 -
    3.91 -            <li>
    3.92 -              Open a new transaction to the database, and create a
    3.93 -              <a><code>IDBTransaction</code></a> object
    3.94 -              that represents that transaction. Let <var>transaction</var> be 
    3.95 -              this object.
    3.96 -            </li>
    3.97 -            
    3.98 -            <li>
    3.99 -              Set the current transaction of this <a><code>IDBDatabase</code></a> object
   3.100 -              to <var>transaction</var>.
   3.101 +              If any of the strings in <var>names</var> identifies an <a>object store</a> which doesn't
   3.102 +              exist, throw a NOT_FOUND_ERR exception. If the <a>closePending</a>
   3.103 +              flag is set on <var>connection</var> the throw a NOT_ALLOWED_ERR.
   3.104              </li>
   3.105              <li>
   3.106 -              Return <var>transaction</var>. End these steps.
   3.107 +              <a title="transaction create">Create</a> a <a>transaction</a> using <var>connection</var> as
   3.108 +              <a>connection</a>, <var>mode</var> as <a>mode</a>, and the <a>object store</a>s identified in
   3.109 +              <var>names</var> as <a>scope</a>.
   3.110              </li>
   3.111              <li>
   3.112 -              This step is only performed in case of error. If this step is performed
   3.113 -              synchronously, then raise a newly constructed 
   3.114 -              <a><code>IDBDatabaseException</code></a> 
   3.115 -              exception <var>exception</var> with the code <var>code</var>.
   3.116 +              If these steps are running asynchronously, return the created <a>transaction</a> and run the
   3.117 +              remaining steps asynchronously. When control is returned to the event loop, the implementation
   3.118 +              MUST set the <a>active</a> flag to false.
   3.119 +            </li>
   3.120 +            <li>
   3.121 +              Wait until the <a>transaction</a> can be <a title="transaction start">started</a> according to the
   3.122 +              <a>transaction lifetime</a> rules. If this takes longer than the specified <var>timeout</var> then:
   3.123 +              <ul>
   3.124 +                <li>
   3.125 +                  If these steps are run asynchronously, run the <a>steps for aborting a transaction</a> using
   3.126 +                  TIMEOUT_ERR as <var>code</var>.
   3.127 +                </li>
   3.128 +                <li>
   3.129 +                  If steps are run synchronously, throw a TIMEOUT_ERR exception.
   3.130 +                </li>
   3.131 +              </ul>
   3.132 +            </li>
   3.133 +            <li>
   3.134 +              If these steps are running synchronously, return the created <a>transaction</a>.
   3.135              </li>
   3.136            </ol>
   3.137            <div class="issue">
   3.138 @@ -424,31 +420,144 @@
   3.139            </div>     
   3.140          </section>
   3.141          <section class="section">
   3.142 +          <h4>Steps for aborting a transaction</h4>
   3.143 +          <p>
   3.144 +            When taking the <dfn>steps for aborting a <a>transaction</a></dfn> the implementation MUST
   3.145 +            execute the following algorithm. This algorithm takes two parameter, the <var>transaction</var> to abort
   3.146 +            and a <var>code</var>.
   3.147 +          </p>
   3.148 +          <ol>
   3.149 +            <li>
   3.150 +              All the changes made to the <a>database</a> the transaction uses are reverted. For VERSION_CHANGE
   3.151 +              transactions this includes changes to the set of <a>object store</a>s and <a>index</a>es, as well
   3.152 +              as the change to the <a>version</a>.
   3.153 +            </li>
   3.154 +            <li>
   3.155 +              If the transaction's <a>request list</a> contain any <a>request</a>s whose <a title="request done">done</a> flag
   3.156 +              is still false, <a>fire a error event</a> with code <var>code</code> against each such <a>request</a>
   3.157 +              and set its <a title="request done">done</a> flag to true. Also abort the <a>steps for asynchronously
   3.158 +              executing a request</a> for each such transaction.
   3.159 +            </li>
   3.160 +          </ol>
   3.161 +        </section>
   3.162 +        <section class="section">
   3.163 +          <h4>Steps for asynchronously executing a <a>request</a></h4>
   3.164 +          <p>
   3.165 +            When taking the <dfn>steps to a asynchronously execute a request</dfn> the implementation MUST run the
   3.166 +            following algorithm. The algorithm takes a <var>source</var> object and a <var>operation</var> to
   3.167 +            perform on a database.
   3.168 +          </p>
   3.169 +          <p>
   3.170 +            These steps can be aborted at any point if the <a>transaction</a> the created <a>request</a> belongs
   3.171 +            to is <a title="transaction abort">aborted</a> using the <a>steps for aborting a transaction</a>
   3.172 +          </p>
   3.173 +          <ol>
   3.174 +            <li>
   3.175 +              Set <var>transaction</var> to the <a>transaction</a> associated with <var>source</var>.
   3.176 +            </li>
   3.177 +            <li>
   3.178 +              Create a <a>IDBRequest</a> object and set <var>request</var> to this object. Set <var>request</var>'s
   3.179 +              <a title="request source">source</a> to <var>source</var> and add <var>request</var> to the end of the
   3.180 +              <a title="request list">list</a> of <a>request</a>s in <var>transaction</var>. Return
   3.181 +              this object and run the remaining steps in this algorithm asynchronously.
   3.182 +              <p class="note">
   3.183 +                Cursors override this step to reuse an existing <a>IDBRequest</a>. However they still put the
   3.184 +                <a>IDBRequest</a> at the end of the list of <a>request</a>s in <var>transaction</var>.
   3.185 +              </p>
   3.186 +            </li>
   3.187 +            <li>
   3.188 +              Wait until all previously added <a>requests<a> in <var>transaction</var> have their
   3.189 +              <a title="request done">done</a> flag set to true.
   3.190 +            </li>
   3.191 +            <li>
   3.192 +              Perform <var>operation</var>.
   3.193 +            </li>
   3.194 +            <li>
   3.195 +              If performing <var>operation</var> succeeded then set the <a title="request done">done</a> flag
   3.196 +              on the <var>request</var> to true and <a>fire a success event</a> at <var>request</var> with
   3.197 +              the result of the operation.
   3.198 +            </li>
   3.199 +            <li>
   3.200 +              If performing <var>operation</var> failed then set the <a title="request done">done</a> flag
   3.201 +              on the <var>request</var> to true and <a>fire a error event</a> at <var>request</var> with
   3.202 +              the code of the error from <var>operation</var>.
   3.203 +            </li>
   3.204 +          </ol>
   3.205 +        </section>
   3.206 +        <section class="section">
   3.207 +          <h4>Steps for synchronously executing a <a>request</a></h4>
   3.208 +          <p>
   3.209 +            When taking the <dfn>steps to a synchronously execute a request</dfn> the implementation MUST run the
   3.210 +            following algorithm. The algorithm takes a <var>transaction</var> object and a <var>operation</var> to
   3.211 +            perform on a database.
   3.212 +          </p>
   3.213 +          <ol>
   3.214 +            <li>
   3.215 +              Perform <var>operation</var>.
   3.216 +            </li>
   3.217 +            <li>
   3.218 +              If performing <var>operation</var> succeeded then set return the result of the operation.
   3.219 +            </li>
   3.220 +            <li>
   3.221 +              If performing <var>operation</var> failed then throw a IDBDatabaseException with the code
   3.222 +              of the error from <var>operation</var>.
   3.223 +            </li>
   3.224 +          </ol>
   3.225 +        </section>
   3.226 +        <section class="section">
   3.227            <h4>VERSION_CHANGE transaction steps</h4>
   3.228            <p>
   3.229              The <dfn>steps for running a <code>VERSION_CHANGE</code> transaction</dfn> are
   3.230 -            as follows. These steps MUST be run with three parameters - a <var>database</var>,
   3.231 -            a new <var>version number</var> to be set for the <var>database</var> and a <var>request</var>
   3.232 -            object representing the <a><code>IDBRequest</code></a> instance associated with this transaction.
   3.233 +            as follows. This algorithm takes two parameters - a <var>connection</var> object which is used
   3.234 +            to update the <a>database</a> and a new <var>version number</var> to be set for the <a>database</a>.
   3.235            </p>
   3.236            <ol>
   3.237              <li>
   3.238 -              Let <var>openDatabases</var> be the set of all <a><code>IDBDatabase</code></a> object representing
   3.239 -              the given <var>database</var>.
   3.240 +              Create a new <a>transaction</a> with <a>mode</a> set to VERSION_CHANGE and <var>connection</var> used as <a>connection</a>.
   3.241 +              The <a>scope</a> of the transaction includes every <a>object store</a> in <var>connection</var>. Set its
   3.242 +              <a>active</a> flag to false.
   3.243              </li>
   3.244              <li>
   3.245 -              Fire a <a><code>versionchange</code></a> event targeted at each object in the <var>openDatabases</var> set.
   3.246 -              The <code>version</code> property of this event must be set to the given <var>version number</var>.
   3.247 +              Create a new <a>request</a> which uses the <a>IDBVersionChangeRequest</a> interface and return it.
   3.248 +              The remaining steps in this algorithm are run asynchronously.
   3.249              </li>
   3.250              <li>
   3.251 -              Wait until all objects in <var>openDatabases</var> are closed.
   3.252 +              Let <var>openDatabases</var> be the set of all <a><code>IDBDatabase</code></a> and <a><code>IDBDatabaseSync</code></a>
   3.253 +              objects, except <var>connection</var>, connected to the same <a>database</a> as <var>connection</var>.
   3.254              </li>
   3.255              <li>
   3.256 -              Start a new <a><code>transaction</code></a> with <a><code>mode</code></a> set to <a><code>VERSION_CHANGE</code></a>.
   3.257 -              Note that as long as this transaction is running, no other <a><code>IDBDatabase</code></a> objects can be open.
   3.258 +              <p>
   3.259 +                Fire a <code>versionchange</code> event at each object in <var>openDatabases</var> that is open. The event MUST NOT
   3.260 +                be fired on objects which has the <code>closePending</code> flag set. The event MUST use the
   3.261 +                <a><code>IDBVersionChangeEvent</code></a> interface and have the
   3.262 +                <a href="#widl-IDBVersionChangeEvent-version"><code>version</code></a> property set to <var>version number</var>.
   3.263 +                This event MUST NOT bubble or be cancelable.
   3.264 +              </p>
   3.265 +              <p class="note">
   3.266 +                Firing this event might cause one or more of the other objects in <var>openDatabases</var> to be closed, in which case
   3.267 +                the <code>versionchange</code> event MUST NOT be fired at those objects if that hasn't yet been done.
   3.268 +              </p>
   3.269              </li>
   3.270              <li>
   3.271 -              Set the version of the <var>database</var> to the given <var>version number</var>.
   3.272 +              <p>
   3.273 +                If any of the <a>connection</a>s in <var>openDatabases</var> are still not closed, fire a <code>blocked</code> event at
   3.274 +                <var>request</var>. The event MUST use the <a><code>IDBVersionChangeEvent</code></a> interface and have the
   3.275 +                <a href="#widl-IDBVersionChangeEvent-version"><code>version</code></a> property set to <var>version number</var>.
   3.276 +                This event MUST NOT bubble or be cancelable.
   3.277 +              </p>
   3.278 +            </li>
   3.279 +            <li>
   3.280 +              Wait until all objects in <var>openDatabases</var> are <a title="database close">closed</a> and all of
   3.281 +              their transactions are <a title="transaction finish">finished</a>.
   3.282 +              <p class="issue">Should we allow <code>blocked</code> to be fired here too, if waiting takes "too long"?</p>.
   3.283 +            </li>
   3.284 +            <li>
   3.285 +              Start a the <a>transaction</a> created above. Note that until this <a>transaction</a> is finished, no other <a>connection</a>s
   3.286 +              can be opened to the same <a>database</a>.
   3.287 +            </li>
   3.288 +            <li>
   3.289 +              Set the version of <var>database</var> to the given <var>version number</var>. This change is considered part of the
   3.290 +              <a><code>transaction</code></a>, and so if the transaction is <a>abort</a>ed, this change is reverted.
   3.291              </li>
   3.292              <li>
   3.293                Fire a <a><code>success</code></a> event targeted at the <var>request</var> object. The <a><code>result</code></a>
   3.294 @@ -456,30 +565,84 @@
   3.295                <a><code>VERSION_CHANGE</code></a> transaction created in step 4.
   3.296              </li>
   3.297              <li>
   3.298 -              Follow the normal steps for executing a <a><code>transaction</code></a> and let the  <a><code>transaction</code></a>
   3.299 -              complete normally.
   3.300 +              Follow the normal steps for executing a <a><code>transaction</code></a> and let the <a><code>transaction</code></a>
   3.301 +              finish normally.
   3.302              </li>
   3.303            </ol>
   3.304          </section>
   3.305          <section class="section">
   3.306            <h4>Database closing steps</h4>
   3.307 -          <p>The <dfn>steps for closing a database connection</dfn> are as follows. These steps MUST be run with one parameter
   3.308 -            - a <var>database</var> object of type <a><code>IDBDatabase</code></a>.</p>
   3.309 +          <p>The <dfn>steps for closing a database connection</dfn> are as follows. These steps take one argument, a <var>connection</var> object.
   3.310            <ol>
   3.311              <li>
   3.312 -              Set the internal <code>closePending</code> flag of the <var>database</var> object to true. If the <code>transaction()</code> method
   3.313 -              is called on the <var>database</var> object while the <code>closePending</code> is set, an exception will be thrown.
   3.314 +              Set the internal <a><code>closePending</code></a> flag of <var>connection</var> to true.
   3.315              </li>
   3.316              <li>
   3.317 -              Wait for all pending transactions on the <var>database</var> to complete. Once they are complete, the <var>database</var> is
   3.318 -              fully closed.
   3.319 +              Wait for all transactions <a title="transaction create">created</a> using <var>connection</var> to complete.
   3.320 +              Once they are complete, <var>connection</var> is <dfn title="database close">closed</dfn>.
   3.321 +            </li>
   3.322 +          </ol>
   3.323 +          <p class="note">
   3.324 +            Once the <a><code>closePending</code></a> flag has ben set to true no new transactions can be
   3.325 +            <a title="transaction create">created</a> using <var>connection</var>. All functions that
   3.326 +            <a title="transaction create">create</a> transactions first check the the <a>closePending</a> flag first and
   3.327 +            throw an exception if it is true.
   3.328 +          </p>
   3.329 +        </section>
   3.330 +        <section class="section">
   3.331 +          <h4>Fire a success event</h4>
   3.332 +          <p>
   3.333 +            To <dfn title="fire a success event">fire a success event with result <var>result</var></dfn> at a <a>request</a>,
   3.334 +            the implementation MUST run the following steps:
   3.335 +          </p>
   3.336 +          <ol>
   3.337 +            <li>
   3.338 +              Set <var>transaction</var> to the <a>transaction</a> associated with the <a title="request source">source</a>.
   3.339              </li>
   3.340              <li>
   3.341 -              Unblock any pending <code>setVersion()</code> calls made on other <a><code>IDBDatabase</code></a> objects connected to the same
   3.342 -              database.
   3.343 +              Set the <a>active</a> flag of <var>transaction</var> to true.
   3.344 +            </li>
   3.345 +            <li>
   3.346 +              Dispatch a <a title="event-success">success event</a>, which does not bubble and is not
   3.347 +              cancelable, at <a>request</a>. The event must use the <a><code>IDBSuccessEvent</code></a> interface and have its 
   3.348 +              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to <var>result</var>. The
   3.349 +              <a class="idlType" href="#widl-IDBEvent-source"><code>source</code></a> is set to <var>request</var>s
   3.350 +              <a title="request source">source</a>. And <a class="idlType" href="#widl-IDBTransactionEvent-result"><code>transaction</code></a>
   3.351 +              is set to <var>transaction</var>.
   3.352 +            </li>
   3.353 +            <li>
   3.354 +              Set the <a>active</a> flag of <var>transaction</var> to false.
   3.355              </li>
   3.356            </ol>
   3.357          </section>
   3.358 +        <section class="section">
   3.359 +          <h4>Fire an error event</h4>
   3.360 +          <p>
   3.361 +            To <dfn title="fire a error event">fire a error event with code <var>code</var></dfn> at a <a>request</a>,
   3.362 +            the implementation MUST run the following steps:
   3.363 +          </p>
   3.364 +          <ol>
   3.365 +            <li>
   3.366 +              Set <var>transaction</var> to the <a>transaction</a> associated with the <a title="request source">source</a>.
   3.367 +            </li>
   3.368 +            <li>
   3.369 +              Set the <a>active</a> flag of <var>transaction</var> to true.
   3.370 +            </li>
   3.371 +            <li>
   3.372 +              Dispatch a <a title="event-error">error event</a> at <a>request</a>. The event must use
   3.373 +              the <a><code>IDBErrorEvent</code></a> interface and have its 
   3.374 +              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to <var>code</var>. The
   3.375 +              <a class="idlType" href="#widl-IDBEvent-source"><code>source</code></a> is set to <var>request</var>s internal
   3.376 +              <a title="request source">source</a>. The <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a> is
   3.377 +              set to a string appropriate for <var>code</var>.
   3.378 +            <li>
   3.379 +              Set the <a>active</a> flag of <var>transaction</var> to false.
   3.380 +            </li>
   3.381 +          </ol>
   3.382 +          <p class="issue">
   3.383 +            TODO: need to define more error handling here.
   3.384 +          </p>
   3.385 +        </section>
   3.386        </section>
   3.387        <!-- end-content -->
   3.388      </section>
     4.1 --- a/Speclet_022_IDB_API_Synchronous_APIs.html	Mon Oct 25 11:08:37 2010 -0700
     4.2 +++ b/Speclet_022_IDB_API_Synchronous_APIs.html	Fri Oct 29 09:13:37 2010 -0700
     4.3 @@ -152,48 +152,33 @@
     4.4            <dl class="idl" title="interface IDBFactorySync">
     4.5              <dt>IDBDatabaseSync open()</dt>
     4.6              <dd>
     4.7 +              <p>
     4.8 +                When invoked, this method synchronously runs the <a>steps for opening a database</a>.
     4.9 +                Let <var>origin</var> be the origin of the <a>IDBEnvironmentSync</a> used to access
    4.10 +                this <a>IDBFactorySync</a>, <var>name</var> be the <var>name</var> argument passed
    4.11 +                to the function and <var>request</var> be the created <a>IDBRequest</a>.
    4.12 +              </p>
    4.13 +              <p>
    4.14 +                The <var>description</var> argument is intentionally ignored. The implementation MAY
    4.15 +                use it to improve UI if so desired.
    4.16 +              </p>
    4.17 +              <p>
    4.18 +                If an error is returned from the steps above, then the implementation MUST
    4.19 +                throw an <a><code>IDBDatabaseException</code></a> with its 
    4.20 +                <a class="idlType" href="#widl-IDBDatabaseException-code"><code>code</code></a>
    4.21 +                and <a class="idlType" href="#widl-IDBDatabaseException-message"><code>message</code></a> set to
    4.22 +                appropriate values for the error.
    4.23 +              </p>
    4.24 +              <p>
    4.25 +                If the steps above are successful, the implementation MUST create a IDBDatabaseSync
    4.26 +                object representing the created <a>connection</a> and return it.
    4.27 +              </p>
    4.28                <dl class="parameters">
    4.29                  <dt>DOMString name</dt>
    4.30                  <dd>The <a title="database name">name</a> for the <a>database</a></dd>
    4.31 -                <dt>DOMString description</dt>
    4.32 +                <dt>optional DOMString description</dt>
    4.33                  <dd>The description for the <a>database</a></dd>
    4.34                </dl>
    4.35 -              <dl class="exception" title="IDBDatabaseException">
    4.36 -                <dt>UNKNOWN_ERR</dt>
    4.37 -                <dd>if an error occurs while the <a>database</a> <a>connection</a> 
    4.38 -                is being opened</dd>
    4.39 -                <dt>NON_TRANSIENT_ERR</dt>
    4.40 -                <dd>if the <var>name</var> parameter is not <a>valid</a></dd>
    4.41 -              </dl>
    4.42 -              <p>
    4.43 -                The synchronous API for databases blocks the calling thread until a
    4.44 -                <a><code>IDBDatabaseSync</code></a> object is ready to return.
    4.45 -                When this method is invoked, the user agent MUST run the
    4.46 -                following steps:
    4.47 -              </p>
    4.48 -    
    4.49 -              <ol>
    4.50 -                <li>
    4.51 -                  Let <var>origin</var> be the origin of the scripts in the worker.
    4.52 -                </li>
    4.53 -                <li>
    4.54 -                  Perform the <a>steps for opening a database</a>, with <var>origin</var>,
    4.55 -                  the <var>name</var> parameter and <var>description</var> parameter, and 
    4.56 -                  call its result as <var>result</var>.
    4.57 -                </li>
    4.58 -                <li>
    4.59 -                  If the steps were aborted with an error code, then throw a newly constructed
    4.60 -                  <a><code>IDBDatabaseException</code></a> 
    4.61 -                  exception with the code of that error and abort these steps.
    4.62 -                </li>
    4.63 -                <li>
    4.64 -                  Create a <a><code>IDBDatabaseSync</code></a> object using <var>result</var>
    4.65 -                  and call it <var>db</var>.
    4.66 -                </li>
    4.67 -                <li>
    4.68 -                  Return <var>db</var>.
    4.69 -                </li>
    4.70 -              </ol>              
    4.71              </dd>
    4.72            </dl>
    4.73          </section>
    4.74 @@ -331,10 +316,20 @@
    4.75              </dd>
    4.76              <dt>IDBTransactionSync transaction()</dt>
    4.77              <dd>
    4.78 -              Perform the <a>steps for creating a transaction</a> with the list of 
    4.79 -              database objects in the scope of this transaction and a timeout 
    4.80 -              duration in milliseconds, and return
    4.81 -              the resulting <a><code>IDBTransactionSync</code></a> object.
    4.82 +              <p>
    4.83 +                This method, when called MUST execute the
    4.84 +                <a title="create a static transaction">steps for creating a transaction</a> in a asychronous
    4.85 +                fashion. If the <var>storeNames</var> argument is provided and non-empty then then use that
    4.86 +                list as the <var>names</var> argument. Otherwise use the full set of <a>object store</a>
    4.87 +                names for the <a>IDBDatabase</a> as <var>names</var> argument. The <var>mode<var> and
    4.88 +                <var>timeout</var> arguments are forwarded to the algorithm as-is. The <var>connection</var>
    4.89 +                argument is set to the <a>IDBDatabase</a> that the <code>transaction()</code> method was
    4.90 +                called on.
    4.91 +              </p>
    4.92 +              <p>
    4.93 +                The method returns a <a>IDBTransactionSync</a> object representing the <a>transaction</a>
    4.94 +                returned by the steps above</a>.
    4.95 +              </p>
    4.96                <dl class="parameters">
    4.97                  <dt>optional DOMStringList storeNames</dt>
    4.98                  <dd>The names of <a title="object store">object stores</a> and 
    4.99 @@ -349,10 +344,12 @@
   4.100                <dl class="exception" title="IDBDatabaseException">
   4.101                  <dt><a class="idlType" href="#widl-IDBDatabaseException-TIMEOUT_ERR"><code>TIMEOUT_ERR</code></a></dt>
   4.102                  <dd>
   4.103 -                If reserving all the <a>database</a> objects identified in the new
   4.104 -                <a title="transaction">transaction's</a> <a>scope</a> takes longer 
   4.105 -                than the specified interval.
   4.106 +                If <a title="transaction start">starting</a> the transaction takes longer than the specified timeout.
   4.107                  </dd>
   4.108 +                <dt>NOT_ALLOWED_ERR</dt>
   4.109 +                <dd>The close() method has been called on this <a>IDBDatabase</a> instance.</dd>
   4.110 +                <dt>NOT_FOUND_ERR</dt>
   4.111 +                <dd>One of the names provided in the <var>storeNames</var> argument doesn't exist in this <a>database</a>.</dd>
   4.112                </dl>
   4.113              </dd>
   4.114            </dl>  
   4.115 @@ -535,13 +532,15 @@
   4.116                  <dd>The <a>unique</a> flag for the new <a>index</a>. The default
   4.117                  value of this parameter is false.</dd>
   4.118                </dl>
   4.119 -            <dt>IDBIndexSync openIndex()</dt>
   4.120 +            <dt>IDBIndexSync index()</dt>
   4.121              <dd>
   4.122 -              <p>
   4.123 -                This method opens the <a>index</a> with the given name
   4.124 -                in the <a title="connection">connected</a> <a>database</a> for the
   4.125 -                <a>mode</a> specified.
   4.126 -              </p>              
   4.127 +              Returns a <a>IDBIndexSync</a> representing a <a>index</a> that is part of the
   4.128 +              to this <a>object store</a>. Every call to this function on the same
   4.129 +              <a>IDBObjectStoreSync</a> instance and with the same <var>name</var> returns the same <a>IDBIndexSync</a> instance.
   4.130 +              However the retured <a>IDBIndexSync</a> instance is specific to this <a>IDBObjectStoreSync</a> instance. If this
   4.131 +              function is called on a different <a>IDBObjectStoreSync</a> instance, a different <a>IDBIndexSync</a> instance is
   4.132 +              returned. A result of this is that different <a>IDBTransactionSync</a>s use different <a>IDBIndexSync</a> instances
   4.133 +              to represent the same <a>index</a>.
   4.134                <dl class="parameters">
   4.135                  <dt>DOMString name</dt>
   4.136                  <dd>The <a title="index name">name</a> of an existing <a>index</a></dd>
   4.137 @@ -913,8 +912,11 @@
   4.138                is a part</dd>
   4.139              <dt>IDBObjectStoreSync objectStore()</dt>
   4.140              <dd>
   4.141 -              Immediately returns the object store that has been already added 
   4.142 -              to the <a>scope</a> of this <a>transaction</a>. 
   4.143 +              Returns a <a>IDBObjectStoreSync</a> representing a <a>object store</a> that is part of the
   4.144 +              to the <a>scope</a> of this <a>transaction</a>. Every call to this function on the same
   4.145 +              <a>IDBTransactionSync</a> instance and with the same <var>name</var> returns the same <a>IDBObjectStoreSync</a> instance.
   4.146 +              However the retured <a>IDBObjectStoreSync</a> instance is specific to this <a>IDBTransactionSync</a>. If this
   4.147 +              function is called on a different <a>IDBTransactionSync</a>, a different <a>IDBObjectStoreSync</a> instance is returned.
   4.148                <dl class="parameters">
   4.149                  <dt>DOMString name</dt>
   4.150                  <dd>The requested <a>object store</a></dd>
   4.151 @@ -929,13 +931,11 @@
   4.152              </dd>
   4.153              <dt>void abort()</dt>
   4.154              <dd>
   4.155 -              This method signals the need to cancel the effects of
   4.156 -              operations performed in this <a>transaction</a>. To perform
   4.157 -              this method, the user agent ignores all the changes performed to the
   4.158 -              <a>objects</a> of this <a>database</a> since the creation of this 
   4.159 -              <a>transaction</a>.
   4.160 +              If this <a>transaction</a> is <a title="transaction finish">finished</a>, throw a NOT_ALLOWED_ERR
   4.161 +              exception. Otherwise this method <a title="transaction abort">aborts</a> the transaction by running the
   4.162 +              <a>steps to abort a transaction</a> with <var>code</var> set to ABORT_ERR.
   4.163                <dl class="exception" title="IDBDatabaseException">
   4.164 -                <dt>NON_TRANSIENT_ERR</dt>
   4.165 +                <dt>NOT_ALLOWED_ERR</dt>
   4.166                  <dd>If this <a>transaction</a> has already been committed or aborted.</dd>
   4.167                </dl>
   4.168              </dd>
     5.1 --- a/Speclet_023_IDB_API_Asynchronous_APIs.html	Mon Oct 25 11:08:37 2010 -0700
     5.2 +++ b/Speclet_023_IDB_API_Asynchronous_APIs.html	Fri Oct 29 09:13:37 2010 -0700
     5.3 @@ -211,9 +211,9 @@
     5.4              <dd>This state indicates that a result to a previous request is available in
     5.5              the <a class="idlType" href="#widl-IDBRequest-result"><code>result</code></a> attribute.</dd>
     5.6              <dt>readonly attribute unsigned short readyState</dt>
     5.7 -            <dd>Every request starts in the 
     5.8 -            <a class="idlType" href="#widl-IDBRequest-LOADING"><code>LOADING</code></a> state.
     5.9 -            When either the request completes or fails, the state changes to 
    5.10 +            <dd>When the <a title="request done">done</a> flag is false, returns
    5.11 +            <a class="idlType" href="#widl-IDBRequest-LOADING"><code>LOADING</code></a>,
    5.12 +            otherwise returns
    5.13              <a class="idlType" href="#widl-IDBRequest-DONE"><code>DONE</code></a>.</dd>
    5.14              <dt>attribute Function onsuccess</dt>
    5.15              <dd>The event handler for the <a title="event-success">success event</a></dd>
    5.16 @@ -243,7 +243,15 @@
    5.17              <code>error</code>, with no namespace, which does not bubble, is 
    5.18              not cancelable at each <a class="externalDFN"><code>Window</code></a> object.
    5.19            </p>
    5.20 -           
    5.21 +          <p>
    5.22 +            The <a href="#widl-IDBDatabase-setVersion">setVersion</a> function on <a>IDBDatabase</a>
    5.23 +            uses a separate interface for its <a>request</a>s in order to make use of the
    5.24 +            <code>blocked event</a> eaiser.
    5.25 +          </p>
    5.26 +          <dl class="idl" title="interface IDBVersionChangeRequest : IDBRequest"> 
    5.27 +            <dt>attribute Function onblocked</dt>
    5.28 +            <dd>The event handler for the <code>blocked event</code></dd>
    5.29 +          </dl>
    5.30            <p>
    5.31              The <span>task source</span> for these tasks is the 
    5.32              <dfn id="database-access-task-source">database access task source</dfn>.
    5.33 @@ -335,54 +343,36 @@
    5.34              <dt>IDBRequest open()</dt>
    5.35              <dd>
    5.36                <p>
    5.37 -                This method returns immediately and runs the
    5.38 -                following steps in a different thread.
    5.39 -                If an error occurs while the <a>database</a> <a>connection</a> 
    5.40 -                is being opened, then an
    5.41 -                <a title="event-error">error event</a> is fired on this method's
    5.42 -                returned object with its 
    5.43 -                <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set
    5.44 -                to <a class="idlType" href="#widl-IDBDatabaseException-UNKNOWN_ERR"><code>UNKNOWN_ERR</code></a>
    5.45 -                and a suitable 
    5.46 -                <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>.
    5.47 +                When invoked, this method creates an <a>IDBRequest</a> and returns it.
    5.48 +                It then asynchronously runs the <a>steps for opening a database</a>.
    5.49 +                Let <var>origin</var> be the origin of the <a>IDBEnvironment</a> used to access
    5.50 +                this <a>IDBFactory</a>, <var>name</var> be the <var>name</var> argument passed
    5.51 +                to the function and <var>request</var> be the created <a>IDBRequest</a>.
    5.52                </p>
    5.53 -    
    5.54 -              <ol>
    5.55 -                <li>
    5.56 -                  Let <var>origin</var> be the origin of the active document 
    5.57 -                  from which the method was invoked.                
    5.58 -                </li>
    5.59 -                <li>
    5.60 -                  Perform the <a>steps for opening a database</a>, with 
    5.61 -                  <var>origin</var>, the <var>name</var> parameter and 
    5.62 -                  <var>description</var> parameter, and call its result as 
    5.63 -                  <var>result</var>.
    5.64 -                </li>
    5.65 -                <li>
    5.66 -                  If the steps were aborted with an error code, then set this 
    5.67 -                  request's <a class="idlType" href="#widl-IDBRequest-error"><code>error</code></a> with that 
    5.68 -                  code and abort these steps.
    5.69 -                </li>
    5.70 -                <li>
    5.71 -                  Create a <a><code>IDBDatabase</code></a> object for <var>result</var>
    5.72 -                  and call it <var>db</var>.
    5.73 -                </li>
    5.74 -                <li>
    5.75 -                  Fire a <a title="event-success">success event</a> on this 
    5.76 -                  method's returned object using the <a><code>IDBSuccessEvent</code></a> interface with its 
    5.77 -                  <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> 
    5.78 -                  set to <var>db</var>.
    5.79 -              </ol>              
    5.80 +              <p>
    5.81 +                The <var>description</var> argument is intentionally ignored. The implementation MAY
    5.82 +                use it to improve UI if so desired.
    5.83 +              </p>
    5.84 +              <p>
    5.85 +                If an error is returned from the steps above, then the implementation MUST
    5.86 +                fire an <a title="event-error">error event</a> on the <a>IDBRequest</a> returned from
    5.87 +                this method, with its 
    5.88 +                <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a>
    5.89 +                and <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a> set to
    5.90 +                appropriate values for the error.
    5.91 +              </p>
    5.92 +              <p>
    5.93 +                If the steps above are successful, the implementation MUST fire a <a title="event-success">success event</a>
    5.94 +                on the <a>IDBRequest</a> returned above. The event MUST use the <a><code>IDBSuccessEvent</code></a> interface with its 
    5.95 +                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> 
    5.96 +                set to the <var>result</var> returned from the steps.
    5.97 +              </p>
    5.98                <dl class="parameters">
    5.99                  <dt>DOMString name</dt>
   5.100                  <dd>The <a title="database name">name</a> for the <a>database</a></dd>
   5.101                  <dt>optional DOMString description</dt>
   5.102                  <dd>The description for the <a>database</a></dd>
   5.103                </dl>
   5.104 -              <dl class="exception" title="IDBDatabaseException">
   5.105 -                <dt>NON_TRANSIENT_ERR</dt>
   5.106 -                <dd>if the <var>name</var> parameter is not <a>valid</a></dd>
   5.107 -              </dl>
   5.108              </dd>
   5.109            </dl>
   5.110          </section>
   5.111 @@ -470,31 +460,34 @@
   5.112                  case-sensitive manner, in the  <a title="connection">connected</a> <a>database</a>.</dd>
   5.113                </dl>
   5.114              </dd>
   5.115 -            <dt>IDBRequest setVersion()</dt>
   5.116 +            <dt>IDBVersionChangeRequest setVersion()</dt>
   5.117              <dd>
   5.118 -              This method returns immediately and sets the <a>version</a> of the 
   5.119 -              <a title="connection">connected</a> <a>database</a> by following the
   5.120 -              <a>steps for running a <code>VERSION_CHANGE</code> transaction</a>. 
   5.121 +              This method updates the <a>version</a> of the <a>database</a> by following the
   5.122 +              <a>steps for running a <code>VERSION_CHANGE</code> transaction</a> using
   5.123 +              the <var>version</var> argument as <var>version</var> and the <a>IDBDatabase</a>
   5.124 +              this function was called on as <var>connection</var>. Return the <a>IDBVersionChangeRequest</a>
   5.125 +              returned by those steps.
   5.126                <dl class="parameters">
   5.127                  <dt>[TreatNullAs=EmptyString] DOMString      version</dt>
   5.128                  <dd>The <a>version</a> to store in the <a>database</a></dd>
   5.129                </dl>
   5.130              </dd>
   5.131              <dt>IDBTransaction transaction()</dt>
   5.132 -            <dd> This method returns an <a><code>IDBTransaction</code></a> object immediately and 
   5.133 -              performs the <a title="create a static transaction">steps for creating a transaction</a> with either the list of 
   5.134 -              <a>object store</a> <a title="object store name">names</a>
   5.135 -              for acquiring locks required in this <a>transaction</a> or the 
   5.136 -              global flag set to true, and an optional timeout duration. The global flag is set only if 
   5.137 -              the list is either empty, not passed or passed as  <code>null</code>. If reserving all the 
   5.138 -              <a>object store</a>s identified in the requested <a>scope</a>
   5.139 -              takes longer than the specified timeout interval, then an
   5.140 -              <a title="event-timeout">timeout event</a> is fired on this method's
   5.141 -              returned object with its 
   5.142 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   5.143 -              <a class="idlType" href="#widl-IDBDatabaseException-TIMEOUT_ERR"><code>TIMEOUT_ERR</code></a>
   5.144 -              and a suitable 
   5.145 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>.
   5.146 +            <dd>
   5.147 +              <p>
   5.148 +                This method, when called MUST execute the
   5.149 +                <a title="create a static transaction">steps for creating a transaction</a> in a asychronous
   5.150 +                fashion. If the <var>storeNames</var> argument is provided and non-empty then then use that
   5.151 +                list as the <var>names</var> argument. Otherwise use the full set of <a>object store</a>
   5.152 +                names for the <a>IDBDatabase</a> as <var>names</var> argument. The <var>mode<var> and
   5.153 +                <var>timeout</var> arguments are forwarded to the algorithm as-is. The <var>connection</var>
   5.154 +                argument is set to the <a>IDBDatabase</a> that the <code>transaction()</code> method was
   5.155 +                called on.
   5.156 +              </p>
   5.157 +              <p>
   5.158 +                The method returns a <a>IDBTransaction</a> object representing the <a>transaction</a>
   5.159 +                returned by the steps above</a>.
   5.160 +              </p>
   5.161                <dl class="parameters">
   5.162                  <dt>optional DOMStringList storeNames</dt>
   5.163                  <dd>The names of <a title="object store">object stores</a> and 
   5.164 @@ -511,11 +504,10 @@
   5.165                  is user agent specific</dd>
   5.166                </dl>
   5.167                <dl class="exception" title="IDBDatabaseException">
   5.168 -                <dt>TIMEOUT_ERR</dt>
   5.169 -                <dd>The required locks could not be acquired in the given timeout interval</dd>
   5.170                  <dt>NOT_ALLOWED_ERR</dt>
   5.171 -                <dd>The <code>close()</code> method has been called on this IDBDatabase instance and
   5.172 -                its internal <code>closePending</code> flag is set.</dd>
   5.173 +                <dd>The close() method has been called on this <a>IDBDatabase</a> instance.</dd>
   5.174 +                <dt>NOT_FOUND_ERR</dt>
   5.175 +                <dd>One of the names provided in the <var>storeNames</var> argument doesn't exist in this <a>database</a>.</dd>
   5.176                </dl>
   5.177              </dd>
   5.178              <dt>void close()</dt>
   5.179 @@ -749,10 +741,13 @@
   5.180              </dd>
   5.181              <dt>IDBIndex index()</dt>
   5.182              <dd>
   5.183 -              <p>
   5.184 -                This method returns immediately and opens the <a>index</a> with the
   5.185 -                given name in the <a title="connection">connected</a> <a>database</a>.
   5.186 -              </p>              
   5.187 +              Returns a <a>IDBIndex</a> representing a <a>index</a> that is part of the
   5.188 +              to this <a>object store</a>. Every call to this function on the same
   5.189 +              <a>IDBObjectStore</a> instance and with the same <var>name</var> returns the same <a>IDBIndex</a> instance.
   5.190 +              However the retured <a>IDBIndex</a> instance is specific to this <a>IDBObjectStore</a> instance. If this
   5.191 +              function is called on a different <a>IDBObjectStore</a> instance, a different <a>IDBIndex</a> instance is
   5.192 +              returned. A result of this is that different <a>IDBTransaction</a>s use different <a>IDBIndex</a> instances
   5.193 +              to represent the same <a>index</a>.
   5.194                <dl class="parameters">
   5.195                  <dt>DOMString name</dt>
   5.196                  <dd>The <a title="index name">name</a> of an existing <a>index</a></dd>
   5.197 @@ -1057,8 +1052,11 @@
   5.198              </dd>
   5.199              <dt>IDBObjectStore objectStore()</dt>
   5.200              <dd>
   5.201 -              Immediately returns the object store that has been already added 
   5.202 -              to the <a>scope</a> of this <a>transaction</a>. 
   5.203 +              Returns a <a>IDBObjectStore</a> representing a <a>object store</a> that is part of the
   5.204 +              to the <a>scope</a> of this <a>transaction</a>. Every call to this function on the same
   5.205 +              <a>IDBTransaction</a> instance and with the same <var>name</var> returns the same <a>IDBObjectStore</a> instance.
   5.206 +              However the retured <a>IDBObjectStore</a> instance is specific to this <a>IDBTransaction</a>. If this
   5.207 +              function is called on a different <a>IDBTransaction</a>, a different <a>IDBObjectStore</a> instance is returned.
   5.208                <dl class="parameters">
   5.209                  <dt>DOMString name</dt>
   5.210                  <dd>The requested <a>object store</a></dd>
   5.211 @@ -1073,15 +1071,13 @@
   5.212              </dd>
   5.213              <dt>void abort()</dt>
   5.214              <dd>
   5.215 -              This method returns immediately and undoes all the changes performed to 
   5.216 -              the <a>objects</a> of this <a>database</a> in this <a>transaction</a>. If this <a>transaction</a> 
   5.217 -              has already been committed or aborted,  then an
   5.218 -              <a title="event-error">error event</a> is fired on this method's
   5.219 -              returned object with its 
   5.220 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   5.221 -              <a class="idlType" href="#widl-IDBDatabaseException-NON_TRANSIENT_ERR"><code>NON_TRANSIENT_ERR</code></a>
   5.222 -              and a suitable 
   5.223 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>.
   5.224 +              If this <a>transaction</a> is <a title="transaction finish">finished</a>, throw a NOT_ALLOWED_ERR
   5.225 +              exception. Otherwise this method <a title="transaction abort">aborts</a> the transaction by running the
   5.226 +              <a>steps to abort a transaction</a> with <var>code</var> set to ABORT_ERR.
   5.227 +              <dl class="exception" title="IDBDatabaseException">
   5.228 +                <dt>NOT_ALLOWED_ERR</dt>
   5.229 +                <dd>If this <a>transaction</a> has already been committed or aborted.</dd>
   5.230 +              </dl>
   5.231              </dd>
   5.232              <dt>attribute Function onabort</dt>
   5.233              <dd>The event handler for the <a>onabort</a> event.</dd>