Indexed Database API Proposed Recommendation Published
From the post:
The Web Applications Working Group has published a Proposed Recommendation of Indexed Database API. This document defines APIs for a database of records holding simple values and hierarchical objects. Each record consists of a key and some value. Moreover, the database maintains indexes over records it stores. An application developer directly uses an API to locate records either by their key or by using an index. A query language can be layered on this API. An indexed database can be implemented using a persistent B-tree data structure. Comments are welcome through 18 December. Learn more about the Rich Web Client Activity.
If you have the time between now and 18 December, this is a great opportunity to “get your feet wet” reviewing W3C recommendations.
The Indexed Database API document isn’t long (43 pages approximately) and you are no doubt already familiar with databases in general.
An example to get you started:
3.2 APIs
The API methods return without blocking the calling thread. All asynchronous operations immediately return an IDBRequest instance. This object does not initially contain any information about the result of the operation. Once information becomes available, an event is fired on the request and the information becomes available through the properties of the IDBRequest instance.
- When you read:
The API methods return without blocking the calling thread.
How do you answer the question: What is being returned by an API method?
-
What is your answer after reading the next sentence?
All asynchronous operations immediately return an IDBRequest instance.
- Does this work?
API methods return an IDBRequest instance without blocking the calling thread.
(Also correcting the unnecessary definite article “The.”)
- One more issue with the first sentence is:
…without blocking the calling thread.
If you search the document, there is no other mention of calling threads.
I suspect this is unnecessary and would ask for its removal.
So, revised the first sentence would read:
API methods return an IDBRequest instance.
- Maybe, except that the second sentence says “All asynchronous operations….”
When you see a statement of “All …. operations…,” you should look for a definition of those operations.
I have looked and while “asynchronous” is used thirty-four (34) times, “asynchronous operations” is used only once.
(more comments on “asynchronous” below)
I am guessing you caught the “immediately” problem on your own. Undefined and what other response would there be?
If we don’t need “asynchronous” and the first sentence is incomplete, is this a good suggestion for 3.2 APIs?
(Proposed Edit)
3.2 APIs
API methods return an IDBRequest instance. This object does not initially contain any information about the result of the operation. Once information becomes available, an event is fired on the request and the information becomes available through the properties of the IDBRequest instance.
There, your first edit to a W3C Recommendation removed twelve (12) words and made the text clearer.
Plus there are the other thirty-three (33) instances of “asynchronous” to investigate.
Not bad for your first effort!
After looking around the rest of the proposed recommendation, I suspect that “asynchronous” is used to mean that results and requests can arrive and be processed in any order (except for some cases of overlapping scope of operations). It’s simpler just to say that once and not go about talking about “asynchronous requests,” “opening databases asynchronously,” etc.