com.novell.xsl.parser
Class StylesheetParser

java.lang.Object
  extended bycom.novell.xsl.parser.StylesheetParser
All Implemented Interfaces:
FunctionLibrary, NamespaceContext

public class StylesheetParser
extends Object
implements NamespaceContext, FunctionLibrary

This class parses XSLT stylesheets and stores the information in a Stylesheet object. It relies on a DOM input tree. This class performs tree parse on the DOM objects to "compile" them into a tree of XSLT-specific objects.

The same stylesheet parser instance must be used to parse everything associated with a given stylesheet and cannot be reused to parse a different stylesheet.

It is important to realize that this class deals with five different parsers: the XSLT stylesheet parser represented by this class, the XML parser that parses standard XML (for parsing imported and included stylesheets), the XPath expression parser, the XSLT pattern parser, and the attribute value template (AVT) parser.

The implementation of the individual parsers for different xsl: elements is for the most part in separate classes, accessed through a static parse() method. Exceptions to this include xsl:include, xsl:import, xsl:sort, xsl:fallback, and xsl:stylesheet/xsl:transform.

Extension elements can be implemented by using a namespace of the form: http://www.novell.com/nxsl/java/{fully-qualified-class-name}. If the namespace is declared to be an extension element prefix and the namespace-qualified element appears where an XSLT instruction element may appear a Class object for the class name is retrieved and a method of the form:

public static com.novell.xsl.process.Template parse(StylesheetParser stylesheetParser, Element element) throws XSLTParserException;

is found and called through introspection.

If an element with a namespace of the above form is found as a top-level element a Class object for the class name is retrieved and a method of the form:

public static void parse(StylesheetParser stylesheetParser, Element element) throws XSLTParserException;

is found and called through introspection. The top-level extension element can use the methods setNamedObject(), getNamedObject(), and removeNamedObject() for storing state information.

Extension functions implemented in java can be used in XPath expressions by qualifying the function name with a namespace of the same sort used for extension elements. In this case, the class specified by the namespace is searched for a method matching the function name and signature specified by the function call. A constructor is specified by using the class name as the name of the function.

See Also:
AttrDef, Stylesheet

Constructor Summary
StylesheetParser(Stylesheet stylesheet)
          Constructs a new stylesheet parser that builds the specified Stylesheet object.
StylesheetParser(Stylesheet stylesheet, FunctionLibrary library)
          Constructs a new stylesheet parser that builds the specified Stylesheet object.
StylesheetParser(Stylesheet stylesheet, FunctionLibrary library, boolean brokenMode)
          Constructs a new stylesheet parser that builds the specified Stylesheet object.
 
Method Summary
 void addFunction(Function function)
          Add a function to the library
 StringBuffer buildErrorPrologue(StringBuffer prologue, Node contextNode, Node lineNumberContext)
          Construct an error message prologue containing as much context information as possible.
protected  void checkVariables()
          Check top-level variable references to ensure that they have all been defined.
 int getElementNumber()
          Get the current ordering number of elements in the stylesheet tree.
 ExpandedQName getExpandedName(String qName)
          Return the expanded name given the passed QName, given the current namespace context
 Function getFunction(ExpandedQName name)
          Return an object of type Function given the function name.
 int getImportPrecedence()
          Get the current import precedence number.
 Object getNamedObject(String name)
          Retrieve an object previously set using setNamedObject()
 NamespaceName getNamespaceName(String prefix)
          Return the currently in-scope namespace URI for the passed prefix.
 Parser getPatternParser()
          Return the XSLT pattern parser being used by this StylesheetParser.
 Stylesheet getStylesheet()
          Return the Stylesheet object for which the stylesheet parse is being performed.
 ParserVariables getVariables()
          Return the ParserVariables object used by this StylesheetParser.
 Parser getXPathParser()
          Return the XPath expression parser being used by this StylesheetParser.
protected  Template handleElementFallback(Element element)
          Handle any fallback information for an element.
