[jdom-interest] getChild() vs. getChildElements()

[Brett McLaughlin]

Joerg wrote:
> 
> Hi everybody,
> 
> I am new to this list and was just digging through the list archives
> trying to get a picture of the development of the JDOM API. I was also
> following the unfortunate discussion about the naming of the getChild()
> or getChildElement() methods. When I stumbled over JDOM, the first thing
> 
> I was lucky about to see was the simple structure and naming of the API.

I'm sure if you read the XML spec at all, you also noticed the erroneous
nature of many of the names.

<small-rant>
I can't believe we are still arguing this facet of this thread. I don't
mind that people are still arguing over the name of the method. I just
can't believe that people won't read the specs and admit that an Element
is <i>not</i> the only type of child an Element can have! Argggh!!
People, at least read the specifications, and argue (if you must) that
we are simplifying the spec, and admit it's not a conformant name. That,
at least, is honest!
</small-rant>

OK, now I'm back ;-)

> 
> Once we made our own DOM implementation for a special purpose, added a
> few 'special Java' functions (for example getChilds() :-) ) and
> developed a DOM wrapper from this, because the standard DOM methods are
> more or less unusable. This wrapper simplifies the access to the
> document for a (very common) subset of XML-Documents. For example we
> trimmed away all dangling whitespace and normalized multiple text nodes
> already in the DocumentHandler of the SAX parser. For our purposes it is

Trimming dangling whitespace is another non-XML-conformant issue. For
your purposes that's fine, but certainly you aren't advocating that in
JDOM, right? We really, really went through this.

Folks, I understand that you want JDOM really simple for /your/
use-case. However, JDOM isn't for /your/ use-case, it is for simple
manipulation of XML in Java. However, that doesn't mean "simple
manipulation of the most common features of XML" because everyone sees
common differently. It doesn't mean "an API that uses almost-XML to help
you out," either. We say we are Java + XML. Therefore, we must be
XML-conformant. To abandon that will mean we won't ever be standardized,
we won't ever be widespread, which more or less means that folks like
Jason and I won't be able to keep working on it (as opposed to things
that are more realistic), and it will die, or become a glitch in the
system ;-) So understand that we /must/ at least attempt to support the
basic tenets of XML. Not DOM, not SAX, but XML itself. We aren't talking
even about functionality loss, here, but a method name! I can't believe
people are honestly arguing that a longer method name /complicates/ the
API! That's false - it clarifies the API (nobody can argue that), and it
may make the API longer to type, but by nature, a no-functionality
change cannot /complicate/ an API, if the name assists in
/clarification/, even when none is needed. That's just logical, folks
;-)

> 
> e.g. of no interest to call getContent() for a non-leaf Element. Our
> method even returns 'null', when called on a non-leaf Element.
> Furthermore our getChilds() method returns only Element nodes (as an
> Enumeration, a List is better but we had nothing else then) to avoid all
> 
> the nerve-racking 'instanceof' or getNodeType() checks.
> 
> What I mean is, we 'declared' a special case in the usage of XML to our
> general case. An XML Document is in that case a tree of Elements, which

And that's great. If you want that, you are welcome to subclass JDOM and
call it "myJDOM" or something. But you special case is not my special
case. And so on - we can't impose our special cases on other users when
not all those users want that special case.

> can have values. This view of an XML document is very common for
> problems in which you have to manipulate deep data structures, which
> form the vast majority of problems outside the area of traditional
> document management. In our case it is explicitly defined, that you work

I don't agree. I wrote a complete set of data binding classes that, in
total, calls getChildren() one time. Period. Over 5,000 lines of code,
more or less, and one call to getChild(). It's just not a valid argument
that XML has a "vast majority" - the whole point of XML is to allow any
use, which is going to result in lots of crazy uses, even minimally. Add
up all the minimal weird cases, and you approach the number of "normal
cases", so vast majority is lost. I just want to continually emphasize
that we can simplify accessing XML - that's great. But we can't cut
things out because we presume that our use-cases are normal and others
aren't.

