/*
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/
package org.apache.xalan.xslt;
import java.util.TooManyListenersException;
import java.util.Vector;
import org.apache.xalan.xpath.XObject;
import org.apache.xalan.xpath.XNodeSet;
import org.apache.xalan.xpath.XBoolean;
import org.apache.xalan.xpath.XNumber;
import org.apache.xalan.xpath.XNull;
import org.apache.xalan.xpath.XString;
import org.apache.xalan.xpath.xml.XMLParserLiaison;
import org.apache.xalan.xpath.xml.ProblemListener;
import org.apache.xalan.templates.Stylesheet;
//import org.apache.xalan.templates.StylesheetRoot;
//import org.apache.xalan.xslt.StylesheetSpec;
import org.apache.xalan.trace.*;
import org.w3c.dom.NodeList;
import org.w3c.dom.Node;
import org.xml.sax.DocumentHandler;
import org.xml.sax.SAXException;
import java.io.OutputStream;
import java.io.UnsupportedEncodingException;
import org.apache.xml.serialize.OutputFormat;
import org.xml.sax.ext.LexicalHandler;
/**
* <meta name="usage" content="general"/>
* The transformation processor -- use {@link org.apache.xalan.xslt.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 <code>process(...)</code> are the primary
* public entry points.
*
* Look at the Process class main() method for
* for an advanced usage example.
*
* <p>If you reuse the processor instance, you should call reset() between transformations.</p>
* @deprecated This compatibility layer will be removed in later releases.
*/
public interface XSLTProcessor extends DocumentHandler, LexicalHandler
{
/**
* Use the XSL stylesheet to transform the XML input, placing the result in the result tree.
* @param xmlSource The XML input to be transformed.
* @param xslStylesheet The XSL stylesheet to be used for the transformation. May be null if XML input
* has an XSL stylesheet PI.
* @param resultTree The tree where the result of the transformation is placed.
* @exception XSLProcessorException thrown if the active ProblemListener and XMLParserLiaison decide
* the error condition is severe enough to halt processing.
*/
public void process( XSLTInputSource xmlSource,
XSLTInputSource xslStylesheet,
XSLTResultTarget resultTree)
throws 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.
*
* @param stylesheetSource The XSL stylesheet.
* @return The compiled stylesheet object.
* @exception XSLProcessorException thrown if the active ProblemListener and XMLParserLiaison decide
* the error condition is severe enough to halt processing.
*/
public StylesheetRoot processStylesheet(XSLTInputSource stylesheetSource)
throws 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.
*
* @param xsldocURLString The URL to the XSL stylesheet.
* @return The compiled stylesheet object.
* @exception XSLProcessorException thrown if the active ProblemListener and XMLParserLiaison decide
* the error condition is severe enough to halt processing.
*/
public StylesheetRoot processStylesheet(String xsldocURLString)
throws SAXException;
/**
* Set the output stream. Required when the XSLTProcessor is being used
* as a SAX DocumentHandler.
*/
public void setOutputStream(java.io.OutputStream os);
/**
* Reset the XSLTProcessor state. Must be used after a process() call
* if the XSLTProcessor instance is to be used again.
*/
public void reset();
/**
* 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).
*/
public Node getSourceTreeFromInput(XSLTInputSource inputSource)
throws org.xml.sax.SAXException;
/**
* 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.
*/
public void setStylesheet(StylesheetRoot stylesheetRoot);
/**
* Get the current Stylesheet setting for this XSLTProcessor.
*/
public StylesheetRoot getStylesheet();
/**
* Get the XMLParserLiaison that this processor uses.
*/
public XMLParserLiaison getXMLProcessorLiaison();
/**
* Get the preferred stylesheet for the XSLTInputSource XML document,
* as identified by the xml-stylesheet PI, and matching the media and
* charset criteria. See <a href="http://www.w3.org/TR/xml-stylesheet/">
* Associating Style Sheets with XML documents</a>.
* Does not yet handle the LINK REL="stylesheet" syntax.
*
* @param media The media attribute to be matched. May be null, in which
* case the prefered stylesheet will be used (i.e., alternate = no).
* @param title The value of the title attribute to match. May be null.
* @param charset The value of the charset attribute to match. May be null.
* @returns StylesheetSpec extends XSLTInputSource extends SAX InputSource; the return value
* can be passed to the processStylesheet method.
*/
public StylesheetSpec getAssociatedStylesheet(XSLTInputSource source,
String media,
String charset)
throws 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 <a href="http://www.w3.org/TR/xml-stylesheet/">
* Associating Style Sheets with XML documents</a>.
* Does not yet handle the LINK REL="stylesheet" syntax.
*
* @param media The media attribute to be matched. May be null, in which
* case the prefered stylesheet will be used (i.e., alternate = no).
* @param title The value of the title attribute to match. May be null.
* @param charset The value of the charset attribute to match. May be null.
* @returns list of StylesheetSpecs (extend XSLTInputSources extend SAX InputSources; a
* list member may be passsed to the processStylesheet method.
*/
public Vector getAssociatedStylesheets(XSLTInputSource source,
String media,
String charset)
throws SAXException;
/**
* Convenience function to create an XString.
* @param s A valid string.
* @return An XString object.
*/
public XString createXString(String s);
/**
* Convenience function to create an XObject.
* @param o Any java object.
* @return An XObject object.
*/
public XObject createXObject(Object o);
/**
* Convenience function to create an XNumber.
* @param d Any double number.
* @return An XNumber object.
*/
public XNumber createXNumber(double d);
/**
* Convenience function to create an XBoolean.
* @param b boolean value.
* @return An XBoolean object.
*/
public XBoolean createXBoolean(boolean b);
/**
* Convenience function to create an XNodeSet.
* @param nl A NodeList object.
* @return An XNodeSet object.
*/
public XNodeSet createXNodeSet(NodeList nl);
/**
* Convenience function to create an XNodeSet from a node.
* @param n A DOM node.
* @return An XNodeSet object.
*/
public XNodeSet createXNodeSet(Node n);
/**
* Convenience function to create an XNull.
* @return An XNull object.
*/
public XNull createXNull();
/**
* Submit a top-level stylesheet parameter. This value can
* be evaluated in the stylesheet via xsl:param-variable.
* @param key The name of the param.
* @param value An XObject that will be used.
*/
public void setStylesheetParam(String key, XObject value);
/**
* 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
* @param key The name of the param.
* @param expression An expression that will be evaluated.
*/
public void setStylesheetParam(String key, String expression);
/**
* Get the current FormatterListener (SAX DocumentHandler), or null if none has been set.
*/
public DocumentHandler getFormatterListener();
/**
* Set the FormatterListener (the SAX DocumentHandler).
*/
public void setFormatterListener(DocumentHandler flistener);
/**
* Get the current SAX DocumentHandler (the same object as the FormatterListener), or null if none has been set.
*/
public DocumentHandler getDocumentHandler();
/**
* Set the current SAX DocumentHandler (the same
* object as the FormatterListener).
*/
public void setDocumentHandler(DocumentHandler listener);
/**
* Add a trace listener for the purposes of debugging and diagnosis.
* @param tl Trace listener to be added.
*/
public void addTraceListener(TraceListener tl)
throws TooManyListenersException;
/**
* If set to true, template calls are traced.
*/
public void setTraceTemplates(boolean b);
/**
* If set to true, selection events are traced.
*/
public void setTraceSelect(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.
*/
public void setTraceTemplateChildren(boolean b);
/**
* If set to true (the default), pattern conflict warnings are not printed to the diagnostics stream.
* @param b true if conflict warnings should be suppressed.
*/
public void setQuietConflictWarnings(boolean b);
/**
* Remove a trace listener.
* @param tl Trace listener to be removed.
*/
public void removeTraceListener(TraceListener tl);
/**
* If set, diagnostics will be
* written to the m_diagnosticsPrintWriter stream. If
* null, diagnostics are turned off. This convenience method calls
* {@link #setDiagnosticsOutput(java.io.PrintWriter)}.
*/
public void setDiagnosticsOutput(java.io.OutputStream out);
/**
* If set, diagnostics will be
* written to the m_diagnosticsPrintWriter stream. If
* null, diagnostics are turned off.
*/
public void setDiagnosticsOutput(java.io.PrintWriter pw);
/**
* 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).
* @param l A ProblemListener interface.
*/
public void setProblemListener(ProblemListener l);
/**
* 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).
* @return A ProblemListener interface.
*/
public ProblemListener getProblemListener();
}