[jdom-interest] Comments on XPath API

[Elliotte Rusty Harold]

As Jason requested, here are some comments on the proposed XPath API for 
JDOM:

1. Exceptions should be a specific subclass of JDOMException;
e.g. org.jdom.xpath.XPathException extends JDOMException, not just
a generic JDOMException

2. Why bother with factory method? Because it's an abstract class. OK, why
is the XPath class abstract?

I have to say this increasing push to make everything
interfaces and to use factory classes instead of constructors really 
bugs me.
This design pattern is a significant factor in DOM's complexity and 
confusion.
We shouldn't duplicate that unless there's a very strong use-case for it.
As demonstrated by SAXBuilder and my recently submitted XSLTransform class,
it is possible to support multiple implementations and still keep the 
JDOM API
concrete.

3. What happens if we pass a document containing EntityRefs to XPath? An 
exception?
This needs to be documented. Possibly, there should be a statement like,
"The XPath model requires all entity references to be resolved. 
Attempting to search
a Document that contains EntityRef objects will throw an XPathException."

4. What do selectSingleNode() and selectNodes() do if the XPath expression
returns a namespace node? e.g. namespace::*? The JavaDoc indicates these 
methods
cannot return a Namespace. (I'd test some of this out but so far I 
haven't been
able to get the XPath API to actually work. Possibly that's a conflict 
with a different
version of Jaxen than JDOM expects.)

5. What do selectSingleNode() and selectNodes() do if the XPath expression
returns a result that crosses several Text/CDATA node boundaries?

6. setVariable() should throw IllegalNameException, not just
IllegalArgumentException; and possibly setting the variable value should 
throw an
IllegalDataException too. Furthermore, we should document what types can
be provided to match the underlying XPath types; e.g. Double, Float,
Integer, Long, etc., String, Boolean, Element, CDATA, Text, Attribute,
List, etc.

7. selectSingleNode() should be renamed selectFirstNode()

8. Very important: Are the nodes returned live or not? We need to specify .

9. The class name is redundant (org.jdom.xpath.XPath) It should be
org.jdom.xpath.Expression or maybe move it into the core as org.jdom.XPath.
However, org.jdom.xpath.Expression suggests future extensions with
org.jdom.xpath.Function, org.jdom.xpath.Variable, etc.

10. The booleanValueOf() method is missing. The valueOf() method should 
be renamed
stringValueOf().

-- 
+-----------------------+------------------------+-------------------+
| 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/   |
+----------------------------------+---------------------------------+