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

[Jason Hunter]

Hi everyone,

In an effort to bring the method names and behavior of Element and
Document more in line with the XML spec, and to make the methods more
intuitive as well, we propose the following changes.  Please let us know
if you support the changes, and if not, explain why not.  (The "we" I'm
referring to is Brett, Elliotte, and myself who had a conference call
Sunday morning to hash out the issues in real time, as well as James
Davidson who helped brainstorm on some issues.)

First, on Element:

String getText()
  Returns untrimmed text content.  Replaces getContent(true).  Content
just isn't the right name for the text nodes.

String getTextTrim()
  Returns trimmed text content.  Replaces getContent() and
getContent(false).  Another possible naming is getTextTrimmed().  
getTextTrim() is currently the best candidate because it's shorter 
and matches foo.trim().

Element setText(String)
  The natural replacement for setContent(String).

Element getChild(String name)
Element getChild(String name, Namespace ns)
List getChildren()
List getChildren(String name)
List getChildren(String name, Nmespace ns)
-- or --
Element getChildElement(String name)
Element getChildElement(String name, Namespace ns)
List getChildElements()
List getChildElements(String name)
List getChildElements(String name, Namespace ns)
  These methods return (respectively) the first Element with the given
name, all child elements with any name, and all Elements with the given
name.  We'll remove getChild(String name, String uri) and
getChildren(String name, String uri) because they prove a point but
aren't very useful.  It's an open question whether the name should be
getChild()/getChildren(), which are short and convenient, or
getChildElement()/getChildElements(), which are more explicit and more
in line with the XML specification terminology.  Let us know what you
think.

List getMixedContent()
  Returns the full content of an element, replacing
getMixedContent(true).  Remove getMixedContent(boolean) because any time
you're interested in the low-level mixed content you presumably want to
see all the whitespace nodes, or could at least ignore them yourself. 
Is that true?  Naming this method getContent() might be nicer but that
will cause subtle bugs to existing code.  This also makes it clear the
List may contain various types of objects.

String getAttributeValue(String name)
String getAttributeValue(String name, Namespace ns)
  Returns the given attribute value, avoiding the getAttribute() call. 
I would have sworn we had this method already, but can't find record of
it.  It's surely convenient.

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!)

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.

boolean removeChild(String name)
boolean removeChild(String name, Namespace ns)
boolean removeChildren(String name)
boolean removeChildren(String name, Namespace ns)
-- or --
boolean removeChildElement(String name)
boolean removeChildElement(String name, Namespace ns)
boolean removeChildElements(String name)
boolean removeChildElements(String name, Namespace ns)
  Removes the given child or children elements.  These methods already
exist.  We'll remove the methods removeChild(String name, String uri)
and removeChildren(String name, String uri).  Again, let us know which
naming style you prefer and why.

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.

boolean removeContent(Element element)
boolean removeContent(ProcessingInstruction pi)
boolean removeContent(Comment comment)
boolean removeContent(Entity entity)  // XXX Do we need this?
  Removes the given item.  Does a == check to compare, so presumably the
item would have been just retrieved with a getMixedContent().  Replaces
the current removeProcessingInstruction() method, and the others are new
functionality.


Have this method on both Element and Document:

Element setMixedContent(List)  // on Element
Document setMixedContent(List) // on Document
  Sets the content for the element or document.  The document version
will be checked so only one root element can exist.


Entity will also change to follow the naming pattern followed by Element
and Document.


So what do you think?  Do we have the right idea?  Any concerns? 
Anything we should also address during this renaming phase?

-jh-

P.S.  We also talked about how to handle XPath in the future, because
that might have an impact on our naming decisions.  We decided there was
no immediate need to worry about XPath because the best approach would
probably involve an XPath class, not involve adding methods to the
current data objects.  For example, we could have a "List
XPath.getList(Element e, String xpath)" method that returns a list of
results, with convenience methods getComment / getElement / getProcInstr
/ getEntity / getText so you could call getText("foo/bar::text()") to
easily get the text of a grandchild, something dear to my heart.  It's
premature to debate this (let's concentrate on the above), but that's a
heads up of what was discussed.