[jdom-interest] getAttributeValue(): wrong signatures?

[Elliotte Rusty Harold]

I recently wrote the following code for an example program without 
looking at the JavaDocs:

  public final static String XLINK_NAMESPACE   = 
"http://www.w3.org/1999/xlink";

// ...

       String href    = input.getAttributeValue("href", XLINK_NAMESPACE);
       String title   = input.getAttributeValue("title", XLINK_NAMESPACE);
       String role    = input.getAttributeValue("role", XLINK_NAMESPACE);
       String arcrole = input.getAttributeValue("arcrole", XLINK_NAMESPACE);

It compiled, but it exhibited strange runtime errors. Specifically, it 
output the XLink namespace URI repeatedly instead of the values of the 
various attributes.

What's going on is that the signature getAttributeValue(String, String) 
does not indicate what to me is the most natural possibility:

public String getAttributeValue(String localName, String namespaceURI)

Instead it has this signature:

public String getAttributeValue(String localName, String defaultValue)

At least for me, this violates the principal of least surprise. When I'm 
writing code I'm a lot more likely to ask for an attribute by name and 
namespace URI than I am to ask for attribute by name only+default value. 
Furthermore, when I'm guessing what the correct signature is for 
requesting an attribute by name and URI, I'll likely come up with 
getAttributeValue(String localName, String namespaceURI). I don't think 
I'd eever guess that there was an option to supply a default value. I 
twouldn't occur to me to even ask the question. It's perhaps a nice 
little convenience, but it's not a fundamental peice of funcitonality 
for an XML API. Asking ofr an attribute by name and URI is fundamental, 
and really deserves to have the signature.

Another problem, is that this is a really significant method call that 
really requires the user to be familar with the Namespace class. In 
fact, I'm not sure if anyother classes actually require the developer to 
be familar with Namespace at all. For instance, you can use a Namespace 
object when constructing an Element object, but you can also use raw 
strings. This is one of the few places in the API where there's no raw 
string alternative for the namespace.

I suggest that the two-string argument version of getAttributeValue() 
use the second string as a namespace URI and that we simply remove the 
default strings from getAttributeValue().

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