Discussion:
Important proposal: Element/Document changes
(too old to reply)
Jason Hunter
2000-07-25 09:05:05 UTC
Permalink
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.
t***@hifusion.com
2000-07-25 13:54:35 UTC
Permalink
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.
Post by 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.)
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.
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.
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.
_______________________________________________
Jason Hunter
2000-07-25 17:16:46 UTC
Permalink
Post by t***@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 :).
I personally would be OK with deprecating for one beta round to give you
time to change. However, I'm firm there will be NO deprecated methods
present in 1.0 final.
Post by t***@hifusion.com
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.
I can see a good use case for replaceChild() for tools like XMLC that do
that all the time. Would it be replaceChild() or replaceContent()? I
lean toward replaceChild(Element,Element). replaceContent() would need
5*5 versions depending on what you wanted to replace with what.
Replacing an element with an element is probably the far more common use
case, and that should be called replaceChild().

Then the other method you propose would be addContentAt(). That's
probably better as a Content form rather than Child form. Hmm, we'd
need five forms again to cover all bases. What's the compelling common
use case here?
Post by t***@hifusion.com
I like the simplicity of getChildren/getChild over
getChildElement etc.
OK. Others agree or disagree?

-jh-
t***@hifusion.com
2000-07-25 20:13:35 UTC
Permalink
Post by Jason Hunter
Post by t***@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 :).
I personally would be OK with deprecating for one beta round to give you
time to change. However, I'm firm there will be NO deprecated methods
present in 1.0 final.
That's perfectly reasonable.
Post by Jason Hunter
Post by t***@hifusion.com
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.
I can see a good use case for replaceChild() for tools like XMLC that do
that all the time. Would it be replaceChild() or replaceContent()? I
lean toward replaceChild(Element,Element). replaceContent() would need
5*5 versions depending on what you wanted to replace with what.
Replacing an element with an element is probably the far more common use
case, and that should be called replaceChild().
Then the other method you propose would be addContentAt(). That's
probably better as a Content form rather than Child form. Hmm, we'd
need five forms again to cover all bases. What's the compelling common
use case here?
The fundemental idea here is to replace the element in the
backing list with a new element in exactly the same place. replaceChild
makes more sense to me, as I don't need to know the index of the element
in the parent's list. However, addChildAt might provide more flexibility
in the long run. If I had to vote, I'd vote for replaceChild.
FWIW, I have the code implemented as a static helper now, so I can
send it along if need be.

-Tom
Jason Hunter
2000-07-25 20:27:04 UTC
Permalink
Post by t***@hifusion.com
The fundemental idea here is to replace the element in the
backing list with a new element in exactly the same place. replaceChild
makes more sense to me, as I don't need to know the index of the element
in the parent's list. However, addChildAt might provide more flexibility
in the long run.
addChildAt() can be done with element.getMixedContent().add(int,
Object). List doesn't have a replace() method though.
Post by t***@hifusion.com
If I had to vote, I'd vote for replaceChild.
FWIW, I have the code implemented as a static helper now, so I can
send it along if need be.
Sure.

-jh-
p***@omniresources.com
2000-07-25 14:15:01 UTC
Permalink
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^( )
Post by Jason Hunter
String getText()
String getTextTrim()
Makes sense +1 getTextTrim()
Post by Jason Hunter
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
Post by Jason Hunter
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?
Post by Jason Hunter
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.
Post by Jason Hunter
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
Post by Jason Hunter
boolean removeContent(String text)
?? same as above
Post by Jason Hunter
boolean removeContent(Element element)
boolean removeContent(ProcessingInstruction pi)
boolean removeContent(Entity entity)
boolean removeContent(Comment comment)
OK
Post by Jason Hunter
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.
Post by Jason Hunter
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
Jason Hunter
2000-07-25 17:08:46 UTC
Permalink
Post by p***@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^( )
Are you saying you like the changes or not? I'm confused. :-)
Post by p***@omniresources.com
getContent would be better of course. Fine with all whitespace. Since the
old getContent returned a String, wouldn't the compiler catch those?
Yes, but if you use already compiled code you'll get weird runtime
errors. But more importantly, it's easier for people to understand that
names change, harder that fundamental behaviors change. And besides, it
is mixed content you're getting.
Post by p***@omniresources.com
I remember fixing "legacy" code with getAttributeValue. It was decided that
getAttribute().getValue() was just as fast to type.
Cept for those NPEs.
Post by p***@omniresources.com
Post by Jason Hunter
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
addContent() adds the string to the list. setText() does a set and
replaces all the content with the text. This is in line with current
behavior.
Post by p***@omniresources.com
Post by Jason Hunter
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.
OK.
Post by p***@omniresources.com
Makes sense. DocType remains the same? Does setRootElement() and
getRootElement remain?
Yep.

-jh-
Steve Meister
2000-07-25 14:37:20 UTC
Permalink
-----Original Message-----
String getText()
Returns untrimmed text content. Replaces getContent(true). Content
just isn't the right name for the text nodes.
[snip]
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.
What is the behavior if you call getText() on an element that contains mixed
content? Does the method simply return the first text child it finds? I.e.
if you have

<element>
This contains <b>mixed</b> content
</element>

What would I get if I called getText() on this element?
Jason Hunter
2000-07-25 17:03:29 UTC
Permalink
Post by Steve Meister
What is the behavior if you call getText() on an element that contains mixed
content? Does the method simply return the first text child it finds? I.e.
if you have
<element>
This contains <b>mixed</b> content
</element>
What would I get if I called getText() on this element?
The proposed behavior would match getContent() and return
"This contains content".

-jh-
Jay Di Silvestri
2000-07-25 14:53:48 UTC
Permalink
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
***@adei.com




-----Original Message-----
From: ***@hifusion.com [mailto:***@hifusion.com]
Sent: Tuesday, July 25, 2000 6:55 AM
To: Jason Hunter
Cc: jdom-***@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.
Post by 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.)
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.
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.
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.
_______________________________________________
http://lists.denveronline.net/mailman/options/jdom-interest/***@yourhos
t.com
_______________________________________________
To control your jdom-interest membership:
http://lists.denveronline.net/mailman/options/jdom-interest/***@yourhos
t.com
Jason Hunter
2000-12-07 08:17:25 UTC
Permalink
(I sent this on Tuesday but oddly enough it never came through.)