protected  void includeStylesheet(Document xslDocument, URL baseURI)
          Includes the specified XSL document using the specified URI as the document's base URI.
 boolean isForwardsCompatibleMode()
          Return true if stylesheet parser is currently in forwards-compatible processing mode.
 boolean isFunctionAvailable(ExpressionContext context, ExpandedQName name)
          Return true if a function under a given name is available
 void parse(Document xsltDocument, URL baseURI)
          Parses the passed XSLT document.
 NamespaceName[] parseElementPrefixes(Node contextNode, String prefixList)
          Parse a whitespace separated list of prefixes.
protected  Template parseExtElement(Element element, NamespaceName namespace)
          Parse a non-xslt extension element template that appears as a descendant of an xsl:template element
protected  FallbackTemplate parseFallbackTemplate(Element element)
          Parse a single xsl:fallback element
protected  FallbackTemplatesTemplate parseFallbackTemplates(Node node, Node context)
          Parse child xsl:fallback elements of a given extension element
protected  void parseImport(Element element)
          Parses the specified xsl:import element.
protected  void parseInclude(Element element)
          Parses the specified xsl:include element.
protected  Document parseIncludeOrImport(Element element, URL[] uri)
          Perform common parsing and processing for xsl:include and xsl:import elements.
protected  Template parseLiteralElement(Element element)
          Parses the specified element as a literal result object.
 Collection parseQNames(Node contextNode, String string)
          Parse a whitespace separated list of QNames names and return a list of expanded names
 SortKey parseSortElement(Element element)
          Parse an xsl:sort element, returning a SortKey object.
 void parseStrippingList(Element contextNode, String elementList, boolean strip)
          Parse the "elements" attribute of an xsl:strip-space or xsl:preserve space element.
protected  void parseStylesheet(Element element)
          Parses the specified xsl:stylesheet element.
 Template[] parseTemplates(Node source, boolean sortWasAllowed)
          Parses the specified source node and its subsequent siblings as a template, and returns the result as an array of Template objects.
protected  void parseTopLevelExtElement(Element element, NamespaceName namespace)
          Parse a non-xsl top-level element that appears as the child of an xsl:stylesheet of xsl:transform element.
 Node popNSContext()
          Remove the current namespace context, restoring the namespace context that was in effect before the current.
 void pushNSContext(Node newContext)
          Change the namespace context to a new node.
 Object removeNamedObject(String name)
          Remove an object previously set using setNamedObject()
 Expression reportAttributeExpressionError(Element contextNode, String attrName, XPathParserException e)
          Report an XPath parser error for an attribute value.
 void reportError(Element topLevelContext, Node contextNode, String key)
          Report a parsing error by notifying the stylesheet's error handler.
 void reportError(Element topLevelContext, Node contextNode, String key, Object[] parms)
          Report a parsing error by notifying the stylesheet's error handler.
 void reportError(Element topLevelContext, Node contextNode, String key, String parm0)
          Report a parsing error by notifying the stylesheet's error handler.
 void reportError(Node contextNode, String key)
          Report a parsing error by notifying the stylesheet's error handler.
 void reportError(Node contextNode, String key, Object[] parms)
          Report a parsing error by notifying the stylesheet's error handler.
 void reportError(Node contextNode, String key, String parm0)
          Report a parsing error by notifying the stylesheet's error handler.
 void reportError(String msg)
          Report a parsing error by notifying the stylesheet's error handler.
 void reportInvalidAttributeValue(Element contextNode, String attrName, boolean isRequired, String attrValue)
          Report an invalid attribute value on an element.
 void reportWarning(Node contextNode, String msg)
          Reports a parsing warning by notifying the stylesheet's error handler.
 void setBuiltInDefinitions(Node namespaceContext)
          Sets the built-in definitions for the stylesheet that this stylesheet parser is building.
 void setNamedObject(String name, Object object)
          Store an object with the StylesheetParser by a name.
protected  void simplifiedStylesheet(Element element, RuleCollection ruleCollection)
          Parse a simplified stylesheet that consists just a literal result element.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

StylesheetParser

public StylesheetParser(Stylesheet stylesheet)
Constructs a new stylesheet parser that builds the specified Stylesheet object.

Parameters:
stylesheet - the stylesheet that this parser is building

StylesheetParser

public StylesheetParser(Stylesheet stylesheet,
                        FunctionLibrary library)
Constructs a new stylesheet parser that builds the specified Stylesheet object.

setBuiltInDefinitions() must be called before further building the stylesheet.

