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, JDOMWriter, 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.

Author:

Michael H. Kay

Field Summary

Fields

Modifier and Type	Field and 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
static int	K_TREE
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 boolean	open
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	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
protected boolean	useEventLocation

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
Builder(PipelineConfiguration pipe)

Method Summary

Modifier and Type	Method and 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 Receiver.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 Receiver.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, attribute, characters, comment, endDocument, endElement, handlesAppend, 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

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

K_TREE

public static final int K_TREE

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

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 Receiver.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 Receiver.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 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()

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.