I propose to add doc.removeContent() methods for all types except Entity
and Element. The methods were recently put back in Element and it would
make sense following the same logic the person-whose-email-I-can't-find
used to get them into Element to have them in Document too.

I would not do removeContent(Entity) because entities can't exist at the
document level. We don't have addContent(Entity) either.

I would not do removeContent(Element) because it would result in a
malformed document and the current strategy at least is to not allow
malformed documents. (I expect we'll revisit that later.)

I think we should also probably get rid of doc.addContent(Element)
because it can never succeed when called on a well-formed document. We
have setRootElement() for that.

Any concerns?

-jh-
p***@omniresources.com
2000-07-25 17:40:29 UTC
Permalink
Post by Jason Hunter
Are you saying you like the changes or not? I'm confused. :-)
My only resistance is because of code I already have. If these were the
names chosen from the start, I would be happy with them. I think they are
an improvement. I defer to the rest of you to determine that throwing out
much of the current example code in this list, the samples, the book, the
articles, and my current projects is justified for the consistency gained
with renaming core methods at this point. It will take less than half a day
to update my code so consider my objection mild.
David W. Smiley
2000-07-25 23:27:09 UTC
Permalink
The new naming proposal sounds nice in general but:

I think getAttributeText() should exist instead of getAttributeValue()
for consistency with Elements, _even_though_ an Attribute is always
Text.

I am one of those in the camp that believe a
getChildText(name,namespace) method should exist for all the reasons
that have been discussed by the proponents of this already. It is a
common case and will make code more concise.

For some applications, order of elements DOES count (as was recently
pointed out by a list member). Would it be possible to insert the new
Content being added into the returned List by getChildElements() using
list.add(idx,newthing) ? If it doesn't work right now, I really think
that it would be useful to have the List be "backed" by JDom. If you
ultimately decide against this proposal that the returned list should
not be backed by JDom, then it should definitely be made unmodifiable
since some clients may be confused and expect the DOM to actually be
updated.

Must addContent(xxxx) and removeContent(xxxx) both be overloaded by all
Node types? Lets just say, for the sake of argument, that there is a
Node interface that simply flagged Element, Entity, etc. as being a
Node. (Maybe it should be called Content, anyways...). Then, if you
wanted to enable the ability to add/remove an element at a certain
index, you would have addContent(idx,Node) and removeContent(idx,Node).
All the instanceof's would only be around twice, once for each of
these. addContent(Node) and removeContent(Node) would immediately call
their add/Remove(idx,Node) counterparts with a... lets say a
Integer.MAX_VALUE which signifies that it goes on the end. Would this
be easier overall? There would be fewer methods, and it wouldn't really
be a big deal doing the if-else instanceof section twice.

Just my 2 cents.

-- David Smiley
Jason Hunter
2000-07-26 00:23:02 UTC
Permalink
Post by David W. Smiley
I think getAttributeText() should exist instead of getAttributeValue()
for consistency with Elements, _even_though_ an Attribute is always
Text.
Only issue there is then Attribute would need a getText() method to be
consistent with this method, and that's just plain wrong. :-)
Attributes don't have text, they have names and values. (I had the same
idea, but shot it down myself with this reasoning.)
Post by David W. Smiley
I am one of those in the camp that believe a
getChildText(name,namespace) method should exist for all the reasons
that have been discussed by the proponents of this already. It is a
common case and will make code more concise.
I'm in the same camp. Since many XML documents (like web.xml) use
element children as essentially attributes, this method makes good
sense. It avoids the damn NPE with getChild().getText(). Any other
campers?
Post by David W. Smiley
For some applications, order of elements DOES count (as was recently
pointed out by a list member). Would it be possible to insert the new
Content being added into the returned List by getChildElements() using
list.add(idx,newthing) ?
That should work right now, although if there's mixed content we have to
do some guessing about where to put it, since you're using an index for
only part of the actual content.
Post by David W. Smiley
Must addContent(xxxx) and removeContent(xxxx) both be overloaded by all
Node types? Lets just say, for the sake of argument, that there is a
Node interface that simply flagged Element, Entity, etc. as being a
Node. (Maybe it should be called Content, anyways...). Then, if you
wanted to enable the ability to add/remove an element at a certain
index, you would have addContent(idx,Node) and removeContent(idx,Node).
All the instanceof's would only be around twice, once for each of
these. addContent(Node) and removeContent(Node) would immediately call
their add/Remove(idx,Node) counterparts with a... lets say a
Integer.MAX_VALUE which signifies that it goes on the end. Would this
be easier overall? There would be fewer methods, and it wouldn't really
be a big deal doing the if-else instanceof section twice.
Can't do it even if we wanted to. Strings can't extend Node.

-jh-
t***@hifusion.com
2000-07-26 11:24:52 UTC
Permalink
Post by Jason Hunter
Post by David W. Smiley
Must addContent(xxxx) and removeContent(xxxx) both be overloaded by all
Node types? Lets just say, for the sake of argument, that there is a
Node interface that simply flagged Element, Entity, etc. as being a
Node. (Maybe it should be called Content, anyways...). Then, if you
wanted to enable the ability to add/remove an element at a certain
index, you would have addContent(idx,Node) and removeContent(idx,Node).
All the instanceof's would only be around twice, once for each of
these. addContent(Node) and removeContent(Node) would immediately call
their add/Remove(idx,Node) counterparts with a... lets say a
Integer.MAX_VALUE which signifies that it goes on the end. Would this
be easier overall? There would be fewer methods, and it wouldn't really
be a big deal doing the if-else instanceof section twice.
Can't do it even if we wanted to. Strings can't extend Node.
I think a node interface for elements, entities, attributes, etc.,
is a good idea. As Jason pointed out though, it wouldn't work for
content. The interface would simplify the API by eliminating all the
overloaded methods.

