Re: publish new Working Draft of Indexed Database API; deadline April 16

On Sat, Apr 9, 2011 at 2:22 PM, Arthur Barstow <art.barstow@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.

Received on Tuesday, 12 April 2011 07:32:52 UTC