Builder
Date: 2016-07-03

com.icl.saxon.om

## Class Builder

- java.lang.Object
- - com.icl.saxon.output.Emitter
  - - com.icl.saxon.om.Builder

- All Implemented Interfaces:
    javax.xml.transform.Result, javax.xml.transform.SourceLocator, org.xml.sax.ErrorHandler, org.xml.sax.Locator
  Direct Known Subclasses:
    TinyBuilder, TreeBuilder

      public abstract class Builder
      extends Emitter
      implements org.xml.sax.ErrorHandler, org.xml.sax.Locator, javax.xml.transform.SourceLocator

  The abstract Builder class is responsible for taking a stream of SAX events and constructing a Document tree. There is one concrete subclass for each tree implementation.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `columnNumber`
    `protected Controller` | `controller`
    `protected DocumentInfo` | `currentDocument`
    `protected boolean` | `discardComments`
    `protected org.xml.sax.ErrorHandler` | `errorHandler`
    `protected javax.xml.transform.ErrorListener` | `errorListener`
    `protected java.io.Writer` | `errorOutput`
    `protected int` | `estimatedLength`
    `protected boolean` | `failed`
    `protected boolean` | `inDTD`
    `protected int` | `lineNumber`
    `protected boolean` | `lineNumbering`
    `protected PreviewManager` | `previewManager`
    `static int` | `STANDARD_TREE`
    `protected boolean` | `started`
    `protected Stripper` | `stripper`
    `protected boolean` | `timing`
    `static int` | `TINY_TREE`

    - ### Fields inherited from class com.icl.saxon.output.Emitter

      `locator, namePool, outputProperties, outputStream, systemId, writer`

    - ### Fields inherited from interface javax.xml.transform.Result

      `PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Builder()` create a Builder and initialise variables

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `DocumentInfo` | `build(javax.xml.transform.sax.SAXSource source)` Build the tree from an input source.
    `void` | `error(org.xml.sax.SAXParseException e)` Callback interface for SAX: not for application use
    `void` | `fatalError(org.xml.sax.SAXParseException e)` Callback interface for SAX: not for application use
    `int` | `getColumnNumber()`
    `DocumentInfo` | `getCurrentDocument()` Get the current document
    `int` | `getLineNumber()`
    `java.lang.String` | `getPublicId()`
    `Stripper` | `getStripper()` Get the Stripper in use
    `boolean` | `isTiming()` Get timing option
    `protected void` | `reportError(org.xml.sax.SAXParseException e, boolean isFatal)` Common routine for errors and fatal errors
    `void` | `setController(Controller c)`
    `void` | `setDiscardCommentsAndPIs(boolean discard)` Indicate whether comments and Processing Instructions should be discarded
    `void` | `setErrorHandler(org.xml.sax.ErrorHandler eh)` Set the SAX error handler to use.
    `void` | `setErrorListener(javax.xml.transform.ErrorListener eh)` Set the JAXP error listener to use, if no SAX errorHandler has been provided.
    `void` | `setErrorOutput(java.io.Writer writer)` Set output for error messages produced by the default error handler. The default error handler does not throw an exception for parse errors or input I/O errors, rather it returns a result code and writes diagnostics to a user-specified output writer, which defaults to System.err This call has no effect if setErrorHandler() has been called to supply a user-defined error handler
    `void` | `setLineNumbering(boolean onOrOff)` Set line numbering on or off
    `void` | `setPreviewManager(PreviewManager pm)` Set the PreviewManager to use
    `void` | `setRootNode(DocumentInfo doc)` Set the root (document) node to use.
    `void` | `setStripper(Stripper s)` Set the Stripper to use
    `void` | `setTiming(boolean on)` Set timing option on or off
    `abstract void` | `setUnparsedEntity(java.lang.String name, java.lang.String uri)` Set the URI for an unparsed entity in the document.
    `void` | `warning(org.xml.sax.SAXParseException e)` Callback interface for SAX: not for application use

    - ### Methods inherited from class com.icl.saxon.output.Emitter

      `characters, comment, endDocument, endElement, getNamePool, getOutputProperties, getOutputStream, getSystemId, getWriter, makeEmitter, processingInstruction, setDocumentLocator, setEscaping, setNamePool, setOutputProperties, setOutputStream, setSystemId, setWriter, startDocument, startElement, usesWriter`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface org.xml.sax.Locator

      `getSystemId`

    - ### Methods inherited from interface javax.xml.transform.SourceLocator

      `getSystemId`

