[jdom-interest] META: Children of a lesser spec

[Peter V. Gadjokov]

> What? JDOM is an XML /model/ so how can we possibly ignore 
> what XML says
> about that model? If what JDOM represents is data that is defined by
> this specification, how can we possibly not use this specification to
> model that data? Otherwise, we wouldn't use the term Processing
> Instruction, or XML Declaration, or Doctype. I don't buy this.

I think you may have misunderstood what I wrote. It's a model allright. And
anything these specs say about the model is relevant. They also say an awful
lot about syntax, which is not as relevant - unless it's very closely tied
to the model and you can't hide it. Specs that are specifically and only
about models should be allowed to override whatever syntax specs say about
models. Good API design should be allowed to override whatever any spec says
about model - that is, it should be allowed to represent a different model,
as long as it makes for a better API and is deterministically, and
bidirectionally mappable to the specified model. I didn't say ignore, I said
'not drive API design'. Whatever the API design it must be capable of,
directly or otherwise, expressing the entirety of the core XML model,
whatever spec it is defined in. The syntax stuff, though, should live in
Builders and Outputers, as far as humanly possible. [*]

> M in JDOM doesn't mean anything ;-) 

Waiddaminute, you just said it was a /model/ :) It does mean something, it
must necessarily be a model that is equivalent to (or a mappable superset
of) what the specs talk about AND something that makes sense in Java. For
instance, the entire notion of 'Node' is pretty much a DOM thing - nothing
in, say, the infoset talks about Nodes yet the infoset explicitly states
that DOM is considered infoset compliant. No, I'm not saying lets add Nodes
- but something like JDOM is necessarily a model, potentially a model that
extends/transforms the less expressive models it covers - Java is a far more
expressive model than anything in XML and I think we're in agreement that we
should make use of that, even if we don't have consensus on _how_. 

> Even on these grounds, you will find
> that XML Infoset clearly defines content, and children. 
>

It defines children and occasionally uses the term content, without
specification. The term content comes from the XML spec (a mostly-syntax
spec). Terms defined in other specs are cross-referenced from infoset to
other specs, oddly enough, content is not. That may be intentional or a bug
in the spec, I have no idea - fact is, content is not solidly defined
terminology in Infoset world - the term 'children' is. 

> This simply could not be any clearer - getChild() and  getChildren() are
> absolutely wrong according to this. So again, we are back to either:
> getElement()/getElements()
> or
> getChildElement()/getChildElements()

Yes they are wrong, no argument. They are also better API names. So what's
more important, exact compliance with the spec naming or intuitive element
traversal method names? Perhaps that's the thing we disagree on - I don't
see any of the answers as exceptionally obvious. But some seem more
consistent than others to me. 

> And again, the second is much clearer, particularly when XPath comes
> into play.

Taking getChildElement/getChildElements and going with the infoset
terminology means replacing getContent/addContent and co with
getChildren/addChild. If child is to mean something other than element then
by your own argument (which I agree with) it should mean what it means in
the spec. And nothing is more explicit about what 'child' means than the
infoset. [**]

> It is good to define what specs we should look at. It's also worth 
> noting that even if we disagree on the XML and Namespace spec as 
> being key, the Infoset spec alone has plenty to say on our names.

It certainly does. I may have made a mistake in using the word 'children' in
the subject - I really meant to start a meta-discussion about what specs
should drive core API design. I still stand by:
 Java/OO API considerations/JDOM >= Infoset >= Syntax specs

But I don't mean to imply that '>=' means 'can ignore'. Every time  >= is
not actually an =, it must be done with complete certainty that the
extension is beneficial and allows for a deterministic, clear bidirectional
mapping between he concepts of the superset to those of the subset.

-pvg

[*] This was the gist of my namespace-prefix rant - I thought (and still
think) namespace prefixen can be made a lot less prominent (as they should
be, since they are very much a syntactic feature) in the core API without
compromising the ability to control and use them. The current implementation
is wrong by omission - it does not distinguish between namespace (or
namespace name, in infoset terminology) and namespace declaration. I'll try
to write it up briefly, with XML spec/Infoset terminology and in terms of an
API, in the hopes that it will be more digestible than an 8-page
single-paragraph text overview. 

[**] Incidentally, if we were to become Infoset hardasses, DocType is
apparently a  child of document, unlike the JDOM implementation.