[jdom-interest] How to upgrade document

[Alex Rosen]

Here's my document on incompatible changes in beta 8. Feel free to much with
it however you want.

Is there anything I missed? In particular, should any of the changes to
XMLOutputter's pretty-printing logic go in here? I.e. how likely is it that
someone would have to change how they deal with XMLOutputter as a result of
these changes?

Alex
-------------- next part --------------
************************
*** BETA 7 TO BETA 8 ***
************************

This document lists incompatible changes made from beta 7 to beta 8.


TEXT CLASS
----------

JDOM now has a Text class. Text objects, along with CDATA objects, hold the
textual content of the XML document. Previously, the list returned from
getContent() would contain plain String objects, but in beta 8 the Strings
were replaced with Text objects. Call the getText() method on the Text
object to get its String value. For convenience, on the parent Element you can
still do getText(), setText(), and addContent() with a String. These methods
will automatically perform any necessary conversions.


FULLY LIVE LISTS
----------------

In beta 7, the Lists returned from getContent(), getChildren(), and 
getAttributes() did not live up to their contract, because they were not fully
"live". Changes to these Lists would affect the underlying Element list, but
not vice versa. Now in beta 8 they are fully live. For example, if you add a
child to an Element, any previously-obtained List of its children will
automatically see this new child.

This can cause upgrade problems when you loop over the contents of a list, and
try to modify the List (or the parent Element/Document) at the same time. If you
loop over the list by index, you may find that the size() of the list changes
unexpectedly, or that the indices of the items change out from under you. If
you loop with an Iterator, you may get a ConcurrentModificationException.

The possible fixes are:

- If you get a ConcurrentModificationException, use the add(), remove(),
or set() methods on Iterator or ListIterator to modify the list, rather than
using methods on the List or the parent Element/Document.

- Make a non-live copy of the list. This list will not see any changes made to
the parent Element/Document. For example:

List liveList = parent.getChildren();
List staticList = new ArrayList(liveList);

- Rearrange your looping construct to take into account the live list.
For example, change:

// This will skip every other child!
for (int i = 0; i < children.size(); i++) {
    Element child = (Element)children.get(i);
    parent.removeContent(child);
}

to:

while(children.size() > 0) {
    Element child = (Element)children.get(0);
    parent.removeContent(child);
}


REMOVED METHODS
---------------

The following methods that were deprecated in beta 7 were removed in beta 8:

= On Element =
getCopy()              - use clone(), setName(), and possibly
                         setNamespace() instead.
addAttribute()         - use setAttribute() instead.
removeAttribute(String, String)
                       - use removeAttribute(String, Namespace) instead.
hasMixedContent()      - this method was not well-defined. Use getContent() to
                         examine the content list manually.

= On Document =
several get/set/remove ProcessingInstruction methods
                       - Use getContent() to find, add, or remove the PIs from
                         the content list manually.

= On Document and Element =
getMixedContent()      - use getContent() instead.
setMixedContent()      - use setContent() instead.

= On Attribute =
constructor (String, String, String, String) 
                       - use constructor (String, String, Namespace) instead.

= On several classes =
getSerializedForm()    - use XMLOutputter.outputString() instead.

= On XMLOutputter =
setTrimText()          - use setTextNormalize() or setTextTrim() instead.

= On JDOMException =
getRootCause()         - use getCause() instead.


DEPRECATED METHODS
------------------

Several methods have been deprecated and will be removed in the next beta.
These can be found in the API documentation (click on "Deprecated" at the top
of the right-hand pane).