-Tom
Brett McLaughlin
2000-07-26 17:03:44 UTC
Permalink
Post by t***@hifusion.com
Post by Jason Hunter
Post by David W. Smiley
Must addContent(xxxx) and removeContent(xxxx) both be overloaded by all
Node types? Lets just say, for the sake of argument, that there is a
Node interface that simply flagged Element, Entity, etc. as being a
Node. (Maybe it should be called Content, anyways...). Then, if you
wanted to enable the ability to add/remove an element at a certain
index, you would have addContent(idx,Node) and removeContent(idx,Node).
All the instanceof's would only be around twice, once for each of
these. addContent(Node) and removeContent(Node) would immediately call
their add/Remove(idx,Node) counterparts with a... lets say a
Integer.MAX_VALUE which signifies that it goes on the end. Would this
be easier overall? There would be fewer methods, and it wouldn't really
be a big deal doing the if-else instanceof section twice.
Can't do it even if we wanted to. Strings can't extend Node.
I think a node interface for elements, entities, attributes, etc.,
is a good idea. As Jason pointed out though, it wouldn't work for
content. The interface would simplify the API by eliminating all the
overloaded methods.
I just don't see it making sense - there is no common ground between
these things. Just doing it for tree walking is a waste, and not a
compelling use case. Look at DOM - half the methods on Node are uesless
on certain Nodes, but mean something on others - that to me is silly.

-Brett
Post by t***@hifusion.com
-Tom
_______________________________________________
--
Brett McLaughlin, Enhydra Strategist
Lutris Technologies, Inc.
1200 Pacific Avenue, Suite 300
Santa Cruz, CA 95060 USA
http://www.lutris.com
http://www.enhydra.org
Patrick Dowler
2000-07-26 17:13:29 UTC
Permalink
Post by Brett McLaughlin
Post by t***@hifusion.com
I think a node interface for elements, entities, attributes, etc.,
is a good idea. As Jason pointed out though, it wouldn't work for
content. The interface would simplify the API by eliminating all the
overloaded methods.
I just don't see it making sense - there is no common ground between
these things. Just doing it for tree walking is a waste, and not a
compelling use case. Look at DOM - half the methods on Node are uesless
on certain Nodes, but mean something on others - that to me is silly.
The minimal idea is a tag interface (a la Serializable) which in some
respect cleans up the API. However, IMO having overloaded methods
isn't bloating the API because you still only have to know one method...

Overloading is a better approach, and you end up having all those anyway
(maybe as protected methods which are called by the "public addNode(Node n)"
method).

I agree with Brett that a non-trivial common interface or base class
is not too useful as there is little common code and most usage requires
that you know which type of "node" you have anyway.

--

Patrick Dowler
Canadian Astronomy Data Centre
Steve Meister
2000-07-26 12:21:05 UTC
Permalink
-----Original Message-----
Post by David W. Smiley
I think getAttributeText() should exist instead of
getAttributeValue()
Post by David W. Smiley
for consistency with Elements, _even_though_ an Attribute is always
Text.
Only issue there is then Attribute would need a getText() method to be
consistent with this method, and that's just plain wrong. :-)
Attributes don't have text, they have names and values. (I
had the same
idea, but shot it down myself with this reasoning.)
Yes, attributes are name/value pairs, and while it's true that the values
are kept as text strings in the XML document, they could be numbers, dates,
etc., so it seems much more logical to me to have getAttributeValue.
Chris Atkins
2000-07-26 13:44:10 UTC
Permalink
Post by Jason Hunter
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)
Being explicit in the name may help with getting up to speed quicker, cut
down on errors and legibility.
Post by Jason Hunter
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!)
Why do we have addContent(String) when we just added setText(). Would we
not want addText(String) to be consistent?
Post by Jason Hunter
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.
I do not see how removeContent(String) is really going to work. It seems
you are making an assumption that each String item in the content has a
unique value. This is not necessarily true. In that case, you need to be
able to specify which one.
Post by Jason Hunter
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.
Like the Element versions for same reason as add. If more that one child
element exists with the same name, removeChildElement(name) would remove the
first one?
Jools Enticknap
2000-07-26 20:24:16 UTC
Permalink
<snip/>

<Element>
Post by Jason Hunter
String getText()
Returns untrimmed text content. Replaces getContent(true). Content
just isn't the right name for the text nodes.
+1
Post by Jason Hunter
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().
+1 for getTextTrim().
Post by Jason Hunter
Element setText(String)
The natural replacement for setContent(String).
+1
Post by Jason Hunter
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.
+1

I prefer the getChildElement(), and the getChildElements().

My first justification is that for non native english speakers Child and
Children are not intuative. Element and Elements is.

Secondly it's explicity stating it's job, rather than implying it.
Post by Jason Hunter
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.
+1

This call should result in the list containing children with whitespace.
Post by Jason Hunter
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.
+1

But what about;

List getAttributeValues(String name)
List getAttributeValues(String name, Namespace ns)

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

Should'nt the above also implemented for completeness ? Or am I missing
something obvious ?
Post by Jason Hunter
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.
Post by Jason Hunter
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.
Post by Jason Hunter
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.
+1 for removeChildElement(), removeChildElements().


</Element>


<Document>
Post by Jason Hunter
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.
Post by Jason Hunter
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.
+1 except I'm not in favour of the == compare. I'd prefer the .equals()
approach.

</Document>

--Jools
Jason Hunter
2000-07-26 21:07:34 UTC
Permalink
Post by Jools Enticknap
But what about;
List getAttributeValues(String name)
List getAttributeValues(String name, Namespace ns)
Attributes only have one value.
Post by Jools Enticknap
void addAttributeValue(String name, String value)
void addAttributeValue(String name, String value, Namespace ns)
We have element.addAttribute(new Attribute(name, value));
Post by Jools Enticknap
Post by Jason Hunter
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?
Post by Jools Enticknap
Post by Jason Hunter
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.
Post by Jools Enticknap
Post by Jason Hunter
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-
Brett McLaughlin
2000-07-26 21:11:31 UTC
Permalink
Jools Enticknap wrote:
<snip-lots-of-agreement />
Post by Jools Enticknap
But what about;
List getAttributeValues(String name)
List getAttributeValues(String name, Namespace ns)
?? attributes must be unique for an element. Can't have two.
Post by Jools Enticknap
void addAttributeValue(String name, String value)
void addAttributeValue(String name, String value, Namespace ns)
Should'nt the above also implemented for completeness ? Or am I missing
something obvious ?
Oh... to clarify:

getAttributeValue(String name) is the same as:

getAttribute(name).getValue();

as opposed to actually getting the Attribute object. Are we getting
mixed up somehwere? I'm not sure what you are asking :~<
Post by Jools Enticknap
Post by Jason Hunter
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.
getContent() is gone. getMixedContent() returns everything, getText()
returns text, getChildElement(s)() returns elements. So getContent() no
longer exists...

