Glueing code for plugging together an
xantlr generated parser and a
tdom generated xml model.
The usage is documented with the methods
and with the user
documentation of tdom.
Why not "endDocument()" generated automatically by "parser.eventGenerator()" ?
parser - an X_LLkParser which is already instantiated with the
lexer, and this lexer in turn with the source stream which shall be parsed later.
(So also a XantlrTdom is a use-once-throw-away kind of object!)
antlrMessages - a mssage receiver into which the parsing errors generated
by the parser shall flow. (These errrors are quite frequent, because they
depend on the correctness of the user's (looser's) input !-)
queueSize - regulates the size of the
SAXEventQueue which will be created
as a buffer.
debugSaxEvents - is a second drain for sax events which can be used for
debugging. All SAX events generated by xantlr and fed to tdom will
be tee-ed to this drain.
(Please note: If you use a
ContentPrinter, then it will be useful
for debugging only if you plug it to a
PrintWriter_flushing, since the
implementation of streams on the varying platforms is full of surprises !-)
tdomDtdModel - is the tdom.runtime.TypedDTD containing the parsing
method. This method will be found be reflection and activated in
a second thread, as described with the
tdomMessages - is a msssage receiver into which the errors generated by
the tdom SAX receiver and validator are fed.
(In contrast to the user generated errors fed into "xantlrMessages",
these errors should normally NOT happen, because
both codes, the parser and the tdom model, have been generated
by our tools, and so errors are unlikely !-)
If one of the two MessageReceiver arguments is omitted, the other takes
Both can be set to the same MessageReceiver, because synchronization is
maintained by the glueing code.
This method initiates the parsing process, and supplies additional
( For a pure operational point of view, this method and the
link() method could be unified, because there is only one
sensible calling sequence, namely XantlrTdom.link(...).parse(...);
Nevertheless, we keep them separate to plug in future extensions (e.g.
w.r.t parameters) more easily !-)
The parsing process is carried out in a spawned thread.
The document creation process is carried out in the main thread.
(because the method may not return before this process is finished!)
Throwables thrown in either process are carefully caught, sorted
and fed (as Message objects) into the corresponding MessageReceivers,
so no Throwables should be emitted by this method.
parseFunctionName - a String giving the name of that parse function
as generated by the antlr tool which corresponds to the start symbol
(nonterminal) of the parsing process. The method will be looked-up
and invoked using reflection.
documentClass - is the tdom generated class which corresponds to
the document to generate.
systemId - is the string which is used in the locators in all text
position related messages.