Hi Josh. Thanks for the feedback. Moving forward, I will track changes and resolution of these suggestions in bug 9379 [1].
Appreciate the time you've spent on this. Eliot [1] http://www.w3.org/Bugs/Public/show_bug.cgi?id=9739 > -----Original Message----- > From: public-webapps-requ...@w3.org [mailto:public-webapps- > requ...@w3.org] On Behalf Of timeless > Sent: Tuesday, April 12, 2011 12:32 AM > To: Arthur Barstow > Cc: public-webapps > Subject: Re: publish new Working Draft of Indexed Database API; deadline > April 16 > > On Sat, Apr 9, 2011 at 2:22 PM, Arthur Barstow <art.bars...@nokia.com> > wrote: > > http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html > > I expect this message to only have editorial comments. However, I'm not > fond of April 16th, this month is tax month and I still need to file. > > > Transaction > > A transaction is used to interact with the data in a database. > > Whenever data is read or written to the database this is done using a > transaction. > > maybe s/this/it/ > > > All transactions are created using a connection, > > I don't like "using", perhaps "from"? -- I haven't gotten to the API yet. > I'm also uncertain about 'a connection' vs. 'connections' > > > which is the transactions connection. > > s/transactions/transaction's/ > > > The transaction has a mode which determines which types of > > interactions can be performed using the transaction. > > s/using the transaction/upon it/ ? -- "The transaction" also started the > sentence. > > > The mode is set when the transaction is created and remains constant > > for the > > s/constant/fixed/ > > > lifetime of the transaction. > > s/lifetime/life/ > > > The transaction also has a scope which determines which object stores > > the transaction can interact with. > > s/which.*with/the object stores with which the transaction may interact/. > > > Finally, transactions have a active flag, > > s/ a / an / > s/Finally, t/T/ -- It isn't Finally -- Finally is used again in the next > sentence. > > > which determines if new requests can currently be placed against the > transaction. > > The prose here implies that this is mutable, it's also awkward (probably he > use of 'currently'). > > > Finally, transactions also contain a request list of requests which have > > been > placed against the transaction. > > It seems that <placed> is treated as technical language, I'd expect it to be > defined somewhere (or globally replaced by 'made'). > > > Transactions have a constant scope which is determined when the > > transaction is created and remains constant for the lifetime of the > transaction. > > Each transaction has a fixed scope determined at creation time. > > > Transactions offer some protection from application and system failures. > > > A transaction represents an atomic and durable set of data access and > mutation operations. > > I know that data can be uncountable or plural, but I'm unsure that 'access' > fits with its use here -- should it be 'accesses'? > > > This is encouraged using the automatically committing functionality > described below. > > s/using the automatically/by the automatic/ > > > Authors can still cause transactions to run for a long time, however > > this is generally not a usage pattern which is recommended > > s/usage pattern which is recommended/a recommended usage pattern/ > > > and can lead to bad user experience in some implementations. > > possibly <a bad user experience> | <bad user experiences> ? > > > A transaction is created using IDBDatabase.transaction. > > The arguments passed determine what the scope of the transaction is > > s/what//; s/is// > > > and whether it's read only or not. > > whether or not it is read-only. > > > When a transaction is created its active flag is initially set to true. > > > The implementation MUST allow requests to be placed against the > > transaction whenever the active flag is true. > > > This is the case even if the transaction has not yet been started. > > > Until the transaction is started the implementation MUST NOT execute > > these requests, but the implementation MUST still keep track of the > > requests and their order. > > s/, but/;/ > s/still// > > > Requests may only be placed against the transaction > > s/the/a/ > > > while the transaction is active. > > s/the transaction/it/ > > > If a request is attempted to be placed against a transaction when > > I find <request/attempted/placed> awkward, possibly because it lacks an > actor... > > > it is not active, > > I believe <not active> is used here to be the technical state <not <active>>, > perhaps it should be marked up. Otherwise as this is prose, I'd use > <inactive>. > > > the implementation MUST reject the attempt by throwing a > TRANSACTION_INACTIVE_ERR exception. > > Inactive is used in the exception type, it's a valid English word.... > > > Once an implementation is able to enforce the constraints defined for > > the mode of the transaction, > > transaction mode > > > defined below, the implementation MUST asynchronously start the > transaction. > > > When this happens is affected by the mode in which the transaction is > > opened, and which object stores are included in scope of the transaction. > > s/which/the/ > s/are// > s/scope of the transaction/the transaction's scope/ > > > Once the transaction has been started the implementation can start > executing the requests placed against the transaction. > > Unless otherwise defined requests MUST be executed in the order they > > are placed against the transaction. > > s/they/in which they/ > s/are/were/ > > I find <placed> <against> strange. <made> <against> seems to work > Otherwise <placed> <into> > > > Likewise, their result MUST be returned in the order the request was > > placed against a specific transaction. > > <result> appears to be used as a mass noun, but <request> is singular, I'm > pretty sure this doesn't work. > > > There is no guarantee about the order that results from requests in > > different transactions are returned. > > > Similarly, the isolation mode ensure that > > ensures > > > it doesn't matter which order requests placed against different transactions > are executed. > > order of requests placed against different transactions doesn't matter with > respect to execution order. > > I don't like "matter", do you mean 'affect'? > > > At any time a transaction can be aborted, > > A transaction can be aborted at any time, > > > even if the transaction isn't currently active. > > Again, <inactive> would be better. > > > When a transaction is aborted > > When <actor requests to abort a transaction>.... > > -- aborted is the result of the request plus the action taken by the agent > > > the implementation MUST undo (roll back) any changes made to the > > database using the transaction. > > s/using/from|in/ ? > > > This includes both changes to the contents of object stores as well as > > additions and removals of object stores and indexes. > > > A transaction can be aborted at any time before it is finished. Including > > if it > isn't active or hasn't yet started. > > This duplicates text from the beginning of the point and should be folded into > the original statement. > > > Once a transaction no longer can become active, > > s/Once/When/ > s/no longer can/can no longer/ > > > and if the transaction hasn't been aborted, > > Move this to the start of the sentence > > > the implementation MUST automatically attempt to commit it. > > I think <automatically> can be dropped > > > This usually happens after all requests placed against the transaction > > has been executed and their returned results handled, > > s/has/have/ > > > but no new requests has been placed against the transaction. > > s/but/and/ > s/has/have/ > > > When a transaction is committed implementation > > s/committed/committed,/ > > > MUST atomically write any changes to the database made by requests > placed against the transaction. > > > That is, either all of the changes MUST be written, or if an error occurs, > such as a disk write error, the implementation MUST NOT write any of the > changes to the database. > > I think "write ... to the database" isn't ideal here, what we want is for none > of the changes to appear in the database when queried. It's certainly possible > for bits to be written to a portion of the database which is rolled back, but > that's still a "write" in a naive sense. > > > If such an error occurs the implementation > > s/occurs/occurs,/ > > > MUST abort the transaction by following the steps for aborting a > > transaction, otherwise it MUST commit the transaction by following the > > steps for committing a transaction. > > > When a transaction is committed or aborted, it is said to be finished. > > If a transaction can't be finished, for example due to the > > implementation crashing or the user taking some explicit action to > > cancel it, the implementation MUST abort the transaction. > > <abort> here can't mean <take the steps for aborting a transaction> in the > case where the implementation crashes. > > > Transactions are opened in one of three modes. > > The mode determine how concurrent access to > > determines > > > object stores in the transaction is isolated. > > s/is/are/ > > I'm going to stop here, lest my user agent crash and my message fail to be > committed. This appears to be about 1/6th through the document. > It took me a few days to reach this document and I expect to cycle through a > couple of other documents which have CfCs pending, plus I have taxes to do. > Sorry for not getting to this sooner. >