com.novell.xsl.result
Class SAXResultHandler

java.lang.Object
  extended bycom.novell.xsl.result.SAXResultHandler
All Implemented Interfaces:
Parser, ResultHandler

public class SAXResultHandler
extends Object
implements ResultHandler, Parser

Result handler for the NXSL processor that passes on result tree events as SAX events.

There are two primary methods of using this class:

1: Construct an instance with a passed Stylesheet (the first four constructors) and then call parse(), or

2: Construct an instance without an attached Stylesheet and then set the constructed object as the result handler for a stylesheet (Stylesheet.setResultHandler()). The SAX events are generated in the second case by calling Stylesheet.process().


Field Summary
protected  List attributeNames
          Names of attributes being marshalled for the DocumentHandler.startElement() notification.
protected  List attributeValues
          Values of attributes being marshalled for the DocumentHandler.startElement() notification.
protected  AttributeListImpl attrList
          AttributeList to use for DocumentHandler.startElement() notifications
protected  NamespaceStack currentNamespaces
          Stack of namespace declarations currently in effect.
protected  DocumentHandler documentHandler
          The SAX DocumentHandler to which to route event notifications
protected  boolean doPIComments
          If true, send comment notifications as processing instruction events with a null target.
protected  String elementName
          The unexpanded name of the current element
protected  ErrorHandler errorHandler
          The SAX error handler to which to route error notifications
protected  Parser parser
          The SAX Parser to use when parse() is called.
protected  Document sourceDocument
          The DOM source document to use as input to the stylesheet.
protected  boolean startTagOpen
          If true, have received a startElement() notification but have not yet forwarded the notification to the DocumentHandler.
protected  Stack stateStack
          Stack of state (changed by elements)
protected  Stylesheet stylesheet
          The Stylesheet object to use in generating the events
 
Constructor Summary
SAXResultHandler()
          Construct a SAX result handler that will translate NXSL ResultHandler events into SAX events.
SAXResultHandler(Document sourceDocument, Stylesheet stylesheet)
          Construct a SAX result handler given a DOM source document and a Stylesheet object that was previous constructed and compiled.
SAXResultHandler(Parser sourceParser, Stylesheet stylesheet)
          Construct a SAX result handler given a SAX Parser to use to parse the source document and a Stylesheet object that was previously constructed and compiled.
SAXResultHandler(String stylesheetURL)
          Construct a SAX result handler given the URL of an XSLT stylesheet.
SAXResultHandler(Stylesheet stylesheet)
          Construct a SAX result handler that will use the passed stylesheet to process the xml document passed to parse() The parse() method of the resulting object can then be called to generate the XSLT result tree events.
 
Method Summary
 void attribute(String name, String value)
          Receive notification of an attribute.
 void characters(String data)
          Receive notification of character data.
protected  void closeStartTag()
          Close any open element start tag by sending SAX startElement event
 void comment(String value)
          Receive notification of a comment.
 void endDocument()
          Receive notification of the end of a document.
 void endElement(String name)
          Receive notification of the end of an element.
protected  ExpandedQName getExpandedName(String qName, boolean isAttribute)
          Get the expanded name for a node QName using the currently in-scope namespace nodes.
 void namespace(String name, NamespaceName value)
          Receive notification of a namespace node.
 void parse(InputSource source)
          Parse an XML document.
 void parse(String systemId)
          Parse an XML document from a system identifier (URI).
protected  void popState()
          Restore the last element state
 void processingInstruction(String target, String value)
          Receive notification of a processing instruction.
protected  void pushState()
          Save the current element state
 void setDocumentHandler(DocumentHandler handler)
          Allow an application to register a document event handler.
 void setDTDHandler(DTDHandler handler)
          Allow an application to register a DTD event handler.
 void setEntityResolver(EntityResolver resolver)
          Allow an application to register a custom entity resolver.
 void setErrorHandler(ErrorHandler handler)
          Allow an application to register an error event handler.
 void setLocale(Locale locale)
          Allow an application to request a locale for errors and warnings.
 void setUsePIComment(boolean usePIComment)
          Cause this object to generate comment events by calling DocumentHandler.processingInstruction() with a null target and the comment data in the data parameter.
 void startDocument()
          Receive notification of the beginning of a document.
 void startElement(String name, String namespaceURI)
          Receive notification of the beginning of an element.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

