com.icl.saxon.trax
Interface Transformer

All Superinterfaces:
org.xml.sax.XMLFilter, org.xml.sax.XMLReader
All Known Implementing Classes:
Controller

public interface Transformer
extends org.xml.sax.XMLFilter

This object represents a Transformer, which is a SAX2 XMLFilter. An object of this class can not be used concurrently over multiple threads.

Open issues:

Separate DOM Interface?

Should there be a separate DOMTransformer class, instead of having the transformNode method?

XMLFilter derivation?

There is some question in some people's mind whether or not the Transformer interface should extend XMLFilter.

XMLReader vs. Parser vs. SAXParser/DocumentBuilder

Currently the interfaces support XMLReader. Should this be javax.xml.parsers.SAXParser/javax.xml.parsers.DocumentBuilder? Or, perhaps just org.xml.sax.Parser?

ContentHandler is entitled to expect a well-formed tree

Mike Kay: The output of XSLT is a well-balanced tree, or to put it another way, a well-formed external general parsed entity, but it is not in general a well-formed XML document. Specifically, it can have multiple elements and text nodes as children of the root. It's quite possible to feed such a tree into a SAX ContentHandler, but to do so breaks the implicit contract that the tree will be well-formed, and I have certainly encountered SAX ContentHandlers (or DocumentHandlers) that break if you try to do this (FOP is an example). This is one of those awful cases where it's difficult to provide the right solution for the 95% of people who want to generate well-formed output without falling over in the other 5% of cases. In Saxon I've been moving in the direction of allowing the ContentHandler itself to declare that it is prepared to accept well-balanced (but ill-formed) input.


Method Summary
 org.xml.sax.ContentHandler getInputContentHandler()
          Get a SAX2 ContentHandler for the input.
 org.xml.sax.ext.DeclHandler getInputDeclHandler()
          Get a SAX2 DeclHandler for the input.
 org.xml.sax.ext.LexicalHandler getInputLexicalHandler()
          Get a SAX2 LexicalHandler for the input.
 org.xml.sax.XMLReader getXMLReader()
          Get the XML parser used for the source tree.
 void resetParameters()
          Reset the parameters to a null list.
 void setOutputFormat(OutputFormat oformat)
          Set the output properties for the transformation.
 void setParameter(java.lang.String name, java.lang.String namespace, java.lang.Object value)
          Set a parameter for the templates.
 void setURIResolver(URIResolver resolver)
          Set an object that will be used to resolve URIs used in document(), etc.
 void setXMLReader(org.xml.sax.XMLReader reader)
          Set an XML parser for the source tree.
 void transform(org.xml.sax.InputSource xmlSource)
          Process the source tree to SAX parse events.
 void transform(org.xml.sax.InputSource xmlSource, Result outputTarget)
          Process the source tree to the output result.
 void transformNode(org.w3c.dom.Node node)
          Process the source node to to SAX parse events, if the processor supports the "http://xml.org/trax/features/dom/input" feature.
 void transformNode(org.w3c.dom.Node node, Result outputTarget)
          Process the source node to the output result, if the processor supports the "http://xml.org/trax/features/dom/input" feature.
 
Methods inherited from interface org.xml.sax.XMLFilter
getParent, setParent
 
Methods inherited from interface org.xml.sax.XMLReader
getContentHandler, getDTDHandler, getEntityResolver, getErrorHandler, getFeature, getProperty, parse, parse, setContentHandler, setDTDHandler, setEntityResolver, setErrorHandler, setFeature, setProperty
 

Method Detail

transform

public void transform(org.xml.sax.InputSource xmlSource)
               throws TransformException
Process the source tree to SAX parse events.
Parameters:
xmlSource - The input for the source tree.

transform

public void transform(org.xml.sax.InputSource xmlSource,
                      Result outputTarget)
               throws TransformException
Process the source tree to the output result.
Parameters:
xmlSource - The input for the source tree.
outputTarget - The output source target.

transformNode

public void transformNode(org.w3c.dom.Node node,
                          Result outputTarget)
                   throws TransformException
Process the source node to the output result, if the processor supports the "http://xml.org/trax/features/dom/input" feature.
Parameters:
node - The input source node, which can be any valid DOM node.
outputTarget - The output source target.

transformNode

public void transformNode(org.w3c.dom.Node node)
                   throws TransformException
Process the source node to to SAX parse events, if the processor supports the "http://xml.org/trax/features/dom/input" feature.
Parameters:
node - The input source node, which can be any valid DOM node.

getInputContentHandler

public org.xml.sax.ContentHandler getInputContentHandler()
Get a SAX2 ContentHandler for the input.
Returns:
A valid ContentHandler, which should never be null, as long as getFeature("http://xml.org/trax/features/sax/input") returns true.

Open issues:

ContentHandler vs. ContentHandler

I don't think I would use ContentHandler at all, except that JAXP uses it. Maybe we should go back to using ContentHandler?

getInputDeclHandler

public org.xml.sax.ext.DeclHandler getInputDeclHandler()
Get a SAX2 DeclHandler for the input.
Returns:
A valid DeclHandler, which should never be null, as long as getFeature("http://xml.org/trax/features/sax/input") returns true.

getInputLexicalHandler

public org.xml.sax.ext.LexicalHandler getInputLexicalHandler()
Get a SAX2 LexicalHandler for the input.
Returns:
A valid LexicalHandler, which should never be null, as long as getFeature("http://xml.org/trax/features/sax/input") returns true.

setOutputFormat

public void setOutputFormat(OutputFormat oformat)
Set the output properties for the transformation. These properties will override properties set in the templates with xsl:output.
See Also:
org.xml.serialize.OutputFormat

setParameter

public void setParameter(java.lang.String name,
                         java.lang.String namespace,
                         java.lang.Object value)
Set a parameter for the templates.
Parameters:
name - The name of the parameter.
namespace - The namespace of the parameter.

resetParameters

public void resetParameters()
Reset the parameters to a null list.

setURIResolver

public void setURIResolver(URIResolver resolver)
Set an object that will be used to resolve URIs used in document(), etc.
Parameters:
resolver - An object that implements the URIResolver interface, or null.

setXMLReader

public void setXMLReader(org.xml.sax.XMLReader reader)
Set an XML parser for the source tree. Note that if Transformer.setXMLReader is not called, the parser set with Processor.setXMLReader will be used.

getXMLReader

public org.xml.sax.XMLReader getXMLReader()
Get the XML parser used for the source tree. Note that if Transformer.setXMLReader is not called, the parser set with Processor.setXMLReader will be used.