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

[tsasala at hifusion.com]

	Two comments:  is it possible to deprecate the methods instead
of removing them?  We have application code that relies on JDOM, despite
the fact it is beta :).  Secondly, how about a replaceChild or at least
an addChildAt method?  It's trivial, but order makes a huge difference
to our application, so removeChild/addChild just doesn't work.
Other than that, I'm generally in favor of the changes.

	-Tom

p.s.,

	I like the simplicity of getChildren/getChild over
getChildElement etc.

Jason Hunter wrote:
> 
> 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.
> _______________________________________________
> To control your jdom-interest membership:
> http://lists.denveronline.net/mailman/options/jdom-interest/youraddr@yourhost.com