Package net.sf.saxon.event

This package provides classes that feed SAX-like events from one tree to another.

See:
Description

Interface Summary

CopyInformee	A CopyInformee is an agent that receives extra information while a tree is being copied.
LocationProvider	LocationProvider: this interface represents an object that provides the location of elements in a source document or instructions in a stylesheet or query.
Receiver	Receiver: This interface represents a recipient of XML tree-walking (push) events.
SaxonLocator	SaxonLocator: this interface exists to unify the SAX Locator and JAXP SourceLocator interfaces, which are identical.
SourceLocationProvider	A SourceLocationProvider is a LocationProvider that represents locations in the source document from which the events are derived (as distinct from locations in a query or stylesheet of the instructions causing the events)

Class Summary

Builder	The abstract Builder class is responsible for taking a stream of SAX events and constructing a Document tree.
CDATAFilter	CDATAFilter: This ProxyEmitter converts character data to CDATA sections, if the character data belongs to one of a set of element types to be handled this way.
CharacterMapExpander	CharacterMapExpander: This ProxyReceiver expands characters occurring in a character map, as specified by the XSLT 2.0 xsl:character-map declaration
CommentStripper	The CommentStripper class is a filter that removes all comments and processing instructions.
ComplexContentOutputter	This class is used for generating complex content, that is, the content of an element or document node.
ContentHandlerProxy	A ContentHandlerProxy is a Receiver that converts events into the form expected by an underlying SAX2 ContentHandler.
ContentHandlerProxyLocator	Implementation of Locator, used to supply location information to the ContentHandler.
DocumentSender	Sends an entire document to a Receiver.
Emitter	Emitter: This abstract class defines methods that must be implemented by components that format SAXON output.
EventSource	An implementation of the JAXP Source class that supplies a document in the form of a stream of push events sent to a Receiver
HTMLEmitter	This class generates HTML output
HTMLIndenter	HTMLIndenter: This ProxyEmitter indents HTML elements, by adding whitespace character data where appropriate.
HTMLTagHashSet	A simple class for testing membership of a fixed set of case-insensitive ASCII strings.
HTMLURIEscaper	This class is used as a filter on the serialization pipeline; it performs the function of escaping URI-valued attributes in HTML
IDFilter	IDFilter is a ProxyReceiver that extracts the subtree of a document rooted at the element with a given ID value.
ImplicitResultChecker	This filter is inserted into the serializer pipeline when serializing an implicit XSLT result tree, that is, one that is created without use of xsl:result-document.
LocationCopier	A Receiver that can be inserted into an event pipeline to copy location information.
MessageEmitter	MessageEmitter is the default Receiver for xsl:message output.
MessageWarner	MessageWarner is a user-selectable receiver for XSLT xsl:message output.
MetaTagAdjuster	The MetaTagAdjuster adds a meta element to the content of the head element, indicating the required content type and encoding; it also removes any existing meta element containing this information
NamePoolConverter	This class is a filter that passes all Receiver events through unchanged, except that it changes namecodes to allow for the source and the destination using different NamePools.
NamespaceReducer	NamespaceReducer is a ProxyReceiver responsible for removing duplicate namespace declarations.
ParseOptions	This class defines options for parsing a source document
PIGrabber	The PIGrabber class is a Receiver that looks for xml-stylesheet processing instructions and tests whether they match specified criteria; for those that do, it creates an InputSource object referring to the relevant stylesheet
PipelineConfiguration	A PipelineConfiguration sets options that apply to all the operations in a pipeline.
ProxyReceiver	A ProxyReceiver is an Receiver that filters data before passing it to another underlying Receiver.
ReceiverOptions	ReceiverOptions defines a set of constants, which can be used in calls to methods on the Receiver interface.
ReceivingContentHandler	ReceivingContentHandler is a glue class that provides a standard SAX ContentHandler interface to a Saxon Receiver.
SaxonOutputKeys	Provides string constants that can be used to set output properties for a Transformer, or to retrieve output properties from a Transformer or Templates object.
Sender	Sender is a helper class that sends events to a Receiver from any kind of Source object
SequenceCopier	Copies a sequence, supplied as a SequenceIterator, to a push pipeline, represented by a SequenceReceiver
SequenceOutputter	This outputter is used when writing a sequence of atomic values and nodes, that is, when xsl:variable is used with content and an "as" attribute.
SequenceReceiver	SequenceReceiver: this extension of the Receiver interface is used when processing a sequence constructor.
SequenceWriter	This outputter is used when writing a sequence of atomic values and nodes, for example, when xsl:variable is used with content and an "as" attribute.
SerializerFactory	Helper class to construct a serialization pipeline for a given result destination and a given set of output properties.
Sink	A Sink is an Receiver that discards all information passed to it
StandardOutputResolver	This class defines the default OutputURIResolver.
StartTagBuffer	StartTagBuffer is a ProxyReceiver that buffers attributes and namespace events within a start tag.
Stripper	The Stripper class performs whitespace stripping according to the rules of the xsl:strip-space and xsl:preserve-space instructions.
TeeOutputter	TeeOutputter: a SequenceReceiver that duplicates received events to two different destinations
TEXTEmitter	This class generates TEXT output
TracingFilter	A filter that can be inserted into a Receiver pipeline to trace the events that pass through
TransformerReceiver	TransformerReceiver is similar in concept to the JAXP TransformerHandler, except that it implements Saxon's Receiver interface rather than the standard SAX2 interface.
TreeReceiver	A TreeReceiver acts as a bridge between a SequenceReceiver, which can receive events for constructing any kind of sequence, and an ordinary Receiver, which only handles events relating to the building of trees.
TypeCheckingFilter	A filter on the push pipeline that performs type checking, both of the item type and the cardinality.
UncommittedSerializer	This class is used when the decision on which serialization method to use has to be delayed until the first element is read.
UnicodeNormalizer	UnicodeNormalizer: This ProxyReceiver performs unicode normalization on the contents of attribute and text nodes.
UTF8Writer	Specialized buffering UTF-8 writer.
XHTMLEmitter	XHTMLEmitter is an Emitter that generates XHTML output.
XHTMLIndenter	XHTMLIndenter: This class indents XHTML elements, by adding whitespace character data where appropriate.
XHTMLURIEscaper	This class performs URI escaping for the XHTML output method.
XML10ContentChecker	This class is used on the serialization pipeline to check that the document conforms to XML 1.0 rules.
XMLEmitter	XMLEmitter is an Emitter that generates XML output to a specified destination.
XMLIndenter	XMLIndenter: This ProxyReceiver indents elements, by adding character data where appropriate.
XQueryEmitter	The XQueryEmitter is designed to serialize an XQuery that was originally embedded in an XML document.

