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

[philip.nelson at omniresources.com]

I am not overwhelmed by this proposal.  Not because the ideas aren't good,
but because they aren't that much improved over the current api.  I recently
brought two developers who, while experienced programmers (Smalltalk, C++,
VB)had little Java and no XML background.  In less than two weeks time, they
are able to move around JDOM based classes with ease (except for some nasty
NullPointerExceptions =8^( )

> First, on Element:
> 
> String getText()
> String getTextTrim()

Makes sense +1 getTextTrim()
 
> 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)

good

> 
> 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.

getContent would be better of course.  Fine with all whitespace.  Since the
old getContent returned a String, wouldn't the compiler catch those?

> 
> 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.

I remember fixing "legacy" code with getAttributeValue.  It was decided that
getAttribute().getValue() was just as fast to type.
> 
> Element addContent(String text)
> Element addContent(Element element)
> Element addContent(ProcessingInstruction pi)
> Element addContent(Entity entity)
> Element addContent(Comment comment)

OK but we get text with getText() and set it with addContent() OR setText()?
Or is this ONLY for addContent("<achild>foo</achild>")?  Would this be
enforced? Will setText() only allow plain text? I'm confused

> 
> boolean removeContent(String text)

?? same as above

> boolean removeContent(Element element)
> boolean removeContent(ProcessingInstruction pi)
> boolean removeContent(Entity entity)
> boolean removeContent(Comment comment)

OK
> boolean removeChild(String name)
> boolean removeChild(String name, Namespace ns)
> boolean removeChildren(String name)
> boolean removeChildren(String name, Namespace ns)
I prefer this naming style because it's shorter and less of a change from
what current example code and Brett's book shows.
> 
> 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?

Makes sense.  DocType remains the same?  Does setRootElement() and
getRootElement remain?


The rest looks good