documentHandler

protected DocumentHandler documentHandler
The SAX DocumentHandler to which to route event notifications


errorHandler

protected ErrorHandler errorHandler
The SAX error handler to which to route error notifications


doPIComments

protected boolean doPIComments
If true, send comment notifications as processing instruction events with a null target.


elementName

protected String elementName
The unexpanded name of the current element


startTagOpen

protected boolean startTagOpen
If true, have received a startElement() notification but have not yet forwarded the notification to the DocumentHandler.


attributeNames

protected List attributeNames
Names of attributes being marshalled for the DocumentHandler.startElement() notification.


attributeValues

protected List attributeValues
Values of attributes being marshalled for the DocumentHandler.startElement() notification.


currentNamespaces

protected NamespaceStack currentNamespaces
Stack of namespace declarations currently in effect.


stateStack

protected Stack stateStack
Stack of state (changed by elements)


attrList

protected AttributeListImpl attrList
AttributeList to use for DocumentHandler.startElement() notifications


stylesheet

protected Stylesheet stylesheet
The Stylesheet object to use in generating the events


parser

protected Parser parser
The SAX Parser to use when parse() is called. If this is null, XMLParserFactory will be used to get a parser to use.


sourceDocument

protected Document sourceDocument
The DOM source document to use as input to the stylesheet. If this is non-null, the argument to parse() will be ignored.

Constructor Detail

SAXResultHandler

public SAXResultHandler(String stylesheetURL)
                 throws IOException,
                        XSLException
Construct a SAX result handler given the URL of an XSLT stylesheet. The parse() method of the resulting object can then be called to generate the SAX events for the XSLT result tree.

Parameters:
stylesheetURL - The URL of the stylesheet document. The URL may be relative if it is a filename.

SAXResultHandler

public SAXResultHandler(Parser sourceParser,
                        Stylesheet stylesheet)
Construct a SAX result handler given a SAX Parser to use to parse the source document and a Stylesheet object that was previously constructed and compiled. The parse() method of the resulting object can then be called to generate the XSLT result tree events.

Parameters:
sourceParser - The SAX parser that will be used to generate source document events.
stylesheet - The Stylesheet object to be applied to the source document.

SAXResultHandler

public SAXResultHandler(Document sourceDocument,
                        Stylesheet stylesheet)
Construct a SAX result handler given a DOM source document and a Stylesheet object that was previous constructed and compiled. The parse() method of the resulting object can then be called to generate the XSLT result tree events. Note, however, that the parameter to parse() will be ignored in this case, since the sourceDocument does not need to be parsed.

Parameters:
sourceDocument - The DOM source document to transform.
stylesheet - The Stylesheet object to be applied to the source document.

SAXResultHandler

public SAXResultHandler(Stylesheet stylesheet)
Construct a SAX result handler that will use the passed stylesheet to process the xml document passed to parse() The parse() method of the resulting object can then be called to generate the XSLT result tree events.

Parameters:
stylesheet - The Stylesheet object to be applied to the source document.

SAXResultHandler

public SAXResultHandler()
Construct a SAX result handler that will translate NXSL ResultHandler events into SAX events. Note that the parse() method of the resulting object must not be called. Instead, call Stylesheet.setResultHandler() with the resulting object as the parameter and then call Stylesheet.process() to generate the SAX events.

Method Detail

setUsePIComment

public void setUsePIComment(boolean usePIComment)
Cause this object to generate comment events by calling DocumentHandler.processingInstruction() with a null target and the comment data in the data parameter. This method of generating comments using standard SAX events was swiped from James Clark's XP XML parser.

Parameters:
usePIComment - true to generate comment events using DocumentHandler.processingInstruction().
See Also:
DocumentCommentHandler

