DO NOT REPLY TO THIS EMAIL, BUT PLEASE POST YOUR BUG RELATED COMMENTS THROUGH THE WEB INTERFACE AVAILABLE AT <http://nagoya.apache.org/bugzilla/show_bug.cgi?id=6774>. ANY REPLY MADE TO THIS MESSAGE WILL NOT BE COLLECTED AND INSERTED IN THE BUG DATABASE.
http://nagoya.apache.org/bugzilla/show_bug.cgi?id=6774 please clarify / correct the javadoc (setAttributeNS, createElementNS, sax DefaultHandler) Summary: please clarify / correct the javadoc (setAttributeNS, createElementNS, sax DefaultHandler) Product: Xerces2-J Version: 2.0.0 Platform: All OS/Version: All Status: NEW Severity: Normal Priority: Other Component: Other AssignedTo: [EMAIL PROTECTED] ReportedBy: [EMAIL PROTECTED] Trying to use the methods org.w3c.dom.Document.createElementNS(), and org.w3c.dom.Element.setAttributeNS() for the first time, I had a number of problems due to trickiness of the whole namespace spec, the meaning of qualified vs unqualified names. It would be vastly helpful if the documentation for these and other NS functions was a little more detailed on the implications of what you put into the "qualifiedName" parameter. It was not clear to me looking at the javadoc whether this parameter was asking for the namespace prefix or not. I did some hunting on the web, and got the impression that it needed the prefix (the word qualified would seem to imply something requires qualification by something). However after some adventures trying to figure out why building a document this way and serializing it out resulted with undesired namespace prefixes on all my attributes and elements (see the previous bug I created and closed), I was told, by someone with a deeper reading of the spec than I have, that a qualifiedName was "optionally preceded by a namespace prefix and colon character." Also that the DOM actually maintaints the information of whether an element is prefixed or not (intuitively, I'd have expected this to be immaterial to the DOM tree model, and be an issue for the serializer to worry about.) If the javadoc clarified this it would be immensely helpful. Attributes seem (again I rely on information from other purporting to understand the specs) to be a slightly different issue, in that they are not bound by the namespace of the schema in which they were declared. To quote their example: Consider <a xmlns="http://my.com"; b="myAttribute"/> Here, element a is indeed bound to the http://my.com namespace. But the attribute b is *not* in that namespace--it's still in the null namespace. If b is required to be in the http://my.com namespace then it *must* be prefixed. That's just how the namespace spec is written. The reason is that most people want attributes to be in the null namespace, since they're already associated with specific elements anyway. (end of quoted example) The implications of this is that when one has a schema with a namespace, one should build the elements with createElementNS() but the attributes with setAttribute() (without the NS) This also could be touched on in the JavaDoc and save the majority of programmers who do not grasp the oddities of the namespace spec from doing the wrong thing. I expect these comments apply also to a number of other NS methods in the dom. Finally I want to point out that the javadoc for org.xml.sax.helpers.DefaultHandler.startElement() has been wrong for as long as I can remember. The parameters in the "Parameters:" section do not match the parameters in the actual method declaration section. The same method docs in ContentHandler are closer but still slightly off. But assuming this gets corrected, it might also be helpful to have some of the same explication about qualifiedNames here as I'm suggesting for in the docbuilder methods. Thanks, Eric --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
