com.icl.saxon.trax
Class Processor

java.lang.Object
  |
  +--com.icl.saxon.trax.Processor
Direct Known Subclasses:
StyleSheet

public abstract class Processor
extends java.lang.Object

A particular transformation Processor is "plugged" into the platform via Processor in one of two ways: 1) as a platform default, and 2) through external specification by a system property named "com.icl.saxon.trax.Processor.[type]" obtained using java.lang.System.getProperty(). The [type] part of the property specifies the language to be used, for instance, "trax.processor.xslt" would specify an XSLT processor. This property (or platform default) names a class that is a concrete subclass of com.icl.saxon.trax.Processor. The subclass shall implement a public no-args constructor used by the base abstract class to create an instance of the factory using the newInstance() method.

The platform default is only used if no external implementation is available.

Open issues:

Separate Factory?

Should there be a separate ProcessorFactory class, to be more consistent with javax.xml.parsers.SAXParserFactory? Doing this would allow this class to be an interface instead of an abstract class.

Separate DOM Interface?

Should there be a separate DOMProcessor class, instead of having the processFromNode method?

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?

XMLReader derivation?

Should this derive from XMLReader (in a similar way that Transformer derives from XMLFilter)?


Constructor Summary
Processor()
           
 
Method Summary
abstract  org.xml.sax.InputSource[] getAssociatedStylesheets(org.xml.sax.InputSource source, java.lang.String media, java.lang.String title, java.lang.String charset)
          Get InputSource specification(s) that are associated with the given document specified in the source param, via the xml-stylesheet processing instruction (see http://www.w3.org/TR/xml-stylesheet/), and that matches the given criteria.
 org.xml.sax.ErrorHandler getErrorHandler()
          Return the current error handler.
 boolean getFeature(java.lang.String name)
          Look up the value of a feature.
abstract  TemplatesBuilder getTemplatesBuilder()
          Get a TemplatesBuilder object that can process SAX events into a Templates object, if the processor supports the "http://xml.org/trax/features/sax/input" feature.
 URIResolver getURIResolver()
          Set an object that will be used to resolve URIs used in xsl:import, etc.
 org.xml.sax.XMLReader getXMLReader()
          Get the XML parser used for the templates.
static Processor newInstance(java.lang.String type)
          Obtain a new instance of a Processor object.
abstract  Templates process(org.xml.sax.InputSource source)
          Process the source into a templates object.
abstract  Templates processFromNode(org.w3c.dom.Node node)
          Process the stylesheet from a DOM tree, if the processor supports the "http://xml.org/trax/features/dom/input" feature.
abstract  Templates processMultiple(org.xml.sax.InputSource[] source)
          Process a series of inputs, treating them in import or cascade order.
 void setErrorHandler(org.xml.sax.ErrorHandler handler)
          Allow an application to register an error event handler.
 void setFeature(java.lang.String name, boolean value)
          Set the state of a feature.
static void setPlatformDefaultProcessor(java.lang.String classname)
          Set the name of the default concrete class to be used.
 void setURIResolver(URIResolver resolver)
          Set an object that will be used to resolve URIs used in xsl:import, etc.
 void setXMLReader(org.xml.sax.XMLReader reader)
          Set an XML parser for the templates.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Processor

public Processor()
Method Detail

setPlatformDefaultProcessor

public static void setPlatformDefaultProcessor(java.lang.String classname)
Set the name of the default concrete class to be used.
Parameters:
classname - Full classname of concrete implementation of com.icl.saxon.trax.Processor.

newInstance

public static Processor newInstance(java.lang.String type)
                             throws ProcessorFactoryException
Obtain a new instance of a Processor object.
Returns:
Concrete instance of an Processor object.

process

public abstract Templates process(org.xml.sax.InputSource source)
                           throws ProcessorException,
                                  org.xml.sax.SAXException,
                                  java.io.IOException
Process the source into a templates object.
Parameters:
source - An object that holds a URL, input stream, etc.
Throws:
org.xml.sax.SAXException - May throw this if it needs to create a XMLReader, and XMLReaderFactory.createXMLReader() fails.
java.io.IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
ProcessorException - May throw this during the parse when it is constructing the Templates object and fails.

processFromNode

public abstract Templates processFromNode(org.w3c.dom.Node node)
                                   throws ProcessorException
Process the stylesheet from a DOM tree, if the processor supports the "http://xml.org/trax/features/dom/input" feature.
Parameters:
node - A DOM tree which must contain valid transform instructions that this processor understands.

processMultiple

public abstract Templates processMultiple(org.xml.sax.InputSource[] source)
                                   throws ProcessorException
Process a series of inputs, treating them in import or cascade order. This is mainly for support of the getAssociatedStylesheets method, but may be useful for other purposes.
Parameters:
sources - An array of SAX InputSource objects.

getAssociatedStylesheets

public abstract org.xml.sax.InputSource[] getAssociatedStylesheets(org.xml.sax.InputSource source,
                                                                   java.lang.String media,
                                                                   java.lang.String title,
                                                                   java.lang.String charset)
                                                            throws ProcessorException
Get InputSource specification(s) that are associated with the given document specified in the source param, via the xml-stylesheet processing instruction (see http://www.w3.org/TR/xml-stylesheet/), and that matches the given criteria. Note that it is possible to return several stylesheets that match the criteria, in which case they are applied as if they were a list of imports or cascades.

Note that DOM2 has it's own mechanism for discovering stylesheets. Therefore, there isn't a DOM version of this method.

Open issues:

Does the xml-stylesheet recommendation really support multiple stylesheets?

Mike Kay wrote: I don't see any support in the xml-stylesheet recommendation for this interpretation of what you should do if there's more than one match. Scott Boag replies: It's in the HTML references. But it's a bit subtle. We talked about this at the last XSL WG F2F, and people agreed to the multiple stylesheet stuff. I'll try and work out the specific references. Probably the xml-stylesheet recommendation needs to have a note added to it.
Parameters:
media - The media attribute to be matched. May be null, in which case the prefered templates will be used (i.e. alternate = no).
title - The value of the title attribute to match. May be null.
charset - The value of the charset attribute to match. May be null.

getTemplatesBuilder

public abstract TemplatesBuilder getTemplatesBuilder()
                                              throws ProcessorException
Get a TemplatesBuilder object that can process SAX events into a Templates object, if the processor supports the "http://xml.org/trax/features/sax/input" feature.

Open issues:

Should Processor derive from org.xml.sax.ContentHandler?

Instead of requesting an object from the Processor class, should the Processor class simply derive from org.xml.sax.ContentHandler?
Returns:
A TemplatesBuilder object, or null if not supported.
Throws:
May - throw a ProcessorException if a TemplatesBuilder can not be constructed for some reason.

setXMLReader

public void setXMLReader(org.xml.sax.XMLReader reader)
Set an XML parser for the templates. This may also be used for the XML input for the source tree, if the setXMLReader method on the Transformation method is not set.

getXMLReader

public org.xml.sax.XMLReader getXMLReader()
Get the XML parser used for the templates. This may also be used for the XML input for the source tree, if the setXMLReader method on the Transformation method is not set.
Returns:
Valid XMLReader object, or null if none has been set.

getFeature

public boolean getFeature(java.lang.String name)
                   throws org.xml.sax.SAXNotRecognizedException,
                          org.xml.sax.SAXNotSupportedException
Look up the value of a feature.

The feature name is any fully-qualified URI. It is possible for an Processor to recognize a feature name but to be unable to return its value; this is especially true in the case of an adapter for a SAX1 Parser, which has no way of knowing whether the underlying parser is validating, for example.

Open issues:

Should getFeature be changed to hasFeature?

Keith Visco writes: Should getFeature be changed to hasFeature? It returns a boolean which indicated whether the "state" of feature is "true or false". I assume this means whether or not a feature is supported? I know SAX is using "getFeature", but to me "hasFeature" is cleaner.
Parameters:
name - The feature name, which is a fully-qualified URI.
Returns:
The current state of the feature (true or false).
Throws:
org.xml.sax.SAXNotRecognizedException - When the Processor does not recognize the feature name.
org.xml.sax.SAXNotSupportedException - When the Processor recognizes the feature name but cannot determine its value at this time.

setFeature

public void setFeature(java.lang.String name,
                       boolean value)
                throws org.xml.sax.SAXNotRecognizedException,
                       org.xml.sax.SAXNotSupportedException
Set the state of a feature.

The feature name is any fully-qualified URI. It is possible for an Processor to recognize a feature name but to be unable to set its value; this is especially true in the case of an adapter for a SAX1 Parser, which has no way of affecting whether the underlying parser is validating, for example.

Parameters:
name - The feature name, which is a fully-qualified URI.
state - The requested state of the feature (true or false).
Throws:
org.xml.sax.SAXNotRecognizedException - When the Processor does not recognize the feature name.
org.xml.sax.SAXNotSupportedException - When the Processor recognizes the feature name but cannot set the requested value.

setURIResolver

public void setURIResolver(URIResolver resolver)
Set an object that will be used to resolve URIs used in xsl:import, etc. This will be used as the default for the transformation.
Parameters:
resolver - An object that implements the URIResolver interface, or null.

getURIResolver

public URIResolver getURIResolver()
Set an object that will be used to resolve URIs used in xsl:import, etc. This will be used as the default for the transformation.
Parameters:
resolver - An object that implements the URIResolver interface, or null.

setErrorHandler

public void setErrorHandler(org.xml.sax.ErrorHandler handler)
Allow an application to register an error event handler.

If the application does not register an error handler, all error events reported by the SAX parser will be silently ignored; however, normal processing may not continue. It is highly recommended that all SAX applications implement an error handler to avoid unexpected bugs.

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Parameters:
handler - The error handler.
Throws:
java.lang.NullPointerException - If the handler argument is null.
See Also:
getErrorHandler()

getErrorHandler

public org.xml.sax.ErrorHandler getErrorHandler()
Return the current error handler.
Returns:
The current error handler, or null if none has been registered.
See Also:
setErrorHandler(org.xml.sax.ErrorHandler)