[jdom-interest] Next JDOM evolution

[Jason Hunter]

phil at triloggroup.com wrote:
> 
> I  personnaly faced 3 problems when moving from B7 to B8

Thanks for writing in.  This will help people as they upgrade.

> => First is the introduction of the text class. As we often do 
> a getContent() and check the type of a node, this code
> was broken. Moreover, it is quite dificult to locate compared 
> to a method removal or a signature change.

True, if you're a power user used to doing iterations of raw content,
you'll need to look for Text now and not String.

> => Secundo, getRootElement() now throws an exception instead of 
> retuning null. Currently, we have lots of code like
> if( doc.getRootElement()!=null ) {
>     //....
> }
> And this code is also broken, and also *very* difficult to locate. 

Here you were relying on a bug in the implementation which allowed docs
without root elements, and were relying on the undocumented back-door
way to build a document passing null as its root.  We fixed the bug by
making it allowed but throwing an exception if you try to access the
root element of a document when it doesn't exist.  There was much debate
on this topic.

> For example, if you have a method like
> void doSomething( Element e ) {
>     if( e!=null ) {
>         //....
>     }
> You should be careful when you call it.
> Moreover, I thought that this change was happy for 2 reasons:
> * Document allows a null root, so it is not an illegal state but a valid one

It indicates a malformed document, but we've opted to allow it for power
users who want to have a document without a root for a while, but we
throw an exception if you try to use this malformed document by reading
its content.

> * this is not coherent with other methods (ex: Element.getChild(String name)). 
> So, when to check the returned value and when to catch an exception?

getChild() returns null if there's no child.  getRootElement() is the
only method that may throw an exception, and that's because if there's
no root you have an illegal document.  Not having some random child does
not indicate an illegal document.

> => The list changes also broke some code, throwing some Concurrent

I added a FAQ entry for this that I hope will help people.  The list is
now more live than it was before, is the short reason for that.

-jh-