startDocument

public void startDocument()
                   throws ResultException
Receive notification of the beginning of a document. This will forward the notification to the SAX DocumentHandler.

Specified by:
startDocument in interface ResultHandler
Throws:
ResultException - if an implementation-dependent error occurs

endDocument

public void endDocument()
                 throws ResultException
Receive notification of the end of a document. This will forward the notification to the SAX DocumentHandler.

Specified by:
endDocument in interface ResultHandler
Throws:
ResultException - if an implementation-dependent error occurs

startElement

public void startElement(String name,
                         String namespaceURI)
                  throws IllegalNameException,
                         IllegalNodeException,
                         ResultException
Receive notification of the beginning of an element. This will not foward the notification to the SAX DocumentHandler since attributes and namespace nodes have not yet been sent.

Specified by:
startElement in interface ResultHandler
Parameters:
name - the element's name
namespaceURI - the element's namespace uri
Throws:
IllegalNameException - if the specified element name is illegal
IllegalNodeException - if the current node cannot contain elements
ResultException - if an implementation-dependent error occurs

endElement

public void endElement(String name)
                throws ResultException
Receive notification of the end of an element. This will foward the notification to the SAX DocumentHandler. It may also cause a DocumentHandler.startElement() notification.

Specified by:
endElement in interface ResultHandler
Throws:
ResultException - if an implementation-dependent error occurs

attribute

public void attribute(String name,
                      String value)
               throws AttributeAfterChildException,
                      IllegalNameException,
                      IllegalNodeException,
                      ResultException
Receive notification of an attribute. This will save the attribute for a later notification to the DocumentHandler.startElement() method.

Specified by:
attribute in interface ResultHandler
Parameters:
name - the attribute's name
value - the attribute's value
Throws:
AttributeAfterChildException - if the current node is an element with children (attributes cannot be added to an element after children have been added to it)
IllegalNameException - if the specified attribute name is illegal
IllegalNodeException - if the current node is not an element
ResultException - if an implementation-dependent error occurs

characters

public void characters(String data)
                throws IllegalNodeException,
                       ResultException
Receive notification of character data. This will forward the notification to the DocumentHandler. It may also cause a DocumentHandler.startElement() notification.

Specified by:
characters in interface ResultHandler
Parameters:
data - the character data
Throws:
IllegalNodeException - if the current node cannot contain character data
ResultException - if an implementation-dependent error occurs

processingInstruction

public void processingInstruction(String target,
                                  String value)
                           throws IllegalNameException,
                                  IllegalNodeException,
                                  ResultException
Receive notification of a processing instruction. This will forward the notification to the DocumentHandler. It may also cause a DocumentHandler.startElement() notification.

Specified by:
processingInstruction in interface ResultHandler
Parameters:
target - the processing instruction's target
value - the processing instruction's value, or null if there is no value
Throws:
IllegalNameException - if the specified target name is illegal
IllegalNodeException - if the current node cannot contain processing instructions
ResultException - if an implementation-dependent error occurs

comment

public void comment(String value)
             throws IllegalNodeException,
                    ResultException
Receive notification of a comment. This will forward the notification to the DocumentHandler if the DocumentHandler is an instance of com.novell.xml.sax.CommentDocumentHandler or if usePIComments is true. It may also cause a DocumentHandler.startElement() notification.

Specified by:
comment in interface ResultHandler
Parameters:
value - the comment's value
Throws:
IllegalNodeException - if the current node cannot contain comments
ResultException - if an implementation-dependent error occurs

namespace

public void namespace(String name,
                      NamespaceName value)
               throws IllegalNodeException,
                      ResultException
Receive notification of a namespace node. This will save the namespace declaration as an attribute for notification with the startElement() notification. An implementation should keep track of what namespace attributes are in scope in the xml representation to avoid placing redundant attributes on elements.

Specified by:
namespace in interface ResultHandler
Parameters:
name - the namespace prefix
value - the namespace name (URI)
Throws:
IllegalNodeException - if the current node cannot contain namespaces
ResultException - if an implementation-dependent error occurs

