Re: [IndexedDB] Proposal for async API changes

On Thu, May 20, 2010 at 8:19 PM, Jonas Sicking <jonas@sicking.cc> wrote:

> On Thu, May 20, 2010 at 11:55 AM, Shawn Wilsher <sdwilsh@mozilla.com>
> wrote:
> > On 5/20/2010 11:30 AM, Andrei Popescu wrote:
> >>
> >> As someone new to this API, I thought the naming used in the current
> >> draft is somewhat confusing. Consider the following interfaces:
> >>
> >> IndexedDatabase
> >> IndexedDatabaseRequest,
> >> IDBDatabaseRequest,
> >> IDBDatabase,
> >> IDBRequest
> >>
> >> Just by looking at this, it is pretty hard to understand what the
> >> relationship between these interfaces really is and what role do they
> >> play in the API. For instance, I thought that the IDBDatabaseRequest
> >> is some type of Request when, in fact, it isn't a Request at all. It
> >> also isn't immediately obvious what the difference between
> >> IndexedDatabase and IDBDatabase really is, etc.
> >
> > It should be noted that we did not want to rock the boat too much with
> our
> > proposal, so we stuck with the existing names.  I think the current spec
> as
> > written has the same issues.
>
> We kept the existing names specifically to avoid tying bikeshed naming
> discussions to technical discussion about how these interfaces should
> behave :)
>

Totally agree with both of you!  But I think now is as good of a time as any
to discuss these issues (since they apply to both specs).  In this case, I
actually don't think this is really bike shedding since we're all agreeing
the current names are confusing, but I guess the line is fine.  :-)


> >> - I know we need to keep the "IDB" prefix in order to avoid collisions
> >> with other APIs. I would therefore think we should keep the IDB prefix
> >> and make sure all the interfaces start with it (right now they don't).
> >
> > I agree with this.  We should probably file a bug about this.
> >
> >> - The "Request" suffix is now used to denote the asynchronous versions
> >> of the API interfaces. These interfaces aren't actually Requests of
> >> any kind, so I would like to suggest changing this suffix. In fact, if
> >> the primary usage of this API is via its async version, we could even
> >> drop this suffix altogether and just add "Sync" to the synchronous
> >> versions?
> >
> > I agree that Request seems confusing and seems to be contrary to what
> other
> > specs use.  We should try to follow what other specs do here.
>
> Agreed on both accounts. There unfortunately isn't much in the way of
> precedence here. There are three other specs to look at here, which
> specify API for both workers and main thread.
>
> * Web Workers spec
> http://www.whatwg.org/specs/web-workers/current-work/ This spec
> doesn't actually use different interfaces for workers and main thread.
> * File API http://dev.w3.org/2006/webapi/FileAPI/ Specifies FileReader
> and FileReaderSync. The two interfaces are separate and doesn't
> inherit from a common base
> * WebSQLDatabase http://dev.w3.org/html5/webdatabase/ Specifies
> separate interfaces, like Database and DatabaseSync. The two
> interfaces are separate and doesn't inherit from a common base.
>
> I think we should follow the same convention as File API and
> WebSQLDatabase. There really isn't anything to be gained by having a
> common base interface, it just makes the spec harder to read as
> functionality is distributed between the base interface and the
> sync/async interface.
>
> I additionally like the naming convention. The async interfaces is
> probably the interface that people will use first. Additionally that
> interface is available both to workers and to the main thread. So it
> makes sense to give the async interface the simpler name.
>

Agreed on all counts.  I would add that, if we did decide to keep base
interfaces, we could always suffix them with Base (which I think makes it
more clear they're base interfaces)...but it sounds like that might not be
necessary.


> >> - Some of the interfaces could have names that would more closely
> >> reflect their roles in the API. For instance, IDBDatabase could be
> >> renamed to IDBConnection, since in the spec it is described as "a
> >> connection to the database".
>
> Not really sold on this. I've always hated the "connection"
> abstraction. With our suggested API IDBDatabase really just holds
> metadata information about the database, and doesn't need to represent
> a connection at all.
>

Well, if we don't make these proposed changes, then I think it's pretty
important to rename to connection since the current spec does distinguish
between each connection.

With your proposal, this is not currently true, but I think it's hard to say
whether or not these concepts will creep back in in later versions.  In
addition, the entire spec is related to databases, so I think naming it a
"connection" rather than a "database" helps distinguish it from the rest.

That said, if IndexedDatabase* becomes IDBFactory* then there certainly is a
lot less confusion already, and this change is less important.

J