XOM API for Processing XML with Java

[Elliotte Rusty Harold <elharo AT metalab.unc.edu>]

I've noticed something funny about the behavior of the insertChild() 
method in Document when used to insert a DocType object. Currently, 
it removes any existing DocType object, which is necessary because a 
Document can have only one DocType. However, this has an unexpected 
side effected. Consider this code:

Document doc = new Document(new Element("root"));
doc.insertChild(new DocType("root"), 0);
doc.insertChild(new Comment("Hello!"), 1);
doc.insertChild(new DocType("test"), 2);
System.out.println(doc.indexOf(doc.getDocType()));

This prints 1, not 2 because the insertion also removed the original DocType.

This is a corner case, but it still feels wrong to me. My gut is that 
insertChild(0 should throw an exception when you try to add a second 
DocType. It should not silently throw the old one away. 
replaceChild(oldDocType, newDocType)
would still work, as would inserting a DocType into a Document that 
does not yet have one.

To make this all slightly easier, I could add a setDocType method to 
match the current getDocType. This would replace any existing 
DocType, and probably make the DocType the first child of the 
Document if none currently existed. This mirrors the behavior of 
setRootElement. I suspect most users would simply call setDocType and 
never notice that insertChild() threw an exception. Thoughts?
--

  Elliotte Rusty Harold
  elharo AT metalab.unc.edu
  Processing XML with Java (Addison-Wesley, 2002)
  http://www.cafeconleche.org/books/xmljava
  http://www.amazon.com/exec/obidos/ISBN%3D0201771861/cafeaulaitA