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

[Jay Di Silvestri]

FWIW, I could really use the AddChildAt.  DOM has the directive
"InsertBefore" that is kind of klunky but it works.

Jay Di Silvestri
Executive Vice President
Advanced Data Engineering
1310 Redwood Way, Suite 120
Petaluma, CA 94954
(707) 794-7000 x23 
jay at adei.com




-----Original Message-----
From: tsasala at hifusion.com [mailto:tsasala at hifusion.com]
Sent: Tuesday, July 25, 2000 6:55 AM
To: Jason Hunter
Cc: jdom-interest at jdom.org
Subject: Re: [jdom-interest] Important proposal: Element/Document
changes



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