[XOM-interest] Builder.build(String) is misleading

[cowwoc]

Hi,

I propose removing Builder.build(String) because it is misleading.
I am willing to bet that 99% of new users fall into the trap of using
this method to parse an XML document from a String only to find out that
the String actually represents a URL.

1. If you're expecting a URL, why not just ask for one instead of a
String?
2. It doesn't help that if you pass in an XML document you end up
with a cryptic error message.

Am I the first person to bring this up?

Gili

[Elliotte Rusty Harold]

Hi,
? ? I propose removing Builder.build(String) because it is misleading.
I am willing to bet that 99% of new users fall into the trap of using
this method to parse an XML document from a String only to find out that
the String actually represents a URL.

Without arguing the merits of your proposal, it's simply too late. I'm
not going to make such a backwards incompatible change.

[Nils Kilden-Pedersen]

Post by Elliotte Rusty Harold
Without arguing the merits of your proposal, it's simply too late. I'm
not going to make such a backwards incompatible change.

What would be wrong with adding a new build method that takes a URL (or URI)
and deprecating the old one? Wouldn't break any builds, but would fix the
issue that the OP brought up.

[Michael Kay]

Post by Nils Kilden-Pedersen
What would be wrong with adding a new build method that takes
a URL (or URI) and deprecating the old one? Wouldn't break
any builds, but would fix the issue that the OP brought up.

People who can't be bothered to read the spec before calling the method are
hardly going to start doing so just because the method is deprecated.

Regards,

Michael Kay
http://www.saxonica.com/
http://twitter.com/michaelhkay

[Elliotte Rusty Harold]

Post by Nils Kilden-Pedersen
What would be wrong with adding a new build method that takes a URL (or URI)
and deprecating the old one? Wouldn't break any builds, but would fix the
issue that the OP brought up.

I could probably be talked into adding an extra build(URL) method if a
lot of folks wanted it.

I don't see a compelling reason to deprecate the old one though.

[cowwoc]

Post by Elliotte Rusty Harold

Post by Nils Kilden-Pedersen
What would be wrong with adding a new build method that takes a URL (or URI)
and deprecating the old one? Wouldn't break any builds, but would fix the
issue that the OP brought up.

I could probably be talked into adding an extra build(URL) method if a
lot of folks wanted it.
I don't see a compelling reason to deprecate the old one though.

Elliotte,

Why not ask your users:

1. How many of them use this method (today)?
2. How many of them used this method incorrectly when they first tried XOM?

I suspect that you will find that few people build Documents from a
URL in the first place, and that most of your users thought that
Builder.build(String) was used to build a Document from a String buffer.
If that is the case, deprecating the method will do more good than harm
to most of your users.

Gili

[Michael Kay]

Post by cowwoc
1. How many of them use this method (today)?
2. How many of them used this method incorrectly when they
first tried XOM?

Excuse me being a little rude, but that question seems rather naive.

(1) Do you seriously imagine that the developer of a library like XOM knows
who the users are or has any way of communicating with them? I'd be
surprised if as many as 1% of users are on this list.

(2) What kind of figure do you think would justify an incompatible change to
the interface? Let's say 90% for the sake of argument.

(2a) Do you seriously think Elliotte is prepared to make 10% of his users'
applications fail by introducing an incompatible change?

(2b) Do you really imagine that the figure could possibly be as high as
this? It's very easy to imagine when you make a programming mistake that
everyone else is making the same mistake. But it doesn't work that way. Of
the users who try to use this method, let's say 50% read the documentation,
and 50% guess. Of the 50% who guess, the chances are that half guess
correctly. So a much more reasonable estimate of the number of users making
this mistake would be 25%. Not nearly enough to justify an incompatible spec
change.

Regards,

Michael Kay
http://www.saxonica.com/
http://twitter.com/michaelhkay