-Brett
Post by Jools Enticknap
--Jools
--
Brett McLaughlin, Enhydra Strategist
Lutris Technologies, Inc.
1200 Pacific Avenue, Suite 300
Santa Cruz, CA 95060 USA
http://www.lutris.com
http://www.enhydra.org
James Duncan Davidson
2000-07-26 20:40:15 UTC
Permalink
Post by p***@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.
The API is showing a bit of maturity. :)
Post by p***@omniresources.com
Post by Jason Hunter
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?
Actually, given that this is pre-1.0 and you have a chance to fix something
-- and everybody using this code *should* know that things can change willy
nilly -- are we sure that this isn't a good time to cut to the chase and
just name getContent what it is?

I know that the door is closing fast -- but the door will never be open
again and you'll have to live with this for a long time. OTOH The most
compelling argument is that it's documented in the book.. So there's legacy
there that cannot be recaptured.

.duncan
James Duncan Davidson
2000-07-26 20:42:27 UTC
Permalink
Post by Jay Di Silvestri
FWIW, I could really use the AddChildAt. DOM has the directive
"InsertBefore" that is kind of klunky but it works.
Since it's reflected as a collection, the methods for doing order juggling
and such are there no?
James Duncan Davidson
2000-07-26 20:45:18 UTC
Permalink
Post by Jason Hunter
Post by t***@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 :).
I personally would be OK with deprecating for one beta round to give you
time to change. However, I'm firm there will be NO deprecated methods
present in 1.0 final.
+++1!.
Post by Jason Hunter
Then the other method you propose would be addContentAt(). That's
probably better as a Content form rather than Child form. Hmm, we'd
need five forms again to cover all bases. What's the compelling common
use case here?
And why aren't the collection based methods good enough for any of the use
cases?
Post by Jason Hunter
Post by t***@hifusion.com
I like the simplicity of getChildren/getChild over
getChildElement etc.
OK. Others agree or disagree?
I'm cool with scrapping "Element" postfixes.

.duncan
James Duncan Davidson
2000-07-26 20:48:25 UTC
Permalink
Post by Jason Hunter
addChildAt() can be done with element.getMixedContent().add(int,
Object). List doesn't have a replace() method though.
Yes it does.. :)

List.add(int, Object);
List.set(int, Object);

s/replace/set/g and you have it.

.duncan
Eddy, Joel
2000-07-26 21:28:45 UTC
Permalink
could you unsubscribe the netivation address and keep the medinex one.. i
seem to be getting two of each email

-----Original Message-----
From: James Duncan Davidson [mailto:***@x180.com]
Sent: Wednesday, July 26, 2000 1:40 PM
To: ***@omniresources.com; jdom-***@jdom.org
Subject: Re: [jdom-interest] Important proposal: Element/Document
changes
Post by p***@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.
The API is showing a bit of maturity. :)
Post by p***@omniresources.com
Post by Jason Hunter
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
Post by p***@omniresources.com
old getContent returned a String, wouldn't the compiler catch those?
Actually, given that this is pre-1.0 and you have a chance to fix something
-- and everybody using this code *should* know that things can change willy
nilly -- are we sure that this isn't a good time to cut to the chase and
just name getContent what it is?

I know that the door is closing fast -- but the door will never be open
again and you'll have to live with this for a long time. OTOH The most
compelling argument is that it's documented in the book.. So there's legacy
there that cannot be recaptured.

.duncan

_______________________________________________
To control your jdom-interest membership:
http://lists.denveronline.net/mailman/options/jdom-interest/***@yourhos
t.com
Jools Enticknap
2000-07-27 08:37:51 UTC
Permalink
Post by Brett McLaughlin
<snip-lots-of-agreement />
Post by Jools Enticknap
But what about;
List getAttributeValues(String name)
List getAttributeValues(String name, Namespace ns)
?? attributes must be unique for an element. Can't have two.
OK then I should not be able to do;

Element e = new Element("test");
e.addAttribute("foo", "bar");
e.addAttribute("foo", "bar");

Without the second call throwing an exception ?

Would'nt the resultant XML be ?

<foo foo="bar" foo="bar"/>

Which as you say is a no-no.


<snip-answered-queries />

--Jools
Jason Hunter
2000-07-27 08:50:10 UTC
Permalink
Post by Jools Enticknap
OK then I should not be able to do;
Element e = new Element("test");
e.addAttribute("foo", "bar");
e.addAttribute("foo", "bar");
Without the second call throwing an exception ?
Yep, when I was going through the code tonight I realized there's no
check for that case, and I already added it to the TODO. :-)

-jh-
Brett McLaughlin
2000-07-27 14:07:29 UTC
Permalink
Post by Jools Enticknap
Post by Brett McLaughlin
<snip-lots-of-agreement />
Post by Jools Enticknap
But what about;
List getAttributeValues(String name)
List getAttributeValues(String name, Namespace ns)
?? attributes must be unique for an element. Can't have two.
OK then I should not be able to do;
Element e = new Element("test");
e.addAttribute("foo", "bar");
e.addAttribute("foo", "bar");
Without the second call throwing an exception ?
Right now, that's a good question - we need to look into that (Jason,
can you add that to TODO, and I'll check for it?)
Post by Jools Enticknap
Would'nt the resultant XML be ?
<foo foo="bar" foo="bar"/>
Which as you say is a no-no.
Correct.

-Brett
Post by Jools Enticknap
<snip-answered-queries />
--Jools
--
Brett McLaughlin, Enhydra Strategist
Lutris Technologies, Inc.
1200 Pacific Avenue, Suite 300
Santa Cruz, CA 95060 USA
http://www.lutris.com
http://www.enhydra.org
Jools Enticknap
2000-07-27 08:47:27 UTC
Permalink
<snip/>
Post by Jason Hunter
Post by Jools Enticknap
Post by Jason Hunter
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.
<!-- 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.
OK, I see what you are getting at now.

So to achieve;

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

You would write;

Document doc = new Document();
Comment comment = new Comment("comment");
Element element = new Element("root");

doc.addContent(comment);
doc.addContent(element);
doc.addContent(comment);

Fine happy with that.

But what if you want to change the "root" element ? I'm guessing that I'd
have to do;

