[jdom-interest] Important proposal: Element/Document changes

[Jason Hunter]

> But what about;
> 
> List getAttributeValues(String name)
> List getAttributeValues(String name, Namespace ns)

Attributes only have one value.

> void addAttributeValue(String name, String value)
> void addAttributeValue(String name, String value, Namespace ns)

We have element.addAttribute(new Attribute(name, value));

> > Element addContent(String text)
> > Element addContent(Element element)
> > Element addContent(ProcessingInstruction pi)
> > Element addContent(Entity entity)
> > Element addContent(Comment comment)
> >   Adds the given content to the element.  Replaces the various
> > addChild() methods because we're not treating Comments and such as
> > "children".  (Before you could call addChild(pi) and then call
> > getChildren() and wouldn't find the method returning the pi!)
> 
> +0
> 
> However getContent() will only return the textual content, and
> getMixedContent() will have to be called to get all the content added
> using the addContent() method.
> 
> Mmmm, I'm not totally sure I like this.

Me either.  But what choice do we have?

> > boolean removeContent(String text)
> > boolean removeContent(Element element)
> > boolean removeContent(ProcessingInstruction pi)
> > boolean removeContent(Entity entity)
> > boolean removeContent(Comment comment)
> >   Removes the given item.  Does a == check to compare, so presumably the
> > item would have been just retrieved with a getMixedContent().  Replaces
> > the current removeChild() methods that were accepting non-elements.
> 
> +1 for the names.
> 
> -1 for the == check. I would prefer a equals(), given that the boolean
>    result will inform you of the result of operation.

For all the JDOM objects .equals() already does a == for various reasons
as explained in the FAQ.  So there's really no difference in what you
want for anything but Strings.  To do a .equals() for strings would be
inconsistent.  Besides, if you have

  <elem>foo<child/>foo</elem>

And you want to remove the second foo, you need to do a == to
distinguish from the first.

> > Now some methods on Document:
> >
> > Document addContent(Element root)
> > Document addContent(ProcessingInstruction pi)
> > Document addContent(Comment comment)
> > Document addContent(Entity entity)   // Do we need this?
> >   Similar to the methods on Element.  Cleans things up since there's no
> > reason to have addComment(Comment) on Document but addContent(Comment)
> > on Element.  The addContent() method will be checked so only one Element
> > can be added to a document.
> 
> +1 for all except addContent(Element root).
>    I'm guessing that addContent(Element root) will replace the previous
>    root element ? then it's not adding its replacing.

The issue is how you do a document like this:

<!-- comment -->
<root/>
<!-- comment -->

It's a whole lot easier with the above using addContent(Element) than
trying to make setRootElement() behave right.  If you
addContent(Element) and there's already an element, then we throw an
IllegalAddEx.

-jh-