eu.bandm.tools.xantlrtdom

Class XantlrTdom

java.lang.Object

eu.bandm.tools.xantlrtdom.XantlrTdom

@Runtime
public class XantlrTdom
extends Object

Glueing code for plugging together an xantlr generated parser and a tdom generated xml model. The usage is documented with the methods link and parse() and with the user documentation of tdom.
internal ml->bt
Why not "endDocument()" generated automatically by "parser.eventGenerator()" ?

Field Summary

Fields

Modifier and Type	Field and Description
protected static Class[]	NOPARAMS
protected static Class[]	PARAM_SAXEVENTSTREAM

Constructor Summary

Constructors

Constructor and Description
XantlrTdom()

Method Summary

Modifier and Type	Method and Description
protected <D> void	init(X_LLkParser parser0, MessageReceiver<? super SimpleMessage<XMLDocumentIdentifier>> antlrMessages, int queueSize, ContentHandler debugSaxEvents, TypedDTD tdomDtdModel, MessageReceiver<? super SimpleMessage<XMLDocumentIdentifier>> tdomMessages)
static XantlrTdom	link(X_LLkParser parser, MessageReceiver<? super SimpleMessage<XMLDocumentIdentifier>> antlrMessages, int queueSize, ContentHandler debugSaxEvents, TypedDTD tdomDtdModel, MessageReceiver<? super SimpleMessage<XMLDocumentIdentifier>> tdomMessages) This method creates a XantlrTdom object, which subsequently will be used to parse a source text (with an xantlr generated parser, see Xantlr user documentation., and to generate a corresponding tdom model, see Tdom user documentation..
<D extends TypedDocument> D	parse(String parseFunctionName, Class<D> documentClass)
<D extends TypedDocument> D	parse(String parseFunctionName, Class<D> documentClass, String systemId) This method initiates the parsing process, and supplies additional arguments.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NOPARAMS

protected static final Class[] NOPARAMS

PARAM_SAXEVENTSTREAM

protected static final Class[] PARAM_SAXEVENTSTREAM

Constructor Detail

XantlrTdom

public XantlrTdom()

Method Detail

link

public static XantlrTdom link(X_LLkParser parser,
                              MessageReceiver<? super SimpleMessage<XMLDocumentIdentifier>> antlrMessages,
                              int queueSize,
                              ContentHandler debugSaxEvents,
                              TypedDTD tdomDtdModel,
                              MessageReceiver<? super SimpleMessage<XMLDocumentIdentifier>> tdomMessages)

This method creates a XantlrTdom object, which subsequently will be used to parse a source text (with an xantlr generated parser, see Xantlr user documentation., and to generate a corresponding tdom model, see Tdom user documentation..

Parameters:

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 parse() method.

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 roles. Both can be set to the same MessageReceiver, because synchronization is maintained by the glueing code.

init

protected <D> void init(X_LLkParser parser0,
                        MessageReceiver<? super SimpleMessage<XMLDocumentIdentifier>> antlrMessages,
                        int queueSize,
                        ContentHandler debugSaxEvents,
                        TypedDTD tdomDtdModel,
                        MessageReceiver<? super SimpleMessage<XMLDocumentIdentifier>> tdomMessages)

parse

public <D extends TypedDocument> D parse(String parseFunctionName,
                                         Class<D> documentClass,
                                         String systemId)

This method initiates the parsing process, and supplies additional arguments.
( 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.

Parameters:

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.

parse

public <D extends TypedDocument> D parse(String parseFunctionName,
                                         Class<D> documentClass)