> 
> only with Elements when you navigate on the tree. So it is not necessary
> 
> there to say 'getChildElement()' or 'getChildElements()', this would be
> a steady repetition of a meaningless statement, because we don't deal
> with other Nodes than Elements. So we named our methods getChild() and
> getChilds(), which says everything necessary, namely that you want to
> have one or all childs (not the parent and not the siblings) of a given
> Element, which are, as always, also Elements.

In your case, that is a valid desire - of course, you are completely
ignoring entities, which I would maintain are in the "normal" use-case,
as you put it. XMLC uses them, which want to move to JDOM. Am I going to
block that effort? No way ;-)

> 
> In JDOM, as I understood, the situation is even much more clear than in
> our DOM wrapper. Here, not everything is based on a Node, so the only
> potential tree-building class is Element. And text is mainly a value of

Wrong. Parsed entities:

<root>
  &parsed;
  <empty />
</root>

may expand to:

<root>
  <copyright>
    This was developed in <b>2000</b>.
  </copyright>
  <empty />
</root>

Depending on when the entity is parsed and expanded, there is no clear
definition of what the child is. Is it the entity? Is it a set of
Elements that the parsed entity converts to? Is it just the empty
element? Is it all? or None? In this case, getChildren() is completely
ambiguous, as is both getChild(parsed) and getChild(copyright). And
based on when the document is accessed, there may be no way of telling
that the parsed entity (the copyright and enclosed character data) is
even an entity at all! So getChildren() is returning potentially
misleading data. This is clearly a case where getChildElement/s() does
the right thing, and clearly gives you only the empty element, which is
both correct and easy to understand. There is no potential for foul-ups
with that approach.

> an Element (All people, who want to use XML in a different manner, can
> use getMixedContent() or DOM directly). This is a basic goal of JDOM, so

or DOM directly? What? Are you really saying that if you want more than
child elements, you should use DOM? That's not our goal at all. You
presume too much about what we want to accomplish here.

> 
> I don't understand this discussion at all, why the nice simplicity of
> JDOM should be sacrificed a foggy 'standards compliance'. JDOM is JDOM,

Uggh... it's not more complex to call getChildElements() than get
Child(). I can't believe this is in contention - it may be less
convenient, or more annoying, for some, but it is a fallacy to say it
complicates the API. And foggy 'standards compliance', as you put it, is
what is getting us into the JDK if things go well. So don't knock it ;-)
Lack of standards compliance will get you nowhere. Even deviations from
standards, like XMLC instead of JSP, are based on a lower level of
standards (XML and servlets), or Cocoon (XML and XSLT). Standards are
the reason that Java and XML run on multiple platforms. You take that
ability away, and you cut all uses of JDOM for anything but
inter-application use, as the XML resulting can't be sent to other
fully-XML-conformant handler APIs, many times. You also elimintate the
ability to accept XML that is not the "simpler subset" form you can deal
with. It just doesn't make sense.

> it has its specialized purpose and its clear basic definitions (you
> should have no other nodes than Elements, folks). This argument of the

What? You're a little nuts here - no Attribute? Wow... I simply don't
think JDOM is right for you... it may work for you, but we will not
simplify to that degree.

> confused JDOM beginners which only know the DOM specification is a
> little bit far-fetched. When someone starts reading about JDOM it is

You haven't read the XML specification either, though, it sounds like.
And the XML spec is not that tough! It's clear where JDOM is deficient,
and we are going to try to resolve those areas.

> very soon absolutely clear what is its intention and what is the
> difference to standard DOM. And if not then it is necessary to emphasize
> 
> this point, but not to change the API because of this.
> 
> The first time, I was first a little bit confused when I saw the class
> diagram because I was missing, what, the Node class of course. But then
> I thought: "hey are these people really thinking about what you really
> want to DO with an XML document and not only about what is in a certain
> way formally consistent?". I understand it, for example, not as yet why
> someone had the idea to tie a DOM node to a specific document. These
> 0.1% of the cases where it would be nice to get directly the Document,
> containing the node, really don't justify all that increasing of entropy
> 
> when all the computers perform all these unneccessary cloneNode()
> operations, while they are merging or transforming XML documents. O.K.,
> I could imagine that Elements with the same name can have a different
> purpose in different DTD's or that the meaning of an Element is somehow
> bound to the document it is part of. But I'm a little bit
> digressing from the subject.
> 
> For my (of course personal) opinion JDOM should be specialized in its
> intention and consequent in the optimization for that special purpose.

