[jdom-interest] Ideas for API changes

[Amy Lewis]

On Sun, Apr 29, 2001 at 02:17:35PM -0700, Jason Hunter wrote:
>> I'm not sure there needs to be more than that. I think having the 
>> common type alone because it really strengthens type checking 
>> throughout the API and makes a lot of code simpler. For instance, in 
>> addContent() we no longer need to check for seven different types at 
>> runtime before adding the object. All the checks can be performed at 
>> compile time. I don't know that this would be significantly faster, 
>> but it would be conceptually much simpler.
>
>Node does not take care of this issue!  You removed from your message my
>discussion of the problem.  Having node *weakens* type checking.

No, bad APIs do.

>If Element had an addContent(Node) and Document implemented Node then an
>Element could add a Document.  Similarly, if Document has an
>addContent(Node) then Document could add more than one element, Document
>could add Entity objects which don't belong at the Document level. 
>Heck, Documents could add Documents.  

*Why* in the name of all the forest gods would you put addContent() on
the Node interface?  addContent(Node) works quite nicely for Element,
as long as Document is special-cased, which it probably ought to be
anyway (it isn't a Node, really, it's a bag in which the root node is
contained).

Which raises the point that Doctype and Entity are probably not Nodes,
either.

>So that means with everything accepting Node is we'd still have to do
>lots of runtime checks because not all Nodes are created equal.  I
>prefer having the compiler do the checks.  Better to catch errors at
>compile time than runtime.  Plus it makes clear to people that Document
>only accepts certain types of objects, Element only accepts certain
>types, etc.
>
>Also, taking a Node interface parameter isn't really safer than taking
>Object because I could still write MyStupidClass implements Node (but
>nothing else) and have it added to any Element even though it's not
>related to XML.  How would you catch that?  By doing exhaustive runtime
>checking within the method?  By just letting this mysterious object be
>added?

Oh, *give* me the damned knife!  If I cut myself, it's *my* problem! 
Yes, if the simple Node interface were to be defined, then any subclass
(no matter how stupid) should be accepted wherever Node is accepted.

The best use case I can think of for this is the mostly-uncontroversial
use of String as a JDOM 'node' type.  I might very well want to write a
handler to generate Text (implements Node) instead, because it solves
some problems (such as walking over a list of things returned as a node
set).

>Another thing:  if Node has getParent() then now Document would have a
>getParent() and that doesn't make much sense.  Methods that don't make
>much sense is one of the largest problems with DOM.

True if Document is a Node, which I am increasingly uncertain of. 
However, this does imply that getParent() should return something that
can be either a Node or a document, if you want to implement a
getDocument() that relies on walking getParent() up the tree.

>More issues: Is DocType a Node?  If so, then Elements could also add
>DocTypes to themselves.
>
>It sounds simple.  It's not.  Even with Node I believe you'd still want
>addContent() to take specific items.  So that advantage is thrown out.

I'd challenge this; I think it may have more to do with carefully
defining which classes actually implement Node.  *Must* Document be a
Node, or is there a better way?  Having the main working classes
(Element, Attribute, PI, Comment) as Nodes does have advantages, I
think.

Amy!
-- 
Amelia A. Lewis          alicorn at mindspring.com          amyzing at talsever.com
The one thing you can't trade for your heart's desire is your heart.
		-- Miles Vorkosigan