[jdom-interest] Element Reference from Attribute

[James Strachan]

----- Original Message -----
From: "Rosen, Alex" <arosen at silverstream.com>
> I like this general idea. I'd like to propose a slightly different
> technique, which lets us have only one API, rather than two very similar
but
> not identical APIs. Just put all methods (getParent(), setValue(), etc) on
> both sets of classes, but have them throw exceptions on the base class.
This
> is not unprecedented; the Collections API (which we seem to be so fond of)
> does this with all of its mutation operations (see the add(), remove(),
etc.
> methods on java.util.Collection). It throws an
UnsupportedOperationException
> when the particular collection implementation doesn't support a particular
> method. JDOM could do the same.

Yes I think this is a reasonable technique but more applicable for when bits
of a standard API are enabled or disabled. (e.g. when a collection happens
to become immutable or removal is specifically disallowed). I can imagine
doing the same for a 'read only JDOM tree' (either singly or doubly linked).
Or when a validator disallows a certain operation.

However in the dual tree JDOM I'd rather use type safety to guarrentee
semantics. Doubly linked trees offer much greater semantics...
    * getParent()
    * getDocument()
    * getValidator() // ?? maybe for incremental validation
    * full XPath support
    * full XInclude support
    * guarrenteed uniqueness of nodes (no sharing allowed)
    * in place mutation of leafes

None of these methods / features will *ever* be implemented by a singly
linked tree.  I'd say there is enough semantics there to warrant 2
'classes'. To use the Collections API as an example we can do

Collection colllection = ..;
if ( collection instanceof List ) {
    List list = (List) collection;
    // I can now use lots of new functionality because I know I'm a list
}
else {
    // I might have to do things differently for the general case
}

I think we need to be able to do the same in JDOM. Singly linked JDOM is
like "Collection" - general purpose and enough for most uses. "List" extends
"Collection" with sepecial operations only a subset of implementations
offer. It would be bad form to implement List rather than Collection but
throw exceptions for *all* the List interface.

> With this change, there's no need to overload the API with multiple
> type-safe methods like getAttribute() and getAttributeNode().

I've actually removed this typesafe method now, so there no longer are any.
I'll post a URL to my patch soon.

> And, you only
> have to learn one set of interfaces, since the methods on Attribute and
> AttributeNode are identical.

I don't think they should be. AttributeNode offers a large range of
functionality that Attribute never can. Throwing exceptions for all the new
methods AttributeNode can add feels more like a hack.

> By default, the builders would generate the
> fully-functional subclasses, but could be set to create the memory-saving
> base classes by people who knew what they were doing.

I'd agree though it shouldn't require rocket science to switch between the
two.

> Another benefit is that XPath and the like can refer to only one set of
> classes, without having to cast back and forth, and still be maximally
> flexible in which set of classes it takes. You'd like for XPath to work
with
> the memory-saving classes as much as possible, and to only require the use
> of the fully-functional classes when evaluating a compilcated XPath that
> needed the extra functionality, like getParent(). So the XPath API would
> have to take Attribute objects in its method signatures, but cast to
> AttributeNode whenever it wanted to call getParent(). With this new
> technique, no casting would be necessary.

"instanceof" gets replaced by try { } catch ().
I'd rather go "instanceof" as its usually more efficient. I prefer to use
exceptions sparingly.

> Since both sets of classes would implement Node,

I don't like the idea that Attribute implements Node - it shouldn't agree to
implement an API then throw exceptions for *all* the implementation methods.
That feels like deception. Saying you implement an interface and throwing an
exception whenever any of the interface is used.

> I'd propose that the
> classes be named MinimalAttribute and Attribute, or something like that,
> instead of Attribute and AttributeNode.

Not sure. I'm still open to suggestions on naming. Initially I wanted the
doubly linked implementations to be named like they were the default
(Attribute / Element etc) and have the singly linked ones named differently
(BaseAttribute / BaseElement or something) as I thought they would be used
less.

However in most code everywhere (except in your own custom builder) you
actually refer to the common base class most of the time. Its only when you
want to do 'special things' that you cast. So I now favour the common base
class being Element / Atttribute. Due to the polymorphic Node interface
proposal, which only the doubly linked implementation would implement, my
favoured naming scheme now is Attribute -> AttributeNode. The postfix of
Node is an extra visual clue that the object is-a Node

<James/>


James Strachan
=============
email: james at metastuff.com
web: http://www.metastuff.com



If you are not the addressee of this confidential e-mail and any
attachments, please delete it and inform the sender; unauthorised
redistribution or publication is prohibited. Views expressed are those of
the author and do not necessarily represent those of Citria Limited.