net.sf.saxon.event
Class Builder

java.lang.Object
  extended by net.sf.saxon.event.Builder
All Implemented Interfaces:
Result, Receiver
Direct Known Subclasses:
DOM4JWriter, JDOMWriter, LinkedTreeBuilder, TinyBuilder, XOMWriter

public abstract class Builder
extends 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  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  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.
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(Source source, RuleBasedStripper stripper, Configuration config)
          Deprecated. since Saxon 9.2: use Configuration.buildDocument(javax.xml.transform.Source). The method was also changed in 9.2 to ignore the stripper parameter.
static NodeInfo build(Source source, RuleBasedStripper stripper, PipelineConfiguration pipe)
          Deprecated. since Saxon 9.2: use Configuration.buildDocument(javax.xml.transform.Source). The method was also changed in 9.2 to ignore the stripper parameter.
 void close()
          Notify the end of the event stream
 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
 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(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(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
 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
attribute, characters, comment, endDocument, endElement, namespace, processingInstruction, setUnparsedEntity, startContent, 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

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

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

pipe

protected PipelineConfiguration pipe

config

protected Configuration config

namePool

protected NamePool namePool

systemId

protected String systemId

baseURI

protected 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

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.

setSystemId

public void setSystemId(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 Result
Specified by:
setSystemId in interface Receiver
Parameters:
systemId - the SystemId, that is, the document-uri.

getSystemId

public 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 Result
Returns:
the SystemId, that is, the document-uri.

setBaseURI

public void setBaseURI(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 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

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.


build

public static NodeInfo build(Source source,
                             RuleBasedStripper stripper,
                             Configuration config)
                      throws XPathException
Deprecated. since Saxon 9.2: use Configuration.buildDocument(javax.xml.transform.Source). The method was also changed in 9.2 to ignore the stripper parameter.

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. Ignored since Saxon 9.2
config - The Configuration object
Returns:
the NodeInfo of the start node in the resulting document object.
Throws:
XPathException

build

public static NodeInfo build(Source source,
                             RuleBasedStripper stripper,
                             PipelineConfiguration pipe)
                      throws XPathException
Deprecated. since Saxon 9.2: use Configuration.buildDocument(javax.xml.transform.Source). The method was also changed in 9.2 to ignore the stripper parameter.

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. Ignored since Saxon 9.2
pipe - The PipelineConfiguration object
Returns:
the NodeInfo of the start node in the resulting document object.
Throws:
XPathException


Copyright (c) 2004-2010 Saxonica Limited. All rights reserved.