Element foo = new Element("foo");

doc.removeContent(element);
doc.addContent(foo);


But won't that end up with;

<!-- comment -->
<!-- comment -->
<foo>

Or have I missed the plot ?


--Jools
Jason Hunter
2000-07-27 08:52:27 UTC
Permalink
Post by Jools Enticknap
OK, I see what you are getting at now.
So to achieve;
<!-- comment -->
<root/>
<!-- comment -->
You would write;
Document doc = new Document();
Comment comment = new Comment("comment");
Element element = new Element("root");
doc.addContent(comment);
doc.addContent(element);
doc.addContent(comment);
Fine happy with that.
You could have issues with double use of the Comment instance should you
get deep into manipulating the document, but basically yes.
Post by Jools Enticknap
But what if you want to change the "root" element ?
How about just
doc.setRootElement(newRoot);

setRootElement() can be smart enough to look for the sole element and
replace it.

-jh-
t***@hifusion.com
2000-07-27 12:13:26 UTC
Permalink
Jools Enticknap
2000-07-27 11:09:55 UTC
Permalink
Post by Jason Hunter
Post by Jools Enticknap
OK, I see what you are getting at now.
So to achieve;
<!-- comment -->
<root/>
<!-- comment -->
You would write;
Document doc = new Document();
Comment comment = new Comment("comment");
Element element = new Element("root");
doc.addContent(comment);
doc.addContent(element);
doc.addContent(comment);
Fine happy with that.
You could have issues with double use of the Comment instance should you
get deep into manipulating the document, but basically yes.
Post by Jools Enticknap
But what if you want to change the "root" element ?
How about just
doc.setRootElement(newRoot);
setRootElement() can be smart enough to look for the sole element and
replace it.
I was under the impression that setRootElement() was going due to the
problems involved in making it behave ?

Anyhow ... so, in order to add the "root" element to a Document you could;

Document doc = new Document();
Element elem = new Element("root")

// Which will call elem.setIsRootElement(true);
doc.setRootElement(elem);

In this scenario we don't get an Exception, because the method is explicit
about what it does.

However.

Document doc = new Document();
Element elem = new Element("root")

try {
doc.addContent(elem);
} catch(IllegalAddException ila) {
// handle the exception or just call setRootElement(elem);
}


addContent(Element) is implicit, it states it'll add an Element to a
document, and set it as the 'root' element unless one is there already,
then it'll throw an exception.

setRootElement(Element) is explicitly stating that it will set the Element
and remove the old Element calling setIsRootElement() on the respective
elements.

So to summarize;

Do we need two methods for setting the Root element of a Document ?

--Jools
Post by Jason Hunter
-jh-
Jason Hunter
2000-07-27 18:01:14 UTC
Permalink
Post by Jools Enticknap
I was under the impression that setRootElement() was going due to the
problems involved in making it behave ?
Problems behaving?
Post by Jools Enticknap
So to summarize;
Do we need two methods for setting the Root element of a Document ?
Well, which would you remove?

-jh-
Chris Atkins
2000-07-27 14:56:47 UTC
Permalink
Post by Jason Hunter
boolean removeContent(String text)
I do not see how removeContent(String) is really going to
work. It seems
you are making an assumption that each String item in the
content has a
unique value. This is not necessarily true. In that case,
you need to be
able to specify which one, or just remove the first one.

Chris Atkins
Jason Hunter
2000-07-27 17:39:34 UTC
Permalink
It does a == check. So it removes the exact string you passed in,
presumably retrieved from getMixedContent(). I say this in the new
Javadocs too.

-jh-
Post by Chris Atkins
Post by Jason Hunter
boolean removeContent(String text)
I do not see how removeContent(String) is really going to
work. It seems
you are making an assumption that each String item in the
content has a
unique value. This is not necessarily true. In that case,
you need to be
able to specify which one, or just remove the first one.
Chris Atkins
_______________________________________________
Chris Atkins
2000-07-27 18:58:49 UTC
Permalink
I guess I am missing something. To get the exact string, I first need to do
a getMixedContent() and find the one I want. Once I do this, I might as
well modify the list and then call the correct method to replace the entire
contents of the element, same thing that you suggested for adding content at
a specific location.

If this is correct, why have the method in the first place?

Chris Atkins
-----Original Message-----
Sent: Thursday, July 27, 2000 12:40 PM
Subject: Re: [jdom-interest] Important proposal: Element/Document
changes
It does a == check. So it removes the exact string you passed in,
presumably retrieved from getMixedContent(). I say this in the new
Javadocs too.
-jh-
Post by Chris Atkins
Post by Jason Hunter
boolean removeContent(String text)
I do not see how removeContent(String) is really going to
work. It seems
you are making an assumption that each String item in the
content has a
unique value. This is not necessarily true. In that case,
you need to be
able to specify which one, or just remove the first one.
Chris Atkins
_______________________________________________
http://lists.denveronline.net/mailman/options/jdom-interest/***@yourhos
t.com
_______________________________________________
To control your jdom-interest membership:
http://lists.denveronline.net/mailman/options/jdom-interest/***@yourhos
t.com
Jason Hunter
2000-07-27 19:31:33 UTC
Permalink
Post by Chris Atkins
To get the exact string, I first need to do
a getMixedContent() and find the one I want. Once I do this, I
might as well modify the list and then call the correct method to
replace the entire
contents of the element, same thing that you suggested for adding
content at a specific location.
If this is correct, why have the method in the first place?
Chris Atkins
Consistency pretty much. If you have a removeContent() for the others,
you should have one for String. But you bring up a good point, do we
need removeContent() methods at all? We need removeChild() and
removeChildren() but do we have a compelling use case for
removeContent(*)?

-jh-