Exception Summary

CopyNamespaceSensitiveException	Exception indicating that an attempt was made to copy namespace-sensitive content without copying its associated namespaces
NoOpenStartTagException	Exception indicating that an attribute or namespace node has been written when there is no open element to write it to

Package net.sf.saxon.event Description

This package provides classes that feed SAX-like events from one tree to another. Many of these classes are associated with serializing the output of a stylesheet, but there are also classes for building a tree from a stream of events, for stripping whitespace, and so on.

The Receiver interface defines a class that accepts a stream of events, with one method defined for each kind of event. The events are modelled on the design of SAX, but adapted to the XPath data model and to the use of Saxon's NamePool. Attributes and namespaces are notified individually after the start of the relevant element.

The immediate output of node constructors in a query or stylesheet goes to a SequenceReceiver. This is a subclass of Receiver that can handle an arbitrary sequence, containing atomic values as well as nodes. When constructing the content of an element, a ComplexContentOutputter is used; when constructing the content of a node such as a text node or attribute, a SequenceOutputter is used instead.

The final destination of the push pipeline is sometimes a serializer, and sometimes a tree builder. The final serialization classes are subclasses of Emitter, but some of the serialization work (such as indentation or application of character maps) is done by other classes on the pipeline. These are generally constructed by extending the ProxyReceiver class.

The Emitter is an abstract implementation of the Receiver interface. As well as supporting the Receiver interface, it provides methods for controlling the destination of serialized output (a Writer or OutputStream) and for setting serialization properties (in a Properties object). In practice nearly all the implementations of Receiver are currently subclasses of Emitter, but this may change in the future.

The package includes emitters for the standard output methods xml, html, and text, and proxy emitters to allow a sequence of filters to be applied to the output.

,

The class ContentHandlerProxy allows events to be converted into standard SAX events and sent to a SAX2 ContentHandler. Similarly, the class ProxyReceiver acts as a ContentHandler, accepting SAX2 events and feeding them into a Receiver pipeline.

The class Builder is a Receiver that constructs a tree representation of the document in memory. There are two subclasses for Saxon's two native tree models. Other classes such as a Stripper and a NamespaceReducer are used to modify the document by adding filters to the pipeline.

Saxon's schema validator is also implemented using this push pipeline model. The classes that perform schema validation, however, are part of a different package: com.saxonica.validate.

Michael H. Kay
Saxonica Limited
9 February 2005