different return from docs description when passing null namespace, method: Element.getChild(java.lang.String cname, Namespace ns)

[rekhubs]

Consider the code snippet below (last 3 lines), the doc says, "A null implies Namespace.NO_NAMESPACE", but I was getting a child if passing explict null, while no hits passing Namespace.NO_NAMESPACE.

ns - Namespace to search within. A null implies Namespace.NO_NAMESPACE.

http://www.jdom.org/docs/apidocs/org/jdom2/Element.html#getChild(java.lang.String,%20org.jdom2.Namespace)

static final String ZOO_XML_STRING = "<ns1:zoo xmlns:ns1=\"namespace1\" xmlns:ns2=\"namespace2\" xmlns:ns3=\"namespace3\">\n" +
            "\t<ns2:animal>\n" +
            "\t\t<ns3:name>python</ns3:name>\n" +
            "\t\t<ns3:age>1</ns3:age>\n" +
            "\t</ns2:animal>\n" +
            "\t<ns2:animal>\n" +
            "\t\t<ns3:name>elephant</ns3:name>\n" +
            "\t\t<ns3:age>2</ns3:age>\n" +
            "\t</ns2:animal>\n" +
            "</ns1:zoo>";


    @Test
    public void jDomTests() throws JDOMException, IOException {
        SAXBuilder jdomBuilder = new SAXBuilder();
        Document zooDoc = jdomBuilder.build(new StringReader(ZOO_XML_STRING));
        Element zooEle = zooDoc.getRootElement();
        Namespace ns2 = zooEle.getNamespace("ns2");
        assertNull(zooEle.getChild("animal"));
        assertNotNull(zooEle.getChild("animal", ns2));
        assertNull(zooEle.getChild("animal", Namespace.NO_NAMESPACE));
        assertNotNull(zooEle.getChild("animal", null));    //  <-- getting a child
        System.out.println(zooEle.getChild("animal", null).getName());
    }

[Jason Hunter]

Yes, if you follow the code path getChild(cname, ns) uses ElementFilter internally and just passes through the second argument and ElementFilter has logic where a null namespace acts like a wildcard. If you just call getChild(cname) then it explicitly uses NO_NAMESPACE. Could change behavior or change the docs.

[rekhubs]

Yes, if you follow the code path getChild(cname, ns) uses ElementFilter internally and just passes through the second argument and ElementFilter has logic where a null namespace acts like a wildcard. If you just call getChild(cname) then it explicitly uses NO_NAMESPACE. Could change behavior or change the docs.

Thanks for your explanation!
I found this wildcard very useful, because I was just searching for method "get child of any namespace", that's what getChild(cname, null) is doing.

[Jason Hunter]

Well cool! That's the design of ElementFilter, for exactly that use case. If you want NO_NAMESPACE matching you can pass it.

[Rolf Lear]

Will change docs.