Parameters:
stylesheet - the stylesheet that this parser is building
library - The FunctionLibrary to use for this stylesheet.
See Also:
setBuiltInDefinitions(org.w3c.dom.Node)

StylesheetParser

public StylesheetParser(Stylesheet stylesheet,
                        FunctionLibrary library,
                        boolean brokenMode)
Constructs a new stylesheet parser that builds the specified Stylesheet object.

setBuiltInDefinitions() must be called before further building the stylesheet.

Parameters:
stylesheet - the stylesheet that this parser is building
library - The FunctionLibrary to use for this stylesheet.
brokenMode - if true then use old behavior that was broken but has since been fixed. This is used solely for backward compatibility.
See Also:
setBuiltInDefinitions(org.w3c.dom.Node)
Method Detail

setBuiltInDefinitions

public void setBuiltInDefinitions(Node namespaceContext)
                           throws XSLTParserException
Sets the built-in definitions for the stylesheet that this stylesheet parser is building.

Throws:
XSLTParserException - if a fatal error occurs during parsing

parse

public void parse(Document xsltDocument,
                  URL baseURI)
           throws XSLTParserException
Parses the passed XSLT document. The XSLT document's base URI is assumed to be unknown and is set to null. Note that a valid, non-null base URI is needed to properly resolve relative URIs in the XSLT document.

Parameters:
xsltDocument - the XSLT document to be imported
Throws:
XSLTParserException - if a fatal error occurs during parsing

isForwardsCompatibleMode

public boolean isForwardsCompatibleMode()
Return true if stylesheet parser is currently in forwards-compatible processing mode.

Returns:
true if stylesheet parser is currently in forwards-compatible processing mode.

getStylesheet

public Stylesheet getStylesheet()
Return the Stylesheet object for which the stylesheet parse is being performed.

Returns:
The Stylesheet object for which the stylesheet parse is being performed.

getXPathParser

public Parser getXPathParser()
Return the XPath expression parser being used by this StylesheetParser.

Returns:
The XPath expression Parser.

getPatternParser

public Parser getPatternParser()
Return the XSLT pattern parser being used by this StylesheetParser.

Returns:
The XSLT pattern Parser.

getImportPrecedence

public int getImportPrecedence()
Get the current import precedence number.

Returns:
The current import precedence number.

getElementNumber

public int getElementNumber()
Get the current ordering number of elements in the stylesheet tree.

This is a relative measurement of element appearance in the stylesheet tree. This is used for the various XSLT rules that resolve conflicts based on relative position in the stylesheet (e.g., the template rule appearing last)

Returns:
The current attribute template number.

getVariables

public ParserVariables getVariables()
Return the ParserVariables object used by this StylesheetParser.

Returns:
ParserVariables object used by this StylesheetParser.

setNamedObject

public void setNamedObject(String name,
                           Object object)
Store an object with the StylesheetParser by a name. This allows top-level extension elements to store state for later use by non-top-level extension elements.

Parameters:
name - The name to associate with the passed Object
object - The object to store
See Also:
getNamedObject(java.lang.String)

getNamedObject

public Object getNamedObject(String name)
Retrieve an object previously set using setNamedObject()

Parameters:
name - The name associated with the object when stored using setNamedObject()
Returns:
The Object, or null if no Object found by passed name
See Also:
setNamedObject(java.lang.String, java.lang.Object)

removeNamedObject

public Object removeNamedObject(String name)
Remove an object previously set using setNamedObject()

Parameters:
name - The name associated with the object when stored using setNamedObject()
Returns:
The Object, or null if no Object found by passed name
See Also:
setNamedObject(java.lang.String, java.lang.Object)

checkVariables

protected void checkVariables()
                       throws XSLTParserException
Check top-level variable references to ensure that they have all been defined. This is called after all of the input tree has been processed.

Throws:
XSLTParserException - Thrown if the stylesheet ErrorHandler throws an exception when and if the error is reported that a referenced variable was never defined.

includeStylesheet

protected void includeStylesheet(Document xslDocument,
                                 URL baseURI)
                          throws XSLTParserException
Includes the specified XSL document using the specified URI as the document's base URI. Note that a valid, non-null base URI is needed to properly resolve relative URIs in the XSLT document.

