[jdom-interest] Ideas for API changes

[Amy Lewis]

On Sun, Apr 29, 2001 at 03:42:52PM -0500, Brett McLaughlin wrote:
>+1. I also like the type-safety and conceptual advantages of either an Item
>or Node interface. We can debate the name on another thread ;-)
>
>I also like getParent(), which I actually thought we had discussed earlier.
>getDocument() is something that I am -0 on, because I can't think of why I
>might need it, but don't have a reason against it, and trust that Elliotte
>probably does have a reason for it.

To get to the root and find things relatively.  I'm -1 on the
implementation adding overhead to do this ... I'm thinking of an
implementation that calls getParent() until it gets a document, or
null.  getDocument() should be able to return null, for nodes not
currently in a document.

>From: "Elliotte Rusty Harold" <elharo at metalab.unc.edu>
>> At 3:43 PM -0700 4/28/01, Jason Hunter wrote:
>>
>> >Here's my challenge to you:  Figure out the interface of Item.  Keep in
>> >mind that any method declared should be useful across all classes
>> >implementing the interface.  And keep in mind the interface should be
>> >useful for more than just being a common base interface.  Object is good
>> >enough at being a common base; there would need to be extra value.
>>
>> I'm not sure there needs to be more than that. I think having the

I agree here.  In developing collections of things, it's nice to be
able to check that the things are JDOM things, without having to check
a dozen unrelated classes (code that will only work so long as no
classes are added to the API, btw).

This also has *some* potential (I'm not sure how much) to allow
subclassers to do more than subclass (supposing someone were to decide
that, despite the decisions of the API developers, they really want to
have a Text or Chars class, for instance).

>> 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.
>>
>> On a similar line, I don't feel Object is good enough as a common
>> base class because a method that takes an Object as an argument
>> implies to me that it can indeed take any object but our methods
>> can't. This seems to cry out for a Node interface. The case where
>> methods do take any objects as arguments, and to which me are most
>> similar, the Java Collections API, indeed does allow any object types
>> as arguments.

Strong agreement.  It's clear that some type checking is done within
JDOM to ensure well-formedness; this type-checking *ought* to be
checking (where possible, when adding child nodes) of an interface,
rather than checking of multiple unrelated classes.  Extensibility.

>> However, I do think they're a couple of methods that would be useful
>> in the Node interface. At a minimum I'd say getParent() and

+1

>> getDocument(). I think we might also want to look at (though perhaps

+0; +1 if (as above) we suggest that all implementations should avoid
bloating the classes by storing an actual pointer.

>> in 1.1) a getValue() method which returns the XPath value of a Node.

+2!  <grin />  +1, that is--I think this is extremely valuable, and a
Node interface should at minimum *allow*, and ideally to some degree
*promote* generic programming ... I can go through and grab information
without caring about type.  I also really like the idea that getValue()
would have XPath semantics; consider the possibility of implementing
other XPath functions as well (stringValue() in particular has
different semantics than either toString() or
XMLOutputter.write(Element)).

>> This is a very useful thing to have even if you're not using XPath,
>> and it is genuinely applicable to all node types, (as opposed to DOM
>> nodes, some of which have null values.) I also think we could
>> plausibly put hasChildren() and getChildren() in the Node interface.

-1, unless we also add hasAttributes() and getAttributes().  In either
case, this is *clearly* a characteristic of the Element class, the only
branching node available (which branches, in fact, in two "axes")
(well, Document is arguably a branch node, but is better considered a
root node, with highly specialized semantics).

If hasChildren/getChildren were to be added, I'd suggest a
subinterface, BranchNode, to define it (and in that case, maybe
Document would actually be a 'BranchNode' ... but syntactically,
Document may have multiple children, *except* that it may only have one
child Element ... and is the only Node subtype that can have a
Doctype ... and generally has a "pattern" as well, in which the
comments and PIs that are its other valid children usually appear
before the Element).

I think, though, that type-safety, reduction of casting in generic
circumstances, and the two methods getParent() and possibly
getDocument() are a perfectly adequate Node interface.

Note that I am *not* promoting a factory-based modification in
supporting this model.

Amy!
-- 
Amelia A. Lewis         alicorn at mindspring.com           amyzing at talsever.com
    Songs and fame are vain endeavor--
    only two things fail us never,
    only two things last forever--
    sorrow and love, sorrow and love ....
                                         -- The Last Song of Sirit Byar