logolineright
bottomhttp://xml.apache.org/http://www.apache.org/http://www.w3.org/
join
Overview
separator
Compiler design
separator
Whitespace
xsl:sort
Keys
Comment design
separator
lang()
Unparsed entities
separator
If design
Choose|When|Otherwise design
Include|Import design
Variable|Param design
separator
Runtime
separator
Internal DOM
Namespaces
separator
Translet & TrAX
XPath Predicates
Xsltc Iterators
Xsltc Native API
Xsltc TrAX API
Performance Hints
separator
Credits
close
Contents
 

Functionality
 

Variables in XSLT are not really variables, as their values cannot be changed. They resemble constants from conventional programming languages. The only way in which a variable can be changed is by declaring it inside a for-each loop, in which case its value will be updated for every iteration. Top-level variables (variables that are direct child nodes of the <xsl:stylesheet> element) can never be changed.

    <xsl:for-each select="/foo/bar">
      <xsl:variable name="some-bar" select="."/>
      <xsl:value-of select="$some-bar"/>
    </xsl:for-each>

Parameters are assigned a value either from the process that invoked the stylesheet (top-level parameter), or from a <xsl:with-param> or from a default value (in which case it behaves as if it was a variable).

    <xsl:template match="/">
      <xsl:call-template name="blob">
        <xsl:with-param name="par" select="'some-value'"/>
      </xsl:call-template>
    </xsl:template>

    <xsl:template name="blob">
      <xsl:param name="par" select="'default-value'"/>
      <xsl:value-of select="$param"/>
    </xsl:template>

Implementation
 

Variables and parameters share a common base class VariableBase that contains a lot of common methods. This class handles both global and local variables/parameters.

Top-level parameters and variables
 

All top-level (ie. global) parameters and variables are stored inside fields in the translet class. Variables are stored as objects or basic data types (such as boolean, char, int, etc.) while parameters have to be "boxed" inside an object. This is because parameters are also stored as objects inside the translet. The addParameter() method of the AbstractTranslet class stores the parameter in a Hashtable (the Hashtable maps the parameter name to the parameter value). The "boxing" of the parameter's value is done by the class that handles the parameters type. This class is a subclass of org.apache.xalan.xsltc.compiler.util.Type.

Note that all top-level parameters and variables from all imported and included stylesheets will be placed as direct children of the top-level stylesheet in the AST. This done to make global variables truly global and not just global in the stylesheet where it was declared.


Local parameters and variables
 

Local variables that are accessible from a given syntax tree node will first be put on the JVM's stack and stored in a local variable slot. This makes the variable or parameter accessible from all code within that method. But, in some special cases, the code that is compiled to handle an element/expression within the variable scope is not put inside the same method as the actual variable. This is the case for some predicates. All syntax-tree nodes implement the isClosureBoundary() method to indicate if its child an ancestor nodes will end up in a different method then itself. This method is used by the Variable and Param classes to determine if the variable or parameter will "escape" the variable frame.

    <xsl:for-each select="/foo/bar/baz">
        <xsl:variable name="pos" select="3"/>
        <xsl:apply-templates select="/foo/bar[$pos]"/>
    </xsl:for-each>

The predicate in this stylesheet fragment is compiled into a separate auxiliary class that implements the Filter interface. It will therefore not have access to the variable "pos" in the current stack frame. A common technique for cases like this is to use a "closure". A closure is a record that contains references to all variables that are in scope for a certain part of the compiled scope. This is done in a very simple manner in XSLTC. All variables or parameters that can "escape" the stack are passed to the translet via its addVariable() method. They can then later be retrieved by the getVariable() method.

Important note 1: A predicate does not always result in a auxiliary class. In some cases we optimize the code by using tailored iterators and goodies like that instead. We may want to update the predicate code to check if an auxiliary class will be generated before returning true or false from the isClosureBoundary() method.

Important note 2: There could be other closure boundaries that we have not yet discovered or considered. This could be, for instance, sort records and other auxiliary classes:

    <xsl:variable name="sort-order" select="'decending'"/>
    <xsl:for-each select="/foo/bar/baz">
        <xsl:sort select="@name" order="$sort-order"/>
        <xsl:value-of select="."/>
    </xsl:for-each>

I would not be surprised if this fails. A fix could be to implement the isClosureBoundary() in the Sort class and have the method return 'true' in all cases.


Parameter and variable references
 

A parameter or variable reference does the oposite of a parameter or variable. The value is read from either a global field, a local variable slot or from a call to getVariable() / getParameter(). The chosen method depends is we're dealing with a parameter or a variable, a global or a local, an escaping variable or not.

The XPath parser identifies all variable references and instanciates either a VariableRef or a ParameterRef. The XPath parser calls the parser's lookupVariable method in an initial attempt to find the variable/parameter instance. If that fails, it goes on to call the symbol table's lookupName() method. If that also fails this means that either:

  • a variable or parameter with the given name does not exist
  • the variable will be declared at a later stage (but within the same scope)

The XPath parser creates an instance of the UnresolvedRef class. This class attempts to locate the variable after the whole AST has been built, when the typeCheck() method is called. If this fails an error is reported and the compilation stops. Otherwise the class creates a VariableRef or a ParameterRef instance and lets that handle the reference.


Forward references
 

XSLTC allows for forward references to global variables and parameters. You can even reference variables in not-yet included/imported stylesheets. In most cases, this is handled by changing the order of top-level elements. (Variables are placed first so that they are handled before any includes or imports). But when a variable contains references to other variables, then this requires some extra code in the Stylesheet and VariableBase classes. The VariableBase has a method that returns a vector containing all variables that are referenced in the variable definition.

    <xsl:variable name="C" select="$A < $B"/>
    <xsl:variable name="A" select="1"/>
    <xsl:variable name="B" select="2"/>

In this case, the getDependencies() method for variable C will return the variables A and B. The stylesheet has a method called resolveReferences that will order the variables accordingly so that the variable values are computed in the desired order. This method will issue an error message and terminate the compilation if there are circular variable/parameter dependencies.




dot
Copyright © 2004 The Apache Software Foundation. All Rights Reserved.