- - ### Field Detail

    - #### STANDARD_TREE

          public static final int STANDARD_TREE

      See Also:
        Constant Field Values

    - #### TINY_TREE

          public static final int TINY_TREE

      See Also:
        Constant Field Values

    - #### estimatedLength

          protected int estimatedLength

    - #### errorOutput

          protected java.io.Writer errorOutput

    - #### stripper

          protected Stripper stripper

    - #### previewManager

          protected PreviewManager previewManager

    - #### discardComments

          protected boolean discardComments

    - #### currentDocument

          protected DocumentInfo currentDocument

    - #### errorHandler

          protected org.xml.sax.ErrorHandler errorHandler

    - #### errorListener

          protected javax.xml.transform.ErrorListener errorListener

    - #### failed

          protected boolean failed

    - #### started

          protected boolean started

    - #### timing

          protected boolean timing

    - #### inDTD

          protected boolean inDTD

    - #### lineNumbering

          protected boolean lineNumbering

    - #### lineNumber

          protected int lineNumber

    - #### columnNumber

          protected int columnNumber

    - #### controller

          protected Controller controller

  - ### Constructor Detail

    - #### Builder

          public Builder()

      create a Builder and initialise variables

  - ### Method Detail

    - #### setController

          public void setController(Controller c)

    - #### setRootNode

          public void setRootNode(DocumentInfo doc)

      Set the root (document) node to use. This method is used to support the JAXP facility to attach transformation output to a supplied Document node. It must be called before startDocument(), and the type of document node must be compatible with the type of Builder used.

    - #### setTiming

          public void setTiming(boolean on)

      Set timing option on or off

    - #### isTiming

          public boolean isTiming()

      Get timing option

    - #### setLineNumbering

          public void setLineNumbering(boolean onOrOff)

      Set line numbering on or off

    - #### setStripper

          public void setStripper(Stripper s)

      Set the Stripper to use

    - #### getStripper

          public Stripper getStripper()

      Get the Stripper in use

    - #### setPreviewManager

          public void setPreviewManager(PreviewManager pm)

      Set the PreviewManager to use

    - #### setDiscardCommentsAndPIs

          public void setDiscardCommentsAndPIs(boolean discard)

      Indicate whether comments and Processing Instructions should be discarded

    - #### setErrorHandler

          public void setErrorHandler(org.xml.sax.ErrorHandler eh)

      Set the SAX error handler to use. If none is specified, SAXON supplies its own, which writes error messages to the selected error output writer.
      Parameters:
        `eh` - The error handler to use. It must conform to the interface org.xml.sax.ErrorHandler

    - #### setErrorListener

          public void setErrorListener(javax.xml.transform.ErrorListener eh)

      Set the JAXP error listener to use, if no SAX errorHandler has been provided.
      Parameters:
        `eh` - The error listener to use. It must conform to the interface javax.xml.transform.ErrorListener

    - #### setErrorOutput

          public void setErrorOutput(java.io.Writer writer)

      Set output for error messages produced by the default error handler.
      The default error handler does not throw an exception for parse errors or input I/O errors, rather it returns a result code and writes diagnostics to a user-specified output writer, which defaults to System.err
      This call has no effect if setErrorHandler() has been called to supply a user-defined error handler
      Parameters:
        `writer` - The Writer to use for error messages

    - #### build

          public DocumentInfo build(javax.xml.transform.sax.SAXSource source)
                             throws javax.xml.transform.TransformerException

      Build the tree from an input source. After building the tree, it can be walked as often as required using run(Document doc).
      Parameters:
        `source` - The source to use. SAXSource is a SAX-defined class that allows input from a URL, a byte stream, or a character stream. SAXON also provides a subclass, ExtendedInputSource, that allows input directly from a File.
      Returns:
        The DocumentInfo object that results from parsing the input.
      Throws:
        `javax.xml.transform.TransformerException` - if the input document could not be read or if it was not parsed correctly.

    - #### getCurrentDocument

          public DocumentInfo getCurrentDocument()

      Get the current document
      Returns:
        the document that has been most recently built using this builder

    - #### warning

          public void warning(org.xml.sax.SAXParseException e)

      Callback interface for SAX: not for application use
      Specified by:
        `warning` in interface `org.xml.sax.ErrorHandler`

    - #### error

          public void error(org.xml.sax.SAXParseException e)
                     throws org.xml.sax.SAXException

      Callback interface for SAX: not for application use
      Specified by:
        `error` in interface `org.xml.sax.ErrorHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### fatalError

          public void fatalError(org.xml.sax.SAXParseException e)
                          throws org.xml.sax.SAXException

      Callback interface for SAX: not for application use
      Specified by:
        `fatalError` in interface `org.xml.sax.ErrorHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### reportError

          protected void reportError(org.xml.sax.SAXParseException e,
                         boolean isFatal)

      Common routine for errors and fatal errors

    - #### setUnparsedEntity

          public abstract void setUnparsedEntity(java.lang.String name,
                               java.lang.String uri)

      Set the URI for an unparsed entity in the document. Abstract method to be implemented in each subclass.
      Overrides:
        `setUnparsedEntity` in class `Emitter`

    - #### getPublicId

          public java.lang.String getPublicId()

      Specified by:
        `getPublicId` in interface `javax.xml.transform.SourceLocator`
      Specified by:
        `getPublicId` in interface `org.xml.sax.Locator`

    - #### getLineNumber

          public int getLineNumber()

      Specified by:
        `getLineNumber` in interface `javax.xml.transform.SourceLocator`
      Specified by:
        `getLineNumber` in interface `org.xml.sax.Locator`

    - #### getColumnNumber

          public int getColumnNumber()

      Specified by:
        `getColumnNumber` in interface `javax.xml.transform.SourceLocator`
      Specified by:
        `getColumnNumber` in interface `org.xml.sax.Locator`