Package net.sf.saxon.event

## Class Builder

- java.lang.Object
- - net.sf.saxon.event.Builder

- All Implemented Interfaces:
    `javax.xml.transform.Result`, `Receiver`
  Direct Known Subclasses:
    `AxiomWriter`, `DOM4JWriter`, `DOMWriter`, `JDOM2Writer`, `LinkedTreeBuilder`, `TinyBuilder`, `XOMWriter`

      public abstract class Builder
      extends java.lang.Object
      implements Receiver

  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 | Description
    --- | --- | ---
    `static int` | `AXIOM_TREE` |
    `protected java.lang.String` | `baseURI` |
    `protected Configuration` | `config` |
    `protected NodeInfo` | `currentRoot` |
    `static int` | `DOMINO_TREE` |
    `static int` | `JDOM_TREE` |
    `static int` | `JDOM2_TREE` |
    `protected boolean` | `lineNumbering` |
    `static int` | `LINKED_TREE` | Constant denoting the "linked tree" in which each node is represented as an object
    `static int` | `MUTABLE_LINKED_TREE` | Constant denoting the "mutable linked tree" in which each node is represented as an object
    `protected NamePool` | `namePool` |
    `protected boolean` | `open` |
    `protected PipelineConfiguration` | `pipe` |
    `protected boolean` | `started` |
    `protected java.lang.String` | `systemId` |
    `protected boolean` | `timing` |
    `static int` | `TINY_TREE` | Constant denoting the "tiny tree" in which the tree is represented internally using arrays of integers
    `static int` | `TINY_TREE_CONDENSED` | Constant denoting the "tiny tree condensed", a variant of the tiny tree in which text and attribute nodes sharing the same string value use shared storage for the value.
    `protected boolean` | `uniformBaseURI` |
    `static int` | `UNSPECIFIED_TREE_MODEL` | Constant denoting a request for the default tree model
    `protected boolean` | `useEventLocation` |

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

      `PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Builder()` | Create a Builder and initialise variables
    `Builder​(PipelineConfiguration pipe)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` | Notify the end of the event stream
    `java.lang.String` | `getBaseURI()` | Get the base URI of the document node of the tree being constructed by this builder
    `BuilderMonitor` | `getBuilderMonitor()` | Get a builder monitor for this builder.
    `Configuration` | `getConfiguration()` | Get the Configuration
    `NodeInfo` | `getCurrentRoot()` | Get the current root node.
    `PipelineConfiguration` | `getPipelineConfiguration()` | Get the pipeline configuration
    `java.lang.String` | `getSystemId()` | The SystemId is equivalent to the document-uri property defined in the XDM data model.
    `boolean` | `isTiming()` | Get timing option
    `boolean` | `isUseEventLocation()` | Ask whether the system IDs of constructed nodes (especially element nodes) are to be taken from the system ID property of the `Location` object passed as a parameter to the `Outputter.startElement(NodeName, SchemaType, Location, int)` event.
    `void` | `open()` | Notify the start of the event stream
    `void` | `reset()` | Reset the builder to its initial state.
    `void` | `setBaseURI​(java.lang.String baseURI)` | Set the base URI of the document node of the tree being constructed by this builder
    `void` | `setLineNumbering​(boolean lineNumbering)` | Set line numbering on or off
    `void` | `setPipelineConfiguration​(PipelineConfiguration pipe)` | Set the pipeline configuration
    `void` | `setSystemId​(java.lang.String systemId)` | The SystemId is equivalent to the document-uri property defined in the XDM data model.
    `void` | `setTiming​(boolean on)` | Set timing option on or off
    `void` | `setUseEventLocation​(boolean useEventLocation)` | Say that the system IDs of constructed nodes (especially element nodes) are to be taken from the system ID property of the `Location` object passed as a parameter to the `Outputter.startElement(NodeName, SchemaType, Location, int)` event.
    `boolean` | `usesTypeAnnotations()` | Ask whether this Receiver (or the downstream pipeline) makes any use of the type annotations supplied on element and attribute events

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

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

    - ### Methods inherited from interface net.sf.saxon.event.Receiver

      `append, append, characters, comment, endDocument, endElement, handlesAppend, processingInstruction, setUnparsedEntity, startDocument, startElement`