Received: from slim.silverstream.com ([216.142.115.7])
by dorothy.denveronline.net (8.9.3/8.9.3) with ESMTP id NAA00281
for <jdom-***@jdom.org>; Thu, 27 Jul 2000 13:00:54 -0600 (MDT)
Received: by slim.silverstream.com with Internet Mail Service (5.5.2650.21)
id <3PRYCT1G>; Thu, 27 Jul 2000 15:00:52 -0400
Received: from arosen (216.142.115.81 [216.142.115.81]) by slim.silverstream.com with SMTP (Microsoft Exchange Internet Mail Service Version 5.5.2650.21)
id 3PRYCT1C; Thu, 27 Jul 2000 15:00:40 -0400
From: "Rosen, Alex" <***@silverstream.com>
To: jdom-***@jdom.org
Subject: RE: [jdom-interest] Important proposal: Element/Document changes
Date: Thu, 27 Jul 2000 15:02:27 -0400
Message-ID: <000401bff7fd$35ab7980$***@arosen>
MIME-Version: 1.0
Content-Type: text/plain;
charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
X-Priority: 3 (Normal)
X-MSMail-Priority: Normal
X-Mailer: Microsoft Outlook 8.5, Build 4.71.2173.0
X-MimeOLE: Produced By Microsoft MimeOLE V5.50.4133.2400
Importance: Normal
In-Reply-To: <***@dorothy.denveronline.net>
Sender: jdom-interest-***@jdom.org
Errors-To: jdom-interest-***@jdom.org
X-BeenThere: jdom-***@jdom.org
X-Mailman-Version: 2.0beta2
Precedence: bulk
List-Id: JDOM Mailing List for General Issues and Updates <jdom-interest.jdom.org>

I think the proposed changes are great. I wholeheartedly believe that getting
the nuances (like method names) right from the beginning is vital. Thanks for
paying attention to the details and doing things right.

I was unsure for a while, but I now strongly favor getChildElement() and the
like. The differences between content/child/text are subtle and easy to get
confused about. This makes it much more obvious, and will reduce the likelihood
of saying one when you mean the other.

I could live without it, but I would like to see add-at functionality. The
alternative of getChildren() + List.add() + setChildren() is OK, but less
intuitive. (The alternative of getChildren() + List.add() is even stranger IMO -
having the List backed by the JDOM tree will be confusing unless
well-documented.) Also, add() is an optional method on the List interface, so
you'd have to specify that this (and other modification operations) is allowed
on the returned list.

Alex

Received: from slim.silverstream.com ([216.142.115.7])
by dorothy.denveronline.net (8.9.3/8.9.3) with ESMTP id NAA00281
for <jdom-***@jdom.org>; Thu, 27 Jul 2000 13:00:54 -0600 (MDT)
Received: by slim.silverstream.com with Internet Mail Service (5.5.2650.21)
id <3PRYCT1G>; Thu, 27 Jul 2000 15:00:52 -0400
Received: from arosen (216.142.115.81 [216.142.115.81]) by slim.silverstream.com with SMTP (Microsoft Exchange Internet Mail Service Version 5.5.2650.21)
id 3PRYCT1C; Thu, 27 Jul 2000 15:00:40 -0400
From: "Rosen, Alex" <***@silverstream.com>
To: jdom-***@jdom.org
Subject: RE: [jdom-interest] Important proposal: Element/Document changes
Date: Thu, 27 Jul 2000 15:02:27 -0400
Message-ID: <000401bff7fd$35ab7980$***@arosen>
MIME-Version: 1.0
Content-Type: text/plain;
charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
X-Priority: 3 (Normal)
X-MSMail-Priority: Normal
X-Mailer: Microsoft Outlook 8.5, Build 4.71.2173.0
X-MimeOLE: Produced By Microsoft MimeOLE V5.50.4133.2400
Importance: Normal
In-Reply-To: <***@dorothy.denveronline.net>
Sender: jdom-interest-***@jdom.org
Errors-To: jdom-interest-***@jdom.org
X-BeenThere: jdom-***@jdom.org
X-Mailman-Version: 2.0beta2
Precedence: bulk
List-Id: JDOM Mailing List for General Issues and Updates <jdom-interest.jdom.org>

I think the proposed changes are great. I wholeheartedly believe that getting
the nuances (like method names) right from the beginning is vital. Thanks for
paying attention to the details and doing things right.

I was unsure for a while, but I now strongly favor getChildElement() and the
like. The differences between content/child/text are subtle and easy to get
confused about. This makes it much more obvious, and will reduce the likelihood
of saying one when you mean the other.

I could live without it, but I would like to see add-at functionality. The
alternative of getChildren() + List.add() + setChildren() is OK, but less
intuitive. (The alternative of getChildren() + List.add() is even stranger IMO -
having the List backed by the JDOM tree will be confusing unless
well-documented.) Also, add() is an optional method on the List interface, so
you'd have to specify that this (and other modification operations) is allowed
on the returned list.

Alex
Elliotte Rusty Harold
2000-07-27 22:10:04 UTC
Permalink
Post by Jason Hunter
Consistency pretty much. If you have a removeContent() for the others,
you should have one for String. But you bring up a good point, do we
need removeContent() methods at all? We need removeChild() and
removeChildren() but do we have a compelling use case for
removeContent(*)?
I reserve the right to change my mind about this, but part of the
point of JDOM is to increase simplicity by not duplicating methods
and data structures Java, particularly the Java Collections API,
already provides. Following that philosophy would seem to dictate
removing the removeContent() methods.

+-----------------------+------------------------+-------------------+
| Elliotte Rusty Harold | ***@metalab.unc.edu | Writer/Programmer |
+-----------------------+------------------------+-------------------+
| The XML Bible (IDG Books, 1999) |
| http://metalab.unc.edu/xml/books/bible/ |
| http://www.amazon.com/exec/obidos/ISBN=0764532367/cafeaulaitA/ |
+----------------------------------+---------------------------------+
| Read Cafe au Lait for Java News: http://metalab.unc.edu/javafaq/ |
| Read Cafe con Leche for XML News: http://metalab.unc.edu/xml/ |
+----------------------------------+---------------------------------+
Brett McLaughlin
2000-07-28 03:03:33 UTC
Permalink
Post by Chris Atkins
I guess I am missing something. To get the exact string, I first need to do
a getMixedContent() and find the one I want. Once I do this, I might as
well modify the list and then call the correct method to replace the entire
contents of the element, same thing that you suggested for adding content at
a specific location.
If this is correct, why have the method in the first place?
Agreed. removeContent(String text) seems stupid to me. I'm +1 on
removing it, and since noone ever +1ed its addition, I'd like to get it
out of the API. Too confusing, too unreliable.

