WebLogic Server 6.1 API Reference

weblogic.apache.xalan.xslt
Interface XSLTProcessor

All Known Implementing Classes:

XSLTEngineImpl

public interface XSLTProcessor

extends org.xml.sax.DocumentHandler, org.xml.sax.ext.LexicalHandler

The transformation processor -- use XSLTProcessorFactory to instantiate an implementation of this interface. It's the responsibility of the implementation (XSLTEngineImpl), collaborating with a XMLParserLiaison, the DOM, and the XPath engine, to transform a source tree of nodes into a result tree according to instructions and templates specified by a stylesheet tree. Use the process(...) are the primary public entry points. Look at the Process class main() method for for an advanced usage example.

If you reuse the processor instance, you should call reset() between transformations.

This class is based on an implementation from the Apache XML Project. In future releases the XML parser, XSLT processor, and associated classes will likely be updated to be based on a later version of the Apache implementations. Since Apache does not guarantee backwards compatibility between versions of their software, we cannot guarantee backwards compatibility of any of the classes contained in the weblogic.apache package or sub-packages.

Method Summary

void	addTraceListener(TraceListener tl) Add a trace listener for the purposes of debugging and diagnosis.
XBoolean	createXBoolean(boolean b) Convenience function to create an XBoolean.
XNodeSet	createXNodeSet(org.w3c.dom.Node n) Convenience function to create an XNodeSet from a node.
XNodeSet	createXNodeSet(org.w3c.dom.NodeList nl) Convenience function to create an XNodeSet.
XNull	createXNull() Convenience function to create an XNull.
XNumber	createXNumber(double d) Convenience function to create an XNumber.
XObject	createXObject(java.lang.Object o) Convenience function to create an XObject.
XString	createXString(java.lang.String s) Convenience function to create an XString.
StylesheetSpec	getAssociatedStylesheet(XSLTInputSource source, java.lang.String media, java.lang.String charset) Get the preferred stylesheet for the XSLTInputSource XML document, as identified by the xml-stylesheet PI, and matching the media and charset criteria.
java.util.Vector	getAssociatedStylesheets(XSLTInputSource source, java.lang.String media, java.lang.String charset) Get a list of stylesheet specifications for the XSLTInputSource XML document, as identified by the xml-stylesheet PI, and matching the media and charset criteria.
org.xml.sax.DocumentHandler	getDocumentHandler() Get the current SAX DocumentHandler (the same object as the FormatterListener), or null if none has been set.
org.xml.sax.DocumentHandler	getFormatterListener() Get the current FormatterListener (SAX DocumentHandler), or null if none has been set.
ProblemListener	getProblemListener() Get the problem listener property.
org.w3c.dom.Node	getSourceTreeFromInput(XSLTInputSource inputSource) Get the DOM Node from the XSLTInputSource object.
StylesheetRoot	getStylesheet() Get the current Stylesheet setting for this XSLTProcessor.
XMLParserLiaison	getXMLProcessorLiaison() Get the XMLParserLiaison that this processor uses.
void	process(XSLTInputSource xmlSource, XSLTInputSource xslStylesheet, XSLTResultTarget resultTree) Use the XSL stylesheet to transform the XML input, placing the result in the result tree.
StylesheetRoot	processStylesheet(java.lang.String xsldocURLString) Given a URL to (or file name of) an XSL stylesheet, Compile the stylesheet into an internal representation, and use it to set the XSLTProcessor Stylesheet property.
StylesheetRoot	processStylesheet(XSLTInputSource stylesheetSource) Compile the XSL stylesheet represented by an XSLTInputSource object into an internal representation, and use it to set the XSLTProcessor Stylesheet property.
void	removeTraceListener(TraceListener tl) Remove a trace listener.
void	reset() Reset the XSLTProcessor state.
void	setDiagnosticsOutput(java.io.OutputStream out) If set, diagnostics will be written to the m_diagnosticsPrintWriter stream.
void	setDiagnosticsOutput(java.io.PrintWriter pw) If set, diagnostics will be written to the m_diagnosticsPrintWriter stream.
void	setDocumentHandler(org.xml.sax.DocumentHandler listener) Set the current SAX DocumentHandler (the same object as the FormatterListener).
void	setFormatterListener(org.xml.sax.DocumentHandler flistener) Set the FormatterListener (the SAX DocumentHandler).
void	setOutputStream(java.io.OutputStream os) Set the output stream.
void	setProblemListener(ProblemListener l) Set the problem listener property.
void	setQuietConflictWarnings(boolean b) If set to true (the default), pattern conflict warnings are not printed to the diagnostics stream.
void	setStylesheet(StylesheetRoot stylesheetRoot) Use a compiled stylesheet to set the Stylesheet property for this processor.
void	setStylesheetParam(java.lang.String key, java.lang.String expression) Set a top-level stylesheet parameter.
void	setStylesheetParam(java.lang.String key, XObject value) Submit a top-level stylesheet parameter.
void	setTraceSelect(boolean b) If set to true, selection events are traced.
void	setTraceTemplateChildren(boolean b) If set to true (the default is false), as template children are being constructed, debug diagnostics are written to the m_diagnosticsPrintWriter stream.
void	setTraceTemplates(boolean b) If set to true, template calls are traced.

