[jdom-interest] DOMAdapter weirdness

[Elliotte Rusty Harold]

The abstract DOMAdapter interface and by extension its implementing 
classes feels strange to me. There are two problems:

1. It provides methods to read a DOM Document from a File and an 
InputStream:

public org.w3c.dom.Document *getDocument*(java.io.File filename, 
boolean validate)
  throws java.io.IOException, JDOMException 
<cid:part1.05050007.04070000 at metalab.unc.edu>


public org.w3c.dom.Document *getDocument*(java.io.InputStream in, 
boolean validate)
 throws java.io.IOException, JDOMException 
<cid:part2.09080205.03060100 at metalab.unc.edu>

We deprecated this behavior in DOMBuilder. Should we also deprecate it 
here  (and in the implementation classes) and later remove it? Are these 
methods being used anywhere except in the deprecated parts of DOMBuilder?

2. The createDocument() methods  do not really follow the DOM patterns. 
They create rootless documents.  Should we/could we revise the signature 
as follows:

public org.w3c.dom.Document createDocument(String namespaceURI, String 
rootElementPrefix,  String rootElementName, DocType doctype ) throws 
JDOMException
public org.w3c.dom.Document createDocument(org.jdom.Element root, , 
DocType doctype) throws JDOMException

 This would allow us to put a lot more of the functionality directly in 
the AbstractDOMAdapter superclass and be more extensible to other DOMs 
in the future. Furthermore, it would be much more robust against 
internal changes in various DOM implementations since we would not be 
relying on undocumented internals but only on the documented behavior of 
DOM Level 2. (We'd still need the internals for a few operations like 
setting the internal DTD subset that DOM Level 2 doesn't support.)

This would also require changing DOMOutputter to match. I doubt any 
clients are relying on these classes and methods directly rather than 
via DOMOutputter, but if they are, they'll still have the deprecated 
methods for at least one build cycle.

Thoughts?

-- 
+-----------------------+------------------------+-------------------+
| Elliotte Rusty Harold | elharo at metalab.unc.edu | Writer/Programmer |
+-----------------------+------------------------+-------------------+ 
|           The XML Bible, 2nd Edition (IDG Books, 2001)             |
|             http://www.cafeconleche.org/books/bible2/              |
|   http://www.amazon.com/exec/obidos/ISBN=0764547607/cafeaulaitA/   |
+----------------------------------+---------------------------------+
|  Read Cafe au Lait for Java News:   http://www.cafeaulait.org/     | 
|  Read Cafe con Leche for XML News:  http://www.cafeconleche.org/   |
+----------------------------------+---------------------------------+