[jdom-interest] The CHANGE has BEGUN!

[Jason Hunter]

I just checked in a new version of Element.java that's in line with the
proposal I sent out Tuesday.  I haven't started on Document.java yet,
and I'm too tired to start now.

All in all, 559 lines were added and 423 lines removed.  If you don't
want to deal with potentially buggy software, don't do an update for a
while.  If you want to be helpful, update right now and try out the
changes.

I changed getContent() to getText() and getTextTrim().  I changed
getMixedContent() to always return whitespace.  I changed addChild() to
addContent().  I changed removeChild() to removeContent().  (And I added
versions of addContent/removeContent that were hitherto forgotten.)  I
also cleaned up the javadocs for the methods I changed; we had some
crazy cut and paste typos in there and behaviors that weren't
documented.

I did not change getChild() to getChildElement() or getChildren() to
getChildElements().  The voting on the list has been 3 in favor of
keeping getChild() and 2 in favor of getChildElement().  There doesn't
seem to be a clear consensus, so for now at least I'll leave it the way
all your current code is written and the way Brett's book has it
written.

In a couple places I varied from the first proposal:

I deprecated the old method signatures wherever possible as someone
requested.  We'll remove the methods after the next beta.  Note that a
few internals changed so that 100% backward compatability would be hard
to maintain without a lot of code, and in those fairly rare cases I
didn't worry about it.  A few things may break.

I also changed getTextTrim() to normalize internal whitespace, as
Patrick Dowler suggested.  That means all whitespace content will become
a single space, a la HTML.  Let me know if you like this behavior.  I
thought it could be useful with mixed content

<element>
  Before
  <!-- comment>
  After
</element>

because the "pure" getTextTrim() would have returned "Before\n  \n 
After" but now it'll be "Before After".  The potential problem is that
<element>Before  After</element> will also return a single space between
the words.

And finally, I added getChildText() and getChildTextTrim() methods
because dammit I really needed them on the code I was writing this
afternoon, and I deserve to make my life a little easier since I spend
how many hours working for free here.  :-)  If you don't like them, you
can ignore them.  Maybe there's a better way, but no one's found it. 
Regardless, I suspect many of you (David Smiley for sure) will find
these useful when parsing config or data files.

-jh-