[XOM-interest] c'tor Builder( org.xml.sax.XMLReader [...] )

[Michael Ludwig]

The documentation for those constructors of nu.xom.Builder that take an
instance of org.xml.sax.XMLReader as first parameter promises that the
resulting builder will read data from the specified parser object.

Not quite true.

Maybe the documentation should reflect the fact that XOM will replace an
existing ContentHandler and put its own ContentHandler in place. So if
the user wants to control the parsing process, he should supply an
XMLFilter, not an XMLReader.

* Don't care what parser? Don't supply any.
* Want a specific parser, like Xerces? Supply an implementation class of
XMLReader without setting up any handlers on it.
* Want specific parsing behaviour? Supply your custom XMLFilter wrapping
a stock XMLReader of your choice.

[Elliotte Rusty Harold]

Post by Michael Ludwig
The documentation for those constructors of nu.xom.Builder that take an
instance of org.xml.sax.XMLReader as first parameter promises that the
resulting builder will read data from the specified parser object.
Not quite true.
Maybe the documentation should reflect the fact that XOM will replace an
existing ContentHandler and put its own ContentHandler in place. So if
the user wants to control the parsing process, he should supply an
XMLFilter, not an XMLReader.

I'm not sure if this is a misunderstanding, a documentation bug, or an
implementation bug. Do you have a test case that demonstrates the
divergence between what you think should happen and what does happen?

[Elliotte Rusty Harold]

Post by Michael Ludwig
Maybe the documentation should reflect the fact that XOM will replace an
existing ContentHandler and put its own ContentHandler in place. So if
the user wants to control the parsing process, he should supply an
XMLFilter, not an XMLReader.

Looking closer I think this qualifies as a misunderstanding. XOM only
promises to use the parser. It never promises to use the supplied
ContentHandler on that parser. I'm open to suggested changes in the
wording though.

[Michael Ludwig]

Post by Elliotte Rusty Harold

Post by Michael Ludwig
Maybe the documentation should reflect the fact that XOM will
replace an existing ContentHandler and put its own ContentHandler
in place. So if the user wants to control the parsing process, he
should supply an XMLFilter, not an XMLReader.

Looking closer I think this qualifies as a misunderstanding. XOM only
promises to use the parser. It never promises to use the supplied
ContentHandler on that parser.

True. That was my misunderstanding.

Post by Elliotte Rusty Harold
I'm open to suggested changes in the wording though.

Maybe a short addition:

"Note that if you want to filter the SAX event stream which the XOM
document will be built from, you have to supply an XMLFilter instead
of a plain XMLReader with a content handler in place as XOM will
replace any existing content handler by its own content handler."

This is how SAX is supposed to be used anyway, but having used it very
little, I had forgotten about this detail. Now that I remember, I know
that using the parser is not the same as using the content handler.
But maybe others could benefit from more clear-cut wording as well.