setLocale

public void setLocale(Locale locale)
               throws SAXException
Allow an application to request a locale for errors and warnings.

SAX parsers are not required to provide localisation for errors and warnings; if they cannot support the requested locale, however, they must throw a SAX exception. Applications may not request a locale change in the middle of a parse.

Specified by:
setLocale in interface Parser
Parameters:
locale - A Java Locale object.
Throws:
SAXException - Throws an exception (using the previous or default locale) if the requested locale is not supported.
See Also:
SAXException, SAXParseException

setEntityResolver

public void setEntityResolver(EntityResolver resolver)
Allow an application to register a custom entity resolver.

If the application does not register an entity resolver, the SAX parser will resolve system identifiers and open connections to entities itself (this is the default behaviour implemented in HandlerBase).

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

Specified by:
setEntityResolver in interface Parser
Parameters:
resolver - The object for resolving entities.
See Also:
EntityResolver, HandlerBase

setDTDHandler

public void setDTDHandler(DTDHandler handler)
Allow an application to register a DTD event handler.

If the application does not register a DTD handler, all DTD events reported by the SAX parser will be silently ignored (this is the default behaviour implemented by HandlerBase).

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.

Specified by:
setDTDHandler in interface Parser
Parameters:
handler - The DTD handler.
See Also:
DTDHandler, HandlerBase

setDocumentHandler

public void setDocumentHandler(DocumentHandler handler)
Allow an application to register a document event handler.

If the application does not register a document handler, all document events reported by the SAX parser will be silently ignored (this is the default behaviour implemented by HandlerBase).

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.

Specified by:
setDocumentHandler in interface Parser
Parameters:
handler - The document handler.
See Also:
DocumentHandler, HandlerBase

setErrorHandler

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

If the application does not register an error event handler, all error events reported by the SAX parser will be silently ignored, except for fatalError, which will throw a SAXException (this is the default behaviour implemented by HandlerBase).

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.

Specified by:
setErrorHandler in interface Parser
Parameters:
handler - The error handler.
See Also:
ErrorHandler, SAXException, HandlerBase

parse

public void parse(InputSource source)
           throws SAXException,
                  IOException
Parse an XML document.

The application can use this method to instruct the SAX parser to begin parsing an XML document from any valid input source (a character stream, a byte stream, or a URI).

Applications may not invoke this method while a parse is in progress (they should create a new Parser instead for each additional XML document). Once a parse is complete, an application may reuse the same Parser object, possibly with a different input source.

Specified by:
parse in interface Parser
Parameters:
source - The input source for the top-level of the XML document.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
See Also:
InputSource, parse(java.lang.String), setEntityResolver(org.xml.sax.EntityResolver), setDTDHandler(org.xml.sax.DTDHandler), setDocumentHandler(org.xml.sax.DocumentHandler), setErrorHandler(org.xml.sax.ErrorHandler)

parse

public void parse(String systemId)
           throws SAXException,
                  IOException
Parse an XML document from a system identifier (URI).

This method is a shortcut for the common case of reading a document from a system identifier. It is the exact equivalent of the following:

 parse(new InputSource(systemId));
 

If the system identifier is a URL, it must be fully resolved by the application before it is passed to the parser.

Specified by:
parse in interface Parser
Parameters:
systemId - The system identifier (URI).
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
See Also:
parse(org.xml.sax.InputSource)

closeStartTag

protected void closeStartTag()
                      throws ResultException
Close any open element start tag by sending SAX startElement event

Throws:
ResultException

getExpandedName

protected ExpandedQName getExpandedName(String qName,
                                        boolean isAttribute)
                                 throws IllegalNameException
Get the expanded name for a node QName using the currently in-scope namespace nodes.

Parameters:
qName - The QName to expand
isAttribute - True if the name is for an attribute node
Returns:
The expanded name of the passed QName
Throws:
IllegalNameException

pushState

protected void pushState()
Save the current element state


popState

protected void popState()
Restore the last element state