-Brett
Post by Chris Atkins
Chris Atkins
-----Original Message-----
Sent: Thursday, July 27, 2000 12:40 PM
Subject: Re: [jdom-interest] Important proposal: Element/Document
changes
It does a == check. So it removes the exact string you passed in,
presumably retrieved from getMixedContent(). I say this in the new
Javadocs too.
-jh-
Post by Chris Atkins
Post by Jason Hunter
boolean removeContent(String text)
I do not see how removeContent(String) is really going to
work. It seems
you are making an assumption that each String item in the
content has a
unique value. This is not necessarily true. In that case,
you need to be
able to specify which one, or just remove the first one.
Chris Atkins
_______________________________________________
t.com
_______________________________________________
t.com
_______________________________________________
--
Brett McLaughlin, Enhydra Strategist
Lutris Technologies, Inc.
1200 Pacific Avenue, Suite 300
Santa Cruz, CA 95060 USA
http://www.lutris.com
http://www.enhydra.org
Jason Hunter
2000-07-28 04:00:44 UTC
Permalink
Post by Brett McLaughlin
Agreed. removeContent(String text) seems stupid to me. I'm +1 on
removing it, and since noone ever +1ed its addition, I'd like to
get it out of the API. Too confusing, too unreliable.
It was in the proposal email. But I'm fine with removing it, and
removing all the other removeContent() methods besides. The adds are
convenient, but the removes are better done using the List. You agree?

-jh-
Brett McLaughlin
2000-07-28 15:02:47 UTC
Permalink
Post by Jason Hunter
Post by Brett McLaughlin
Agreed. removeContent(String text) seems stupid to me. I'm +1 on
removing it, and since noone ever +1ed its addition, I'd like to
get it out of the API. Too confusing, too unreliable.
It was in the proposal email. But I'm fine with removing it, and
removing all the other removeContent() methods besides. The adds are
convenient, but the removes are better done using the List. You agree?
I'd like to see what people think on the other removes (I'm deferring to
the community, in other words), but I am defintely for getting rid of
removeContent(String)

-Brett
Post by Jason Hunter
-jh-
_______________________________________________
--
Brett McLaughlin, Enhydra Strategist
Lutris Technologies, Inc.
1200 Pacific Avenue, Suite 300
Santa Cruz, CA 95060 USA
http://www.lutris.com
http://www.enhydra.org
Rafizan Baharum
2000-07-28 16:35:02 UTC
Permalink
hi all,
two quick question..

1) is "space-after.optimum" a valid name for an attribute? i stumble into this when
using FOP from apache..

2) ive tried DOMOuputter and it looks good in my application.( waydagooo guys ;) )
but unfortunately ive got this wierd error when using it in servlet

java.lang.NoSuchMethodError: org.apache.xerces.dom.NodeImpl: method
(Lorg/apache/xerces/dom/DocumentImpl;Ljava/lang/String;Ljava/lang/String;)V not found
at
org.apache.xerces.dom.DocumentImpl.(DocumentImpl.java:157) at
org.apache.xerces.dom.DocumentImpl.(DocumentImpl.java:152) at
java.lang.Class.newInstance0(Native Method) at
java.lang.Class.newInstance(Class.java, Compiled Code) at
org.jdom.adapters.XercesDOMAdapter.createDocument(XercesDOMAdapter.java:149) at
org.jdom.output.DOMOutputter.output(DOMOutputter.java, Compiled Code) at
org.jdom.output.DOMOutputter.output(DOMOutputter.java:114) at


im pretty sure both environemnt( servlet& app) are using the same latest xerces.jar.
...any ideas?

-z00t-
Brett McLaughlin
2000-07-28 16:44:09 UTC
Permalink
Post by Rafizan Baharum
hi all,
two quick question..
1) is "space-after.optimum" a valid name for an attribute? i stumble into this when
using FOP from apache..
2) ive tried DOMOuputter and it looks good in my application.( waydagooo guys ;) )
but unfortunately ive got this wierd error when using it in servlet
java.lang.NoSuchMethodError: org.apache.xerces.dom.NodeImpl: method
(Lorg/apache/xerces/dom/DocumentImpl;Ljava/lang/String;Ljava/lang/String;)V not found
at
org.apache.xerces.dom.DocumentImpl.(DocumentImpl.java:157) at
org.apache.xerces.dom.DocumentImpl.(DocumentImpl.java:152) at
java.lang.Class.newInstance0(Native Method) at
java.lang.Class.newInstance(Class.java, Compiled Code) at
org.jdom.adapters.XercesDOMAdapter.createDocument(XercesDOMAdapter.java:149) at
org.jdom.output.DOMOutputter.output(DOMOutputter.java, Compiled Code) at
org.jdom.output.DOMOutputter.output(DOMOutputter.java:114) at
im pretty sure both environemnt( servlet& app) are using the same latest xerces.jar.
...any ideas?
Make sure that xml.jar isn't in the classpath of Tomcat before
xerces.jar

-Brett
Post by Rafizan Baharum
-z00t-
--
Brett McLaughlin, Enhydra Strategist
Lutris Technologies, Inc.
1200 Pacific Avenue, Suite 300
Santa Cruz, CA 95060 USA
http://www.lutris.com
http://www.enhydra.org
Rafizan Baharum
2000-07-28 17:56:17 UTC
Permalink
hi all,

thanks for the help brett.. its working now..i didnt realize i have compat.jar somewhere in
my classpath..
i have yet to find out why "space-after.optimum" is not a valid name for an attribute. are
JDOM and FOP
not comply to the same working draft or something? (sorry, im new to the XML turf, doing
some stuff for class project ;) )

thanks in advance..

-z00t-
Post by Brett McLaughlin
Post by Rafizan Baharum
hi all,
two quick question..
1) is "space-after.optimum" a valid name for an attribute? i stumble into this when
using FOP from apache..
2) ive tried DOMOuputter and it looks good in my application.( waydagooo guys ;) )
but unfortunately ive got this wierd error when using it in servlet
java.lang.NoSuchMethodError: org.apache.xerces.dom.NodeImpl: method
(Lorg/apache/xerces/dom/DocumentImpl;Ljava/lang/String;Ljava/lang/String;)V not found
at
org.apache.xerces.dom.DocumentImpl.(DocumentImpl.java:157) at
org.apache.xerces.dom.DocumentImpl.(DocumentImpl.java:152) at
java.lang.Class.newInstance0(Native Method) at
java.lang.Class.newInstance(Class.java, Compiled Code) at
org.jdom.adapters.XercesDOMAdapter.createDocument(XercesDOMAdapter.java:149) at
org.jdom.output.DOMOutputter.output(DOMOutputter.java, Compiled Code) at
org.jdom.output.DOMOutputter.output(DOMOutputter.java:114) at
im pretty sure both environemnt( servlet& app) are using the same latest xerces.jar.
...any ideas?
Make sure that xml.jar isn't in the classpath of Tomcat before
xerces.jar
-Brett
Post by Rafizan Baharum
-z00t-
--
Brett McLaughlin, Enhydra Strategist
Lutris Technologies, Inc.
1200 Pacific Avenue, Suite 300
Santa Cruz, CA 95060 USA
http://www.lutris.com
http://www.enhydra.org
Rafizan Baharum
2000-07-28 19:50:22 UTC
Permalink
hi again..

