Modules for IDL fragments in W3C specifications (was: Re: An import statement for Web IDL)

Cameron McCormack:
> I don’t know how important it is to keep the HTML interfaces in the
> org.w3c.dom.html package, but it definitely seems important to keep
> DOM Core and Events interfaces in org.w3c.dom and org.w3c.dom.events.

Ian Hickson:
> Why? How does it affect black-box compliance of Web-relevant 
> implementations of those drafts?

Maciej Stachowiak:
> It seems to me that there is some benefit to making Java implementations 
> of a Web IDL based DOM Core mostly source compatible with existing Java 
> DOM bindings. And the cost is low.

I agree.  I also agree that such source compatibility isn’t strictly
“web relevant”, but published OMG IDL fragments for DOM specifications
are being used for non-web situations, and I don’t want to make Web IDL
and the specifications we write useless for those situations if I can
help it and the cost isn’t too great.

> I think letting a spec declare a module in one place in prose without  
> wrapping all fragments in a module {} declaration could achieve this  
> with minimum burden to spec authors.

That’s do-able; perhaps there could be some wording in the HTML 5 spec
like:

  Conforming HTML 5 implementations [or whatever conformance class is
  appropriate] must be conforming ECMAScript implementations of an IDL
  fragment constructed by concatenating the string "module html {",
  the text of all of the IDL boxes in this specification and the string
  "};".

It makes it harder for tools that compile IDL fragments into Java
interfaces, though, since then a human has to extract the package name
requirement out of the spec text manually — I could see that as being
a violation of
http://www.w3.org/TR/html-design-principles/#priority-of-constituencies.


As for how we (spec writers) should be dealing with modules in the IDL
we write, I think the current division of interfaces among modules
(which is basically one module per spec) isn’t that useful.  Authors of
W3C specifications should know what other interfaces exist and not clash
with them.  This is especially true because of the fact that ES
interface objects all go on the global object (modulo the newly
introduced [NamespaceObject] extended attribute).  Having a module
declaration in the IDL does make it easier to hang some extended
attribute off to specify the Java package (if you can’t determine it
from the module name).  And I am all for non-W3C specifications having
to use modules, to keep out of the namespace of interfaces defined by
W3C specs.

With that in mind, here is a mostly concrete proposal:

  * All W3C specs will place interfaces and exceptions at the top level
    scope (i.e., not in a module).

  * Definitions at the top level scope will be placed into the
    org.w3c.dom Java package unless overridden somehow.

  * Certain other specs, such as DOM Events, will place interfaces/
    exceptions in a different Java package, not by using a module
    with a [Prefix] or [JavaPackage], but by some other mechanism
    (perhaps in spec prose).  By keeping definitions at the top level
    scope, it will make it easier for other specs to reference them,
    since they won’t need to use typedefs or scoped names like
    events::EventTarget.  (As mentioned in a previous mail, I think
    we will have to rewrite/republish IDL fragments from DOM specs
    anyway, so we can do this module changing at the same time.)

  * We will encourage authors of non-W3C specifications to place
    definitions in a module.  An extended attribute (or the extra-IDL
    mechanism mentioned in the previous point) can be used to make
    that module correspond to an appropriately named Java package.

-- 
Cameron McCormack ≝ http://mcc.id.au/

Received on Friday, 3 July 2009 06:25:04 UTC