[jdom-interest] Surprise with filter and namespace - a bit more Javadoc

[Wolfgang.Frech at xenium.de]

On the way to simple code, a funny thing happened to me:

I shortened
      root.getContent(new ElementFilter(LEAF))
to
      root.getChildren(LEAF)
and ...
all my content vanished.

More precisely: my unit tests were still running after the change, but when
processing the real input file, no more content was found.What was the
difference? The real file used namespaces, my unit tests did not.


So I had a second look at the API documentation;

ElementFilter.ElementFilter(String name)   Select only the Elements with
the supplied name in any Namespace.

Element.getChildren(String name)
returns a List of all the child elements nested directly (one level deep)
within this element with the given local name and belonging to no
namespace, returned as Element objects.

Note the difference:
getContent with an ElementFilter selects Elements in _any_ Namespace
getContent with a name directly selects Elements in an _empty_ Namespace

Of course, when you know the namespace and use it explicitly, both veriants
give the same result.


I would like to propose a bit more documentation along these lines:


1) Element.getChildren(String name)
...
Note that this method will not return Elements belonging to a non-empty
Namespace. If the Namespace is known use getChildren(String name, Namespace
namespace) instead. For example, if the parent and the children belong to
the same Namespace then query the parent Element for its Namespace and use
it in the call. If the Namespace is not known, or if the Namespace is not
relevant, use getContent(Filter filter) and an ElementFilter.
...
@see tags for the references


2) Element.getChildren(String name)
...
Note that ElementFilter.ElementFilter(String name) does not use the
Namespace of the Element as a criterion. Specically, it returns Elements
with a non-empty Namespace, as long as the local name is equal. If only
Elements with an empty Namespace should be returned use
FilterElement(String name, Namespace ns) and the Namespace.NO_NAMESPACE
constant, or Element.getChildren(Sting name).
...
@see tags for the references


Could someone include this in the source?

TestCase included below

--
Wolfgang Frech


public class JdomNamespaceSurprise extends TestCase {
      private static final String LEAF = "leaf";

      private static final Namespace NAMESPACE = Namespace.getNamespace
("ns",
                  "http://example.org/ns");
      private final Element root = new Element("root", NAMESPACE);
      private Element leaf = new Element(LEAF, NAMESPACE);

      public void testSurprise() {
            root.addContent(leaf);

            // children in _any_ namespace
            assertEquals(1, root.getContent(new ElementFilter(LEAF)).size
());
            // children in _empty_ namespace
            assertEquals(0, root.getChildren(LEAF).size());

            // with known and given namespace, all is well
            assertEquals(1, root.getChildren(LEAF, NAMESPACE).size());
            assertEquals(1, root.getContent(new ElementFilter(LEAF,
NAMESPACE))
                        .size());
      }
}