Parameters:
xslDocument - the XSLT document to be imported
baseURI - the XSLT document's base URI, or null if the base URI is unknown
Throws:
XSLTParserException - if a fatal error occurs during parsing

getFunction

public Function getFunction(ExpandedQName name)
                     throws XPathParserException
Return an object of type Function given the function name.

Specified by:
getFunction in interface FunctionLibrary
Parameters:
name - The name of the function
Returns:
a Function object
Throws:
XPathParserException

isFunctionAvailable

public boolean isFunctionAvailable(ExpressionContext context,
                                   ExpandedQName name)
Return true if a function under a given name is available

Specified by:
isFunctionAvailable in interface FunctionLibrary
Parameters:
context - the expression context
name - name of the function

addFunction

public void addFunction(Function function)
Add a function to the library

Specified by:
addFunction in interface FunctionLibrary
Parameters:
function - The function to bind.

getNamespaceName

public NamespaceName getNamespaceName(String prefix)
Return the currently in-scope namespace URI for the passed prefix.

Specified by:
getNamespaceName in interface NamespaceContext
Parameters:
prefix - The QName prefix of interest
Returns:
The namespace name associated with the prefix for the passed prefix

getExpandedName

public ExpandedQName getExpandedName(String qName)
Return the expanded name given the passed QName, given the current namespace context

Specified by:
getExpandedName in interface NamespaceContext
Parameters:
qName - The QName to expand
Returns:
The expanded Name

pushNSContext

public void pushNSContext(Node newContext)
Change the namespace context to a new node.

Parameters:
newContext - The node that is the new namespace context.

popNSContext

public Node popNSContext()
Remove the current namespace context, restoring the namespace context that was in effect before the current.

Returns:
The removed namespace context node.

parseStylesheet

protected void parseStylesheet(Element element)
                        throws XSLTParserException
Parses the specified xsl:stylesheet element.

Parameters:
element - the xsl:stylesheet element to be parsed
Throws:
XSLTParserException - if a fatal error occurs during parsing

simplifiedStylesheet

protected void simplifiedStylesheet(Element element,
                                    RuleCollection ruleCollection)
                             throws XSLTParserException
Parse a simplified stylesheet that consists just a literal result element.

Parameters:
element - The literal result element that makes up the simplified stylesheet.
ruleCollection - The stylesheet rule collection.
Throws:
XSLTParserException

parseImport

protected void parseImport(Element element)
                    throws XSLTParserException
Parses the specified xsl:import element.

Parameters:
element - the xsl:import element to be parsed
Throws:
XSLTParserException - if a fatal error occurs during parsing

parseInclude

protected void parseInclude(Element element)
                     throws XSLTParserException
Parses the specified xsl:include element.

Parameters:
element - the xsl:include element to be parsed
Throws:
XSLTParserException - if a fatal error occurs during parsing

parseIncludeOrImport

protected Document parseIncludeOrImport(Element element,
                                        URL[] uri)
                                 throws XSLTParserException
Perform common parsing and processing for xsl:include and xsl:import elements.

Parameters:
element - The xsl:include or xsl:import element.
uri - A 1-element URL array (pass by reference)
Returns:
The parsed document referenced by the xsl:include or xsl:import href attribute.
Throws:
XSLTParserException

parseStrippingList

public void parseStrippingList(Element contextNode,
                               String elementList,
                               boolean strip)
                        throws XSLTParserException
Parse the "elements" attribute of an xsl:strip-space or xsl:preserve space element.

Parameters:
contextNode - The context node for error reporting
elementList - The "elements" attribute value.
strip - True if from xsl:strip-space, false otherwise
Throws:
XSLTParserException - if a fatal error occurs during parsing

parseTemplates

public Template[] parseTemplates(Node source,
                                 boolean sortWasAllowed)
                          throws XSLTParserException
Parses the specified source node and its subsequent siblings as a template, and returns the result as an array of Template objects.

Parameters:
source - the source node where parsing is to begin
sortWasAllowed - true if xsl:sort elements were allowed as siblings to the source node, false if not; used to generate sensible error messages
Returns:
the array of Template objects for the parsed nodes
Throws:
XSLTParserException - if a fatal error occurs during parsing