Methods inherited from interface org.xml.sax.DocumentHandler

characters, endDocument, endElement, ignorableWhitespace, processingInstruction, setDocumentLocator, startDocument, startElement

Methods inherited from interface org.xml.sax.ext.LexicalHandler

comment, endCDATA, endDTD, endEntity, startCDATA, startDTD, startEntity

Method Detail

process

public void process(XSLTInputSource xmlSource,
                    XSLTInputSource xslStylesheet,
                    XSLTResultTarget resultTree)
             throws org.xml.sax.SAXException

Use the XSL stylesheet to transform the XML input, placing the result in the result tree.

Parameters:

xmlSource - The XML input to be transformed.

xslStylesheet - The XSL stylesheet to be used for the transformation. May be null if XML input has an XSL stylesheet PI.

resultTree - The tree where the result of the transformation is placed.

Throws:

XSLProcessorException - thrown if the active ProblemListener and XMLParserLiaison decide the error condition is severe enough to halt processing.

processStylesheet

public StylesheetRoot processStylesheet(XSLTInputSource stylesheetSource)
                                 throws org.xml.sax.SAXException

Compile the XSL stylesheet represented by an XSLTInputSource object into an internal representation, and use it to set the XSLTProcessor Stylesheet property. This operation is required if the XSLTProcessor is to function as a SAX DocumentHandler. If the Stylesheet property has already been set to non-null, this operation calls reset() before a transformation is performed.

Parameters:

stylesheetSource - The XSL stylesheet.

Returns:

The compiled stylesheet object.

Throws:

XSLProcessorException - thrown if the active ProblemListener and XMLParserLiaison decide the error condition is severe enough to halt processing.

processStylesheet

public StylesheetRoot processStylesheet(java.lang.String xsldocURLString)
                                 throws org.xml.sax.SAXException

Given a URL to (or file name of) an XSL stylesheet, Compile the stylesheet into an internal representation, and use it to set the XSLTProcessor Stylesheet property. This operation is required if the XSLTProcessor is to function as a SAX DocumentHandler. If the Stylesheet property has already been set to non-null, this operation calls reset() before a transformation is performed.

Parameters:

xsldocURLString - The URL to the XSL stylesheet.

Returns:

The compiled stylesheet object.

Throws:

XSLProcessorException - thrown if the active ProblemListener and XMLParserLiaison decide the error condition is severe enough to halt processing.

setOutputStream

public void setOutputStream(java.io.OutputStream os)

Set the output stream. Required when the XSLTProcessor is being used as a SAX DocumentHandler.

reset

public void reset()

Reset the XSLTProcessor state. Must be used after a process() call if the XSLTProcessor instance is to be used again.

getSourceTreeFromInput

public org.w3c.dom.Node getSourceTreeFromInput(XSLTInputSource inputSource)
                                        throws org.xml.sax.SAXException

Get the DOM Node from the XSLTInputSource object. Returns null if the XSLTInputSource object does not contain a Node (it may, for example, contain an input stream).

setStylesheet

public void setStylesheet(StylesheetRoot stylesheetRoot)

Use a compiled stylesheet to set the Stylesheet property for this processor. When this property is set, the process method uses this stylesheet rather than looking for a stylesheet PI if the stylesheet parameter is null. Also required if you are going to use the XSLTProcessor as a SAX DocumentHandler.

getStylesheet

public StylesheetRoot getStylesheet()

Get the current Stylesheet setting for this XSLTProcessor.

getXMLProcessorLiaison

public XMLParserLiaison getXMLProcessorLiaison()

Get the XMLParserLiaison that this processor uses.

getAssociatedStylesheet

public StylesheetSpec getAssociatedStylesheet(XSLTInputSource source,
                                              java.lang.String media,
                                              java.lang.String charset)
                                       throws org.xml.sax.SAXException

Get the preferred stylesheet for the XSLTInputSource XML document, as identified by the xml-stylesheet PI, and matching the media and charset criteria. See Associating Style Sheets with XML documents. Does not yet handle the LINK REL="stylesheet" syntax.

Parameters:

media - The media attribute to be matched. May be null, in which case the prefered stylesheet 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.

getAssociatedStylesheets

public java.util.Vector getAssociatedStylesheets(XSLTInputSource source,
                                                 java.lang.String media,
                                                 java.lang.String charset)
                                          throws org.xml.sax.SAXException

