Figured I ought to tell folks what these are about. Apologies for the terse
language...
These are a proposed replacement for the CoroutineParser, written in an
effort to simplify the calling conventions -- we've been finding the old
version a bit more baroque, and confusing, than we really need.
Only operates in filtering mode. Inialized via normal method calls. The
only coroutine transaction is deliverMoreNodes() -- pass in true to request
more, false to halt parsing; get back true if parse is still in progress,
false if parsing was halted by end of document or user request. (Note that
returned false means there WILL NOT be more events delivered after that
time, even if you call deliverMoreNodes(true) again.)
ISSUE: deliverMoreNodes() currently returns an object -- Boolean.TRUE,
Boolean.FALSE, or an exception. We could instead return a single-bit
boolean, and throw the exception if one arises. That would be more
efficient and java-idiomatic, but would complicate coding slightly on
the caller's end. I think I'm in favor of making this change, but I'd
welcome opinions.
No "restart" dialog (which simplifies the end-of-parsing sequence
_considerably_!). Want another parse? Get another IncrementalSAXSource;
they're cheap. (Actually, the Xerces-specific version is restartable, and
it may be posible to add that to the filtering version in the future.)
Convenience methods are provided to encapsulate binding to and launching a
parser. In the filter version, it launches the parser in a thread -- and
takes advantage of the fact that it knows this was done to use the faster
stop-via-exception solution when deliverMoreNodes(false) is called. In the
Xerces version,
Coroutine details are mostly swept under the covers of the filter
implementation. You can tell it to use a specific CoroutineManager and/or
coroutine ID numbers if you really insist on doing so; if not it should
obtain these automagically and Do The Right Thing.
ISSUE: I'm not 100% sure this "implied init()" will interact properly
with the startup sequencing (see next paragraph). Don't trust it, for
now.
Filter automatically handles the "don't deliver any events until the first
deliverMoreNodes() request is made" issue, to guard against timing
problems. (startDocument pauses before delivery.)
Haven't yet started cutting over Xalan code to the new system. Should be
straightforward. We aren't using doParse(), so that isn't an issue. Replace
doMore() with deliverMoreNodes(). Delete calls to doTerminate(). Eliminate
any try-to-finish-the-dialog loops. Trust the returned "false". And get rid
of the startup hack since that's now built in (see previous paragraph).