whoops my bad.... downloaded the new version of verifier... ;)
-z00t-
Post by Rafizan Baharum
hi all,
thanks for the help brett.. its working now..i didnt realize i have compat.jar somewhere in
my classpath..
i have yet to find out why "space-after.optimum" is not a valid name for an attribute. are
JDOM and FOP
not comply to the same working draft or something? (sorry, im new to the XML turf, doing
some stuff for class project ;) )
thanks in advance..
-z00t-
Post by Brett McLaughlin
Post by Rafizan Baharum
hi all,
two quick question..
1) is "space-after.optimum" a valid name for an attribute? i stumble into this when
using FOP from apache..
2) ive tried DOMOuputter and it looks good in my application.( waydagooo guys ;) )
but unfortunately ive got this wierd error when using it in servlet
java.lang.NoSuchMethodError: org.apache.xerces.dom.NodeImpl: method
(Lorg/apache/xerces/dom/DocumentImpl;Ljava/lang/String;Ljava/lang/String;)V not found
at
org.apache.xerces.dom.DocumentImpl.(DocumentImpl.java:157) at
org.apache.xerces.dom.DocumentImpl.(DocumentImpl.java:152) at
java.lang.Class.newInstance0(Native Method) at
java.lang.Class.newInstance(Class.java, Compiled Code) at
org.jdom.adapters.XercesDOMAdapter.createDocument(XercesDOMAdapter.java:149) at
org.jdom.output.DOMOutputter.output(DOMOutputter.java, Compiled Code) at
org.jdom.output.DOMOutputter.output(DOMOutputter.java:114) at
im pretty sure both environemnt( servlet& app) are using the same latest xerces.jar.
...any ideas?
Make sure that xml.jar isn't in the classpath of Tomcat before
xerces.jar
-Brett
Post by Rafizan Baharum
-z00t-
--
Brett McLaughlin, Enhydra Strategist
Lutris Technologies, Inc.
1200 Pacific Avenue, Suite 300
Santa Cruz, CA 95060 USA
http://www.lutris.com
http://www.enhydra.org
_______________________________________________
t***@hifusion.com
2000-07-28 16:39:12 UTC
Permalink
Post by Brett McLaughlin
Post by Chris Atkins
I guess I am missing something. To get the exact string, I first need to do
a getMixedContent() and find the one I want. Once I do this, I might as
well modify the list and then call the correct method to replace the entire
contents of the element, same thing that you suggested for adding content at
a specific location.
If this is correct, why have the method in the first place?
Agreed. removeContent(String text) seems stupid to me. I'm +1 on
removing it, and since noone ever +1ed its addition, I'd like to get it
out of the API. Too confusing, too unreliable.
-Brett
+1
Jools Enticknap
2000-07-27 22:07:54 UTC
Permalink
Post by Jason Hunter
Post by Jools Enticknap
I was under the impression that setRootElement() was going due to the
problems involved in making it behave ?
Problems behaving?
<quote>
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.

</quote>

Which is what I was refering to.
Post by Jason Hunter
Post by Jools Enticknap
So to summarize;
Do we need two methods for setting the Root element of a Document ?
Well, which would you remove?
Fruedian slip there I think, I was not advocating the removal of either,
rather I wanted to clarify their use and see if we need two.

I personally think there is a need for them both(now that supprised you
did'nt it !)

I would use the setContent(<type>) methods for creating the initial layout
of the Document, and if I needed to replace __just__ the root I could call
setRootElement() and I'd know that the Document would still be as I
intended it.

For instance;

Imagine that I want to have a Document which has copyright information
before and afer the root Element.

<!-- Copyright Nmemonix Ltd 2000 -->
<root/>
<!-- Copyright Nmemonix Ltd 2000 -->

I could use the following method to make sure that all the documents were
written out with Copy right information as a header and tailer.

void dumpDocuments(Document doc, Vector elems) {

Enumeration e = elems.elements();

while(e.hasMoreElements()) {
Element elem = (Element) e.nextElement();

doc.setRootElement(elem);
dumpDocument(doc);
}

}


But in order to create the Document in the first place I would want to
specify the order of the Comments and the place holder root Element by
using setContent() in the order in which I would want them to appear in
the Document.

doc.setContent(comment);
doc.setContent(new Element("root"));
doc.setContent(comment);


So there might be a reason to have both.

Comments ?


--Jools
Post by Jason Hunter
-jh-
_______________________________________________
p***@omniresources.com
2000-07-28 17:16:14 UTC
Permalink
Post by Brett McLaughlin
I'd like to see what people think on the other removes (I'm
deferring to
the community, in other words), but I am defintely for getting rid of
removeContent(String)
We seem to be house cleaning
+1

We should make it obvious through examples somewhere how this is to be done
though because browsing the JavaDoc or looking at the methods will not make
it obvious.
Jason Hunter
2000-12-06 04:33:20 UTC
Permalink
I propose to add doc.removeContent() methods for all types except Entity
and Element. The methods were recently put back in Element and it would
make sense following the same logic the person-whose-email-I-can't-find
used to get them into Element to have them in Document too.

I would not do removeContent(Entity) because entities can't exist at the
document level. We don't have addContent(Entity) either.

I would not do removeContent(Element) because it would result in a
malformed document and the current strategy at least is to not allow
malformed documents. (I expect we'll revisit that later.)

I think we should also probably get rid of doc.addContent(Element)
because it can never succeed when called on a well-formed document. We
have setRootElement() for that.

Any concerns?

-jh-

Continue reading on narkive:
Loading...