[jdom-interest] Code submision: JDOM2 the dual tree implementation...

[Patrick Dowler]

On Thu, 23 Nov 2000, you wrote:
> I'm about to post a full implementation of the 2 tree JDOM for your review.
> I've noticed that patch submissions often take a while to get though to the
> list, so I thought I'd introduce it first ;-) The full source code will be a
> few hours later...

Since I also argued for this split, 

> The effect on the API is suprisingly minimal. 

Since the doubly-linked subclasses are strictly adding features, this isn't
surprising, In fact, that is what made the whole idea appealing in the first
place :-)

> The following standard JDOM
> objects are now immutable, so can be shared across any Element and Document
> instances..
>     Attribute
>     Entity
>     Comment
>     CDATA

They do not have to be immutable in order to be shared. In fact, since I could
write my own factory to create mutable/shared attributes, you can't enforce it thus
you can't assume it in any code. The base implementation could be immutable, but 
since it can't be final that isn't much of a constraint  in practice.

If a developer wants to mutate these things and be safe, they could use the
doubly-linked tree and, as Jason said, the parentage enforces the lack of
sharing for them.

ProcessingInstruction?

> There are new doubly linked, mutable versions of these...
>     AttributeNode
>     EntityNode
>     CommentNode
>     CDATANode
>  
> Each of these new classes implements the new Node interface which as a
> method
>     public interface Node {
>         public Element getParent();    
>     }
>  
> There were little typesafe methods on Element for Comment/Entity/CDATA.
> Though I've added a couple of typesafe helper methods for Attribute on
> Element...

Not sure if helper methods are what you really want here. First, user code could
do this quite easily.  In general, such helper methods add to the API without 
really allowing you to do something you couldn't do. if enough people are 
wriitng the same code, then it makes sense, but I'd hold off on this for a bit.

Also, I don't know that immutable vs. mutable and singly vs. doubly linked are 
"necessarily" related. Some people might have good reason for mutable/shared 
attributes, for example*. They could do it by implementing the Factory appropriately.
  
* I could write a pretty fast "in-place" transformer if I was interested in changing
ALL instances (that is, all shared instances) of something into something else :-)



> None of the outputters or adapters are affected by any of these changes. The
> only other change is in the input package. I've renamed my previously
> submitted "SAXFactory" to be "JDOMFactory". This class is now reused with
> minimal change in DOMBuilder and SAXBuilder / SAXHandler.
>  
> There is a new JDOMFactory implementation, which I've called JDOM2Factory
> for now (horrible name) which is used to build the full doubly linked tree.

One downside to all this is that it is a nice feature of JDOM to use "new" instead
of a factory in your code. Of course, once people start subclassing, they can
chose "new" vs. "factory" as they see fit, so it is just the people who use the
API as is that have to take care. It would be very nice to not force everyone to use
the factory pattern in their own code and yet me maintainable...

Once upon a time I tried this sort of thing by naming the base and subclasses 
the same and only changing the package name. Then you could "upgrade" to 
the power-feature set simply by changing the import statement, and all your 
uses of "new" were OK.

Basically:

---------------------------------------
package org.jdom.level1;
class Element { ... }
---------------------------------------
package org.jdom.level2;
class Element extends org.jdom.level1.Element { ... }
---------------------------------------

In the user code, you just "import org.jdom.level1.*;" or "level2.*;" as needed.
Of course, once you start using level2 features, you can't go back to importing
level1 without the compiler barfing, but that should be seen as a feature.

Are there any catches to this strategy?

Other than the millions of "this won't compile" messages on the mailing list :-)

Is it madness? 


-- 

Patrick Dowler
Canadian Astronomy Data Centre