## 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:
  TinyBuilder, TreeBuilder

    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.

Author:
  Michael H. Kay

Field Summary
`protected java.lang.String` `baseURI`
`protected Configuration` `config`
`protected NodeInfo` `currentRoot`
`protected boolean` `lineNumbering`
`static int` `LINKED_TREE` Constant denoting the "linked tree" in which each node is represented as an object
`protected NamePool` `namePool`
`protected PipelineConfiguration` `pipe`
`static int` `STANDARD_TREE` Alternative constant denoting the "linked tree" in which each node is represented as an object Retained for backwards compatibility
`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` `UNSPECIFIED_TREE_MODEL` Constant denoting a request for the default tree model

Fields inherited from interface javax.xml.transform.Result
`PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING`

Constructor Summary
`Builder()` create a Builder and initialise variables

Method Summary
`static NodeInfo` `build(javax.xml.transform.Source source, Stripper stripper, Configuration config)` Static method to build a document from any kind of Source object.
`static NodeInfo` `build(javax.xml.transform.Source source, Stripper stripper, PipelineConfiguration pipe)` Static method to build a document from any kind of Source object.
`void` `close()` Notify the end of the event stream
`void` `endDocument()` Notify the end of a document node
`java.lang.String` `getBaseURI()` Get the base URI of the document node of the tree being constructed by 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
`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` `startDocument(int properties)` Start of a document node.

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
`attribute, characters, comment, endElement, namespace, processingInstruction, setUnparsedEntity, startContent, 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

### STANDARD_TREE

    public static final int STANDARD_TREE

  Alternative constant denoting the "linked tree" in which each node is represented as an object Retained for backwards compatibility

  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

### pipe

    protected PipelineConfiguration pipe

### config

    protected Configuration config

### namePool

    protected NamePool namePool

### systemId

    protected java.lang.String systemId

### baseURI

    protected java.lang.String baseURI

### currentRoot

    protected NodeInfo currentRoot

### lineNumbering

    protected boolean lineNumbering

### started

    protected boolean started

### timing

    protected boolean timing

Constructor Detail

### Builder

    public Builder()

  create a Builder and initialise variables

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

### 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 `javax.xml.transform.Result`
  Specified by:
    `setSystemId` in interface `Receiver`
  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()
              throws XPathException

  Description copied from interface: `Receiver`
  Notify the start of the event stream

  Specified by:
    `open` in interface `Receiver`
  Throws:
    `XPathException`

### 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`

### startDocument

    public void startDocument(int properties)
                       throws XPathException

  Start of a document node. This event is ignored: we simply add the contained elements to the current document

  Specified by:
    `startDocument` in interface `Receiver`
  Parameters:
    `properties` - bit-significant integer indicating properties of the document node. The definitions of the bits are in class `ReceiverOptions`
  Throws:
    `XPathException`

### endDocument

    public void endDocument()
                     throws XPathException

  Notify the end of a document node

  Specified by:
    `endDocument` in interface `Receiver`
  Throws:
    `XPathException`

### 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.

### build

    public static NodeInfo build(javax.xml.transform.Source source,
                                 Stripper stripper,
                                 Configuration config)
                          throws XPathException

  Static method to build a document from any kind of Source object. If the source is already in the form of a tree, it is wrapped as required.

  The preferred way to construct a document tree from a Source object is to use the method `Configuration.buildDocument(javax.xml.transform.Source)`.

  Parameters:
    `source` - Any javax.xml.transform.Source object
    `stripper` - A stripper object, if whitespace text nodes are to be stripped; otherwise null.
    `config` - The Configuration object
  Returns:
    the NodeInfo of the start node in the resulting document object.
  Throws:
    `XPathException`

### build

    public static NodeInfo build(javax.xml.transform.Source source,
                                 Stripper stripper,
                                 PipelineConfiguration pipe)
                          throws XPathException

  Static method to build a document from any kind of Source object. If the source is already in the form of a tree, it is wrapped as required.

  The preferred way to construct a document tree from a Source object is to use the method `Configuration.buildDocument(javax.xml.transform.Source)`.

  Parameters:
    `source` - Any javax.xml.transform.Source object
    `stripper` - A stripper object, if whitespace text nodes are to be stripped; otherwise null.
    `pipe` - The PipelineConfiguration object
  Returns:
    the NodeInfo of the start node in the resulting document object.
  Throws:
    `XPathException`

Copyright (c) Saxonica Limited. All rights reserved.