Package eu.bandm.tools.xantlrtdom

Class XantlrTdom

java.lang.Object
eu.bandm.tools.xantlrtdom.XantlrTdom
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 Details

  • Constructor Details

    • XantlrTdom

      public XantlrTdom()

  • Method Details

    • 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)