Which decreases our usability, which decreases our user base, which
decreases the effort put into it... 

> This does not imply, that it is not standards compliant, because there
> are all these special functions with which you can do everything else,
> the standard requires (for me it would be perfect even without that but,
> 
> who knows, one day I will need them, too). Everything else will bring
> JDOM in the direction of DOM and this is definetly the wrong direction.

There is no possibility that we are ever moving towards DOM, and even a
cursory inspection of JDOM shows that. Ask Arnaud LeHors on the DOM
working group how close JDOM is to DOM - he'll laugh you out of the room
;-)

> Therefore the often mentioned 'default' in the
> naming should reflect this what is used most often in the area, JDOM is
> explicitly addressing (manipulating XML data structures with Java). And
> this naming should be short, significant and free of repetitions (like
> it is more or less now). Everything else is wasting resources (time,
> nerves and entropy) like DOM is doing.

Time? Nerves? Entropy? I'm amazed at the amount of energy you must be
spending on those extra 8 or so characters! ;-)

> 
> All I can do now is waiting, hoping that JDOM continues this promising
> way it started, that we can silently bury our own DOM wrapper (in
> honour, of course), because its major drawback is (apart from the owner
> document reference, which I cannot get rid of) that it not automaticly
> follows the evolving of the standards. Otherwise I have to implement
> proper namespace support soon (ahrrrg... some fearless hero has to do
> such things, but I'm through with implementing DOM features for some
> time).

But namespaces are not needed, and can just be ignored, right? I mean,
that's what you are implying - if you don't need it, just trash it. I
don't get your reasoning here, it is contrary to the entire rest of your
email!

> 
> But, joking apart, I have the impression that JDOM can get a cool
> standard, because of its clear and useful design approach and the

I'm really confused now ;-_ We should'nt follow standards, but we should
be a standard - how does that work ;-)

-Brett

> competence and influence, which is assembled here.
> 
> If you are here then you probably read all the stuff before, so thanks
> for your time.
> 
> Joerg
> 
> --
> <?xml version="1.0" standalone="no" encoding="ISO-8859-1"?>
> <businesscard>
>   <bookmarks>
>     <bookmark> http://www.google.com </bookmark>
>     <bookmark> http://www.gnu.org </bookmark>
>     <bookmark> http://java.apache.org </bookmark>
>     <bookmark> http://www.w3.org </bookmark>
>     <bookmark> http://www-db.stanford.edu/lore </bookmark>
>   </bookmarks>
>   <sender>
>     <firstname> Jörg </firstname>
>     <name> Kirchhof </name>
>     <title> Dipl.-Ing. </title>
>     <email> joerg at freiheit.com </email>
>     <phone> +49-40-890584-14 </phone>
>   </sender>
>   <company>
>     <name> freiheit.com Technologieberatung GmbH </name>
>     <address> Theodorstraße 42-90 </address>
>     <zip> 22761 </zip>
>     <city> Hamburg </city>
>     <country> Germany </country>
>     <phone> +49-40-890584-0 </phone>
>     <fax> +49-40-890584-20 </fax>
>     <www> http://www.freiheit.com </www>
>   </company>
> </businesscard>
> 
> _______________________________________________
> To control your jdom-interest membership:
> http://lists.denveronline.net/mailman/options/jdom-interest/youraddr@yourhost.com

-- 
Brett McLaughlin, Enhydra Strategist
Lutris Technologies, Inc. 
1200 Pacific Avenue, Suite 300 
Santa Cruz, CA 95060 USA 
http://www.lutris.com
http://www.enhydra.org