parseLiteralElement

protected Template parseLiteralElement(Element element)
                                throws XSLTParserException
Parses the specified element as a literal result object.

Parameters:
element - the element to be parsed
Returns:
the LiteralElementTemplate for the parsed element
Throws:
XSLTParserException - if a fatal error occurs during parsing

parseExtElement

protected Template parseExtElement(Element element,
                                   NamespaceName namespace)
                            throws XSLTParserException
Parse a non-xslt extension element template that appears as a descendant of an xsl:template element

Parameters:
element - The extension element.
namespace - The namespace name of the extension element
Returns:
A Template object representing the extension element
Throws:
XSLTParserException

parseTopLevelExtElement

protected void parseTopLevelExtElement(Element element,
                                       NamespaceName namespace)
                                throws XSLTParserException
Parse a non-xsl top-level element that appears as the child of an xsl:stylesheet of xsl:transform element.

XSLT doesn't specify any manner of qualifying a top-level extension element (indeed, extension elements are specified only to be those that appear in a template) so we use our magic extension prefix to recognize such elements.

Parameters:
element - The extension element.
namespace - The namespace name of the extension element
Throws:
XSLTParserException

handleElementFallback

protected Template handleElementFallback(Element element)
                                  throws XSLTParserException
Handle any fallback information for an element. This will either return a FallbackTemplatesTemplate object or a BadTemplate object.

Parameters:
element - The element for which to provide fallback behavior
Returns:
A Template that provides fallback behavior for the element.
Throws:
XSLTParserException
See Also:
FallbackTemplatesTemplate, BadTemplate

parseFallbackTemplates

protected FallbackTemplatesTemplate parseFallbackTemplates(Node node,
                                                           Node context)
                                                    throws XSLTParserException
Parse child xsl:fallback elements of a given extension element

Parameters:
node - The child of the extension element at which to begin looking for xsl:fallback elements
context - The extension element node in the stylesheet
Returns:
A FallbackTemplatesTemplate that, when instantiated, will instantiate each xsl:fallback template
Throws:
XSLTParserException
See Also:
FallbackTemplatesTemplate

parseFallbackTemplate

protected FallbackTemplate parseFallbackTemplate(Element element)
                                          throws XSLTParserException
Parse a single xsl:fallback element

Parameters:
element - The xsl:fallback element node
Returns:
A FallbackTemplate object that, when instantiated, will instantiate the contents of the xsl:fallback element
Throws:
XSLTParserException
See Also:
FallbackTemplate

parseSortElement

public SortKey parseSortElement(Element element)
                         throws XSLTParserException
Parse an xsl:sort element, returning a SortKey object. One or more SortKey objects is used to construct a SortCriteria object.

Parameters:
element - The xsl:sort element to parse.
Returns:
The resulting SortKey object.
Throws:
XSLTParserException - if a fatal error occurs during parsing
See Also:
SortKey, SortCriteria

parseElementPrefixes

public NamespaceName[] parseElementPrefixes(Node contextNode,
                                            String prefixList)
                                     throws XSLTParserException
Parse a whitespace separated list of prefixes. This is used for parsing attribute values from extension-element-prefixes, namespace-alias attributes, etc.

If the string "#default" is encountered the default namespace is used.

Parameters:
contextNode - The context node for error reporting
prefixList - A whitespace-separated list of namespace prefixes. "#default" is treated as indicating the default namespace.
Returns:
An array of namespace names corresponding to the prefixes
Throws:
XSLTParserException

parseQNames

public Collection parseQNames(Node contextNode,
                              String string)
                       throws XSLTParserException
Parse a whitespace separated list of QNames names and return a list of expanded names

Parameters:
contextNode - The context node for error reporting
string - The whitespace separated list of element names
Returns:
A Set of ExpandedQName objects
Throws:
XSLTParserException

reportError

public void reportError(String msg)
                 throws XSLTParserException
Report a parsing error by notifying the stylesheet's error handler. This method does not show any useful context, so should only be used in cases where there is no useful context

Parameters:
msg - the error message
Throws:
XSLTParserException - if the error is fatal and the ErrorHandler throws it

reportError