- - ### Field Detail

    - #### UNSPECIFIED_TREE_MODEL

          public static final int UNSPECIFIED_TREE_MODEL

      Constant denoting a request for the default tree model
      See Also:
        Constant Field Values

    - #### LINKED_TREE

          public static final int LINKED_TREE

      Constant denoting the "linked tree" in which each node is represented as an object
      See Also:
        Constant Field Values

    - #### TINY_TREE

          public static final int TINY_TREE

      Constant denoting the "tiny tree" in which the tree is represented internally using arrays of integers
      See Also:
        Constant Field Values

    - #### TINY_TREE_CONDENSED

          public static final int TINY_TREE_CONDENSED

      Constant denoting the "tiny tree condensed", a variant of the tiny tree in which text and attribute nodes sharing the same string value use shared storage for the value.
      See Also:
        Constant Field Values

    - #### JDOM_TREE

          public static final int JDOM_TREE

      See Also:
        Constant Field Values

    - #### JDOM2_TREE

          public static final int JDOM2_TREE

      See Also:
        Constant Field Values

    - #### AXIOM_TREE

          public static final int AXIOM_TREE

      See Also:
        Constant Field Values

    - #### DOMINO_TREE

          public static final int DOMINO_TREE

      See Also:
        Constant Field Values

    - #### MUTABLE_LINKED_TREE

          public static final int MUTABLE_LINKED_TREE

      Constant denoting the "mutable linked tree" in which each node is represented as an object
      See Also:
        Constant Field Values

    - #### pipe

          protected PipelineConfiguration pipe

    - #### config

          protected Configuration config

    - #### namePool

          protected NamePool namePool

    - #### systemId

          protected java.lang.String systemId

    - #### baseURI

          protected java.lang.String baseURI

    - #### uniformBaseURI

          protected boolean uniformBaseURI

    - #### currentRoot

          protected NodeInfo currentRoot

    - #### lineNumbering

          protected boolean lineNumbering

    - #### useEventLocation

          protected boolean useEventLocation

    - #### started

          protected boolean started

    - #### timing

          protected boolean timing

    - #### open

          protected boolean open

  - ### Constructor Detail

    - #### Builder

          public Builder()

      Create a Builder and initialise variables

    - #### Builder

          public Builder​(PipelineConfiguration pipe)

  - ### Method Detail

    - #### setPipelineConfiguration

          public void setPipelineConfiguration​(PipelineConfiguration pipe)

      Description copied from interface: `Receiver`
      Set the pipeline configuration
      Specified by:
        `setPipelineConfiguration` in interface `Receiver`
      Parameters:
        `pipe` - the pipeline configuration

    - #### getPipelineConfiguration

          public PipelineConfiguration getPipelineConfiguration()

      Description copied from interface: `Receiver`
      Get the pipeline configuration
      Specified by:
        `getPipelineConfiguration` in interface `Receiver`
      Returns:
        the pipeline configuration

    - #### getConfiguration

          public Configuration getConfiguration()

      Get the Configuration
      Returns:
        the Saxon configuration

    - #### getBuilderMonitor

          public BuilderMonitor getBuilderMonitor()

      Get a builder monitor for this builder. This must be called immediately after opening the builder, and all events to the builder must thenceforth be sent via the BuilderMonitor.
      Returns:
        a new BuilderMonitor appropriate to this kind of Builder; or null if the Builder does not provide this service. The default implementation returns null.

    - #### setUseEventLocation

          public void setUseEventLocation​(boolean useEventLocation)

      Say that the system IDs of constructed nodes (especially element nodes) are to be taken from the system ID property of the `Location` object passed as a parameter to the `Outputter.startElement(NodeName, SchemaType, Location, int)` event. This property should be set to true when building a document from events originating with an XML parser, because the `Location` object in this case will have a system ID that changes as external entities are processed. The base URI of a node in this case is determined by the system ID, modified by any `xml:base` attributes. If the property is set to false, all nodes in the tree have the same system ID, this being supplied as the systemID property of the builder. This will typically be the static base URI of the instruction in the query or stylesheet that was used to construct the root node; in the case of `xsl:result-document`, it will be the absolutized value of the `href` attribute of the instruction.
      Parameters:
        `useEventLocation` - true if the system ID is to be taken from the Location parameter of each event. The default value is true.

    - #### isUseEventLocation

          public boolean isUseEventLocation()

      Ask whether the system IDs of constructed nodes (especially element nodes) are to be taken from the system ID property of the `Location` object passed as a parameter to the `Outputter.startElement(NodeName, SchemaType, Location, int)` event.
      Returns:
        true if the system ID is to be taken from the Location parameter of each event. The default value is true.

    - #### setSystemId

          public void setSystemId​(java.lang.String systemId)

      The SystemId is equivalent to the document-uri property defined in the XDM data model. It should be set only in the case of a document that is potentially retrievable via this URI. This means it should not be set in the case of a temporary tree constructed in the course of executing a query or transformation.
      Specified by:
        `setSystemId` in interface `Receiver`
      Specified by:
        `setSystemId` in interface `javax.xml.transform.Result`
      Parameters:
        `systemId` - the SystemId, that is, the document-uri.

    - #### getSystemId

          public java.lang.String getSystemId()

      The SystemId is equivalent to the document-uri property defined in the XDM data model. It should be set only in the case of a document that is potentially retrievable via this URI. This means the value will be null in the case of a temporary tree constructed in the course of executing a query or transformation.
      Specified by:
        `getSystemId` in interface `javax.xml.transform.Result`
      Returns:
        the SystemId, that is, the document-uri.

    - #### setBaseURI

          public void setBaseURI​(java.lang.String baseURI)

      Set the base URI of the document node of the tree being constructed by this builder
      Parameters:
        `baseURI` - the base URI

    - #### getBaseURI

          public java.lang.String getBaseURI()

      Get the base URI of the document node of the tree being constructed by this builder
      Returns:
        the base URI

    - #### setLineNumbering

          public void setLineNumbering​(boolean lineNumbering)

      Set line numbering on or off
      Parameters:
        `lineNumbering` - set to true if line numbers are to be maintained for nodes in the tree being constructed.

    - #### setTiming

          public void setTiming​(boolean on)

      Set timing option on or off
      Parameters:
        `on` - set to true to turn timing on. This causes the builder to display statistical information about the tree that is constructed. It corresponds to the command line -t option

    - #### isTiming

          public boolean isTiming()

      Get timing option
      Returns:
        true if timing information has been requested

    - #### open

          public void open()

      Description copied from interface: `Receiver`
      Notify the start of the event stream
      Specified by:
        `open` in interface `Receiver`

    - #### close

          public void close()
                     throws XPathException

      Description copied from interface: `Receiver`
      Notify the end of the event stream
      Specified by:
        `close` in interface `Receiver`
      Throws:
        `XPathException` - if an error occurs

    - #### usesTypeAnnotations

          public boolean usesTypeAnnotations()

      Ask whether this Receiver (or the downstream pipeline) makes any use of the type annotations supplied on element and attribute events
      Specified by:
        `usesTypeAnnotations` in interface `Receiver`
      Returns:
        true if the Receiver makes any use of this information. If false, the caller may supply untyped nodes instead of supplying the type annotation

    - #### getCurrentRoot

          public NodeInfo getCurrentRoot()

      Get the current root node. This will normally be a document node, but if the root of the tree is an element node, it can be an element.
      Returns:
        the root of the tree that is currently being built, or that has been most recently built using this builder

    - #### reset

          public void reset()

      Reset the builder to its initial state. The most important effect of calling this method (implemented in subclasses) is to release any links to the constructed document tree, allowing the memory occupied by the tree to released by the garbage collector even if the Builder is still in memory. This can happen because the Builder is referenced from a parser in the Configuration's parser pool.