Get a list of stylesheet specifications for the XSLTInputSource XML document, as identified by the xml-stylesheet PI, and matching the media and charset criteria. See Associating Style Sheets with XML documents. Does not yet handle the LINK REL="stylesheet" syntax.

Parameters:

media - The media attribute to be matched. May be null, in which case the prefered stylesheet 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.

createXString

public XString createXString(java.lang.String s)

Convenience function to create an XString.

Parameters:

s - A valid string.

Returns:

An XString object.

createXObject

public XObject createXObject(java.lang.Object o)

Convenience function to create an XObject.

Parameters:

o - Any java object.

Returns:

An XObject object.

createXNumber

public XNumber createXNumber(double d)

Convenience function to create an XNumber.

Parameters:

d - Any double number.

Returns:

An XNumber object.

createXBoolean

public XBoolean createXBoolean(boolean b)

Convenience function to create an XBoolean.

Parameters:

b - boolean value.

Returns:

An XBoolean object.

createXNodeSet

public XNodeSet createXNodeSet(org.w3c.dom.NodeList nl)

Convenience function to create an XNodeSet.

Parameters:

nl - A NodeList object.

Returns:

An XNodeSet object.

createXNodeSet

public XNodeSet createXNodeSet(org.w3c.dom.Node n)

Convenience function to create an XNodeSet from a node.

Parameters:

n - A DOM node.

Returns:

An XNodeSet object.

createXNull

public XNull createXNull()

Convenience function to create an XNull.

Returns:

An XNull object.

setStylesheetParam

public void setStylesheetParam(java.lang.String key,
                               XObject value)

Submit a top-level stylesheet parameter. This value can be evaluated in the stylesheet via xsl:param-variable.

Parameters:

key - The name of the param.

value - An XObject that will be used.

setStylesheetParam

public void setStylesheetParam(java.lang.String key,
                               java.lang.String expression)

Set a top-level stylesheet parameter. This value can be evaluated via xsl:param-variable. Note that the value passed is an expression, and not a string. This means that setStylesheetParam("foo", "hello"); will look for the element "hello". If you want to pass a string, you'll need to put quotes around it: setStylesheetParam("foo", "'hello'"); will look for the

Parameters:

key - The name of the param.

expression - An expression that will be evaluated.

getFormatterListener

public org.xml.sax.DocumentHandler getFormatterListener()

Get the current FormatterListener (SAX DocumentHandler), or null if none has been set.

setFormatterListener

public void setFormatterListener(org.xml.sax.DocumentHandler flistener)

Set the FormatterListener (the SAX DocumentHandler).

getDocumentHandler

public org.xml.sax.DocumentHandler getDocumentHandler()

Get the current SAX DocumentHandler (the same object as the FormatterListener), or null if none has been set.

setDocumentHandler

public void setDocumentHandler(org.xml.sax.DocumentHandler listener)

Set the current SAX DocumentHandler (the same object as the FormatterListener).

addTraceListener

public void addTraceListener(TraceListener tl)
                      throws java.util.TooManyListenersException

Add a trace listener for the purposes of debugging and diagnosis.

Parameters:

tl - Trace listener to be added.

setTraceTemplates

public void setTraceTemplates(boolean b)

If set to true, template calls are traced.

setTraceSelect

public void setTraceSelect(boolean b)

If set to true, selection events are traced.

setTraceTemplateChildren

public void setTraceTemplateChildren(boolean b)

If set to true (the default is false), as template children are being constructed, debug diagnostics are written to the m_diagnosticsPrintWriter stream.

setQuietConflictWarnings

public void setQuietConflictWarnings(boolean b)

If set to true (the default), pattern conflict warnings are not printed to the diagnostics stream.

Parameters:

b - true if conflict warnings should be suppressed.

removeTraceListener

public void removeTraceListener(TraceListener tl)

Remove a trace listener.

Parameters:

tl - Trace listener to be removed.

setDiagnosticsOutput

public void setDiagnosticsOutput(java.io.OutputStream out)

If set, diagnostics will be written to the m_diagnosticsPrintWriter stream. If null, diagnostics are turned off. This convenience method calls setDiagnosticsOutput(java.io.PrintWriter).

setDiagnosticsOutput

public void setDiagnosticsOutput(java.io.PrintWriter pw)

If set, diagnostics will be written to the m_diagnosticsPrintWriter stream. If null, diagnostics are turned off.

setProblemListener

public void setProblemListener(ProblemListener l)

Set the problem listener property. The XSL class can have a single listener to be informed of errors and warnings. The problem listener normally controls whether an exception is thrown or not (or the problem listeners can throw its own RuntimeException).

Parameters:

l - A ProblemListener interface.

getProblemListener

public ProblemListener getProblemListener()

Get the problem listener property. The XSL class can have a single listener to be informed of errors and warnings. The problem listener normally controls whether an exception is thrown or not (or the problem listener can throw its own RuntimeException).

Returns:

A ProblemListener interface.