This package implements SAX2-specific transformation APIs. It provides classes which allow input from ContentHandler
events, and also classes that produce org.xml.sax.ContentHandler events. It also provides methods to set the input source as an XMLReader
, or to use a InputSource
as the source. It also allows the creation of a XMLFilter
, which enables transformations to "pull" from other transformations, and lets the transformer to be used polymorphically as an XMLReader
.
The SAXSource
class allows the setting of an XMLReader
to be used for "pulling" parse events, and an InputSource
that may be used to specify the SAX source.
The SAXResult
class allows the setting of a ContentHandler
to be the receiver of SAX2 events from the transformation.
The SAXTransformerFactory
extends TransformerFactory
to provide factory methods for creating TemplatesHandler
, TransformerHandler
, and XMLReader
instances.
To obtain a SAXTransformerFactory
, the caller must cast the TransformerFactory
instance returned from newInstance()
.
The TransformerHandler
interface allows a transformation to be created from SAX2 parse events, which is a "push" model rather than the "pull" model that normally occurs for a transformation. Normal parse events are received through the ContentHandler
interface, lexical events such as startCDATA and endCDATA are received through the LexicalHandler
interface, and events that signal the start or end of disabling output escaping are received via processingInstruction(String, String)
, with the target parameter being PI_DISABLE_OUTPUT_ESCAPING
and PI_ENABLE_OUTPUT_ESCAPING
. If parameters, output properties, or other features need to be set on the Transformer handler, a Transformer
reference will need to be obtained from getTransformer()
, and the methods invoked from that reference.
The TemplatesHandler
interface allows the creation of Templates
objects from SAX2 parse events. Once the ContentHandler
events are complete, the Templates object may be obtained from getTemplates()
. Note that setSystemId(String)
should normally be called in order to establish a base system ID from which relative URLs may be resolved.
The newXMLFilter(Source)
method allows the creation of a XMLFilter
, which encapsulates the SAX2 notion of a "pull" transformation. The following illustrates several transformations chained together. Each filter points to a parent XMLReader
, and the final transformation is caused by invoking parse(String)
on the final reader in the chain.
TemplatesHandler | A SAX ContentHandler that may be used to process SAX parse events (parsing transformation instructions) into a Templates object. |
TransformerHandler | A TransformerHandler listens for SAX ContentHandler parse events and transforms them to a Result. |
SAXResult | Acts as an holder for a transformation Result. |
SAXSource | Acts as an holder for SAX-style Source. |
SAXTransformerFactory | This class extends TransformerFactory to provide SAX-specific factory methods. |