public void reportError(Element topLevelContext,
                        Node contextNode,
                        String key,
                        Object[] parms)
                 throws XSLTParserException
Report a parsing error by notifying the stylesheet's error handler.

Parameters:
topLevelContext - The Element in which the contextNode appears
contextNode - The node that is causing the error.
key - the error message key from XSLTParserException
parms - the replacement parameters for the message (may be null)
Throws:
XSLTParserException - if the error is fatal and the ErrorHandler throws it

reportError

public void reportError(Element topLevelContext,
                        Node contextNode,
                        String key,
                        String parm0)
                 throws XSLTParserException
Report a parsing error by notifying the stylesheet's error handler.

Parameters:
topLevelContext - The Element in which the contextNode appears
contextNode - The node that is causing the error.
key - the error message key from XSLTParserException
parm0 - the replacement parameter for the message (may be null)
Throws:
XSLTParserException - if the error is fatal and the ErrorHandler throws it

reportError

public void reportError(Element topLevelContext,
                        Node contextNode,
                        String key)
                 throws XSLTParserException
Report a parsing error by notifying the stylesheet's error handler.

Parameters:
topLevelContext - The Element in which the contextNode appears
contextNode - The node that is causing the error.
key - the error message key from XSLTParserException
Throws:
XSLTParserException - if the error is fatal and the ErrorHandler throws it

reportError

public void reportError(Node contextNode,
                        String key,
                        Object[] parms)
                 throws XSLTParserException
Report a parsing error by notifying the stylesheet's error handler.

Parameters:
contextNode - The node that is causing the error.
key - the error message key from XSLTParserException
parms - the replacement parameters for the message (may be null)
Throws:
XSLTParserException - if the error is fatal and the ErrorHandler throws it

reportError

public void reportError(Node contextNode,
                        String key,
                        String parm0)
                 throws XSLTParserException
Report a parsing error by notifying the stylesheet's error handler.

Parameters:
contextNode - The node that is causing the error.
key - the error message key from XSLTParserException
parm0 - the replacement parameter for the message (may be null)
Throws:
XSLTParserException - if the error is fatal and the ErrorHandler throws it

reportError

public void reportError(Node contextNode,
                        String key)
                 throws XSLTParserException
Report a parsing error by notifying the stylesheet's error handler.

Parameters:
contextNode - The node that is causing the error.
key - the error message key from XSLTParserException
Throws:
XSLTParserException - if the error is fatal and the ErrorHandler throws it

reportInvalidAttributeValue

public void reportInvalidAttributeValue(Element contextNode,
                                        String attrName,
                                        boolean isRequired,
                                        String attrValue)
                                 throws XSLTParserException
Report an invalid attribute value on an element. In forwards-compatible mode an error will not be reported if the attribute is not required.

Parameters:
contextNode - The Element containing the bad attribute
attrName - The name of the attribute
attrValue - The bad attribute value
Throws:
XSLTParserException - if the error is fatal and the ErrorHandler throws it

reportAttributeExpressionError

public Expression reportAttributeExpressionError(Element contextNode,
                                                 String attrName,
                                                 XPathParserException e)
                                          throws XSLTParserException
Report an XPath parser error for an attribute value. In forwards-compatible mode an error will not be reported. Instead, a BadExpression object is returned that will report an error if it is ever evaluated.

Parameters:
contextNode - The Element containing the bad attribute
attrName - The name of the attribute
e - The XPathParserException
Throws:
XSLTParserException - if the error is fatal and the ErrorHandler throws it
See Also:
BadExpression

buildErrorPrologue

public StringBuffer buildErrorPrologue(StringBuffer prologue,
                                       Node contextNode,
                                       Node lineNumberContext)
Construct an error message prologue containing as much context information as possible.

Parameters:
prologue - A StringBuffer in which to build the prologue. If this is null a StringBuffer will be allocated.
contextNode - The node in the stylesheet that supplies the context for the error message.
lineNumberContext - if non-null, get line number info from this node
Returns:
The StringBuffer in which the prologue was built.

reportWarning

public void reportWarning(Node contextNode,
                          String msg)
Reports a parsing warning by notifying the stylesheet's error handler.

Parameters:
contextNode - The node in the stylesheet document closest to the problem.
msg - the warning message