net.sf.saxon.instruct
Class Bindery

java.lang.Object
  extended by net.sf.saxon.instruct.Bindery

public final class Bindery
extends Object

The Bindery class holds information about variables and their values. Variables are identified by a Binding object. Values can be any object, though values of XSL variables will always be of class Value.


Field Summary
static int FRAME_PARAMS
           
static int FRAME_TUNNEL_PARAMS
           
static int FRAME_VARIABLES
           
 
Constructor Summary
Bindery()
           
 
Method Summary
 void allocateGlobals(int n)
          Define how many slots are needed for global variables
 void allocateLocals(int n)
          Define how many slots are needed for local variables.
 void assignVariable(DefiningVariable binding, Value value)
          Assign a new value to a variable
 void closeStackFrame()
          Close the current stack frame for local variables
 void defineGlobalParameters(ParameterSet params)
          Define global parameters
 void defineGlobalVariable(DefiningVariable binding, Value value)
          Provide a value for a global variable
 Value evaluateGlobalVariable(DefiningVariable binding)
          Get the value of a global variable
 Object[] getCurrentStackFrame()
          Get a reference to the current stackframe containing local variables.
 int getFrameId()
          Get the id of the current frame.
 Value getLocalVariable(int slotNumber)
          Get the value of a local variable, given its slot number
 ParameterSet getTunnelParameters()
          Get the set of tunnel parameters from the local stackframe
 Value getValue(DefiningVariable binding, int frameId)
          Get the value of a variable in the given frame
 boolean isEvaluated(DefiningVariable binding)
          Test if global variable has already been evaluated
 void openStackFrame()
          Start a new stack frame without parameters
 void openStackFrame(ParameterSet localParameters, ParameterSet tunnelParameters)
          Start a new stack frame supplying parameters by name
 void openStackFrame(Value[] arguments)
          Start a new stack frame supplying parameters positionally
 void setExecuting(DefiningVariable binding, boolean executing)
          Set/Unset a flag to indicate that a particular global variable is currently being evaluated.
 void setLocalVariable(int slotNumber, Value value)
          Set the value of a local variable.
 boolean useGlobalParameter(int fingerprint, DefiningVariable binding)
          Use global parameter.
 boolean useLocalParameter(int fingerprint, DefiningVariable binding, boolean isTunnel)
          Use local parameter.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FRAME_PARAMS

public static final int FRAME_PARAMS
See Also:
Constant Field Values

FRAME_TUNNEL_PARAMS

public static final int FRAME_TUNNEL_PARAMS
See Also:
Constant Field Values

FRAME_VARIABLES

public static final int FRAME_VARIABLES
See Also:
Constant Field Values
Constructor Detail

Bindery

public Bindery()
Method Detail

allocateGlobals

public void allocateGlobals(int n)
Define how many slots are needed for global variables


defineGlobalParameters

public void defineGlobalParameters(ParameterSet params)
Define global parameters

Parameters:
params - The ParameterSet passed in by the user, eg. from the command line

useGlobalParameter

public boolean useGlobalParameter(int fingerprint,
                                  DefiningVariable binding)
                           throws XPathException
Use global parameter. This is called when a global xsl:param element is processed. If a parameter of the relevant name was supplied, it is bound to the xsl:param element. Otherwise the method returns false, so the xsl:param default will be evaluated.

Parameters:
fingerprint - The fingerprint of the parameter
binding - The XSLParam element to bind its value to
Returns:
true if a parameter of this name was supplied, false if not
Throws:
XPathException

defineGlobalVariable

public void defineGlobalVariable(DefiningVariable binding,
                                 Value value)
Provide a value for a global variable

Parameters:
binding - identifies the variable
value - the value of the variable

setExecuting

public void setExecuting(DefiningVariable binding,
                         boolean executing)
                  throws XPathException
Set/Unset a flag to indicate that a particular global variable is currently being evaluated.

Throws:
XPathException - If an attempt is made to set the flag when it is already set, this means the definition of the variable is circular.

isEvaluated

public boolean isEvaluated(DefiningVariable binding)
Test if global variable has already been evaluated


allocateLocals

public void allocateLocals(int n)
Define how many slots are needed for local variables. We work on the basis of "one size fits all": all stackframes are allocated as large as the largest one needed


openStackFrame

public void openStackFrame(ParameterSet localParameters,
                           ParameterSet tunnelParameters)
Start a new stack frame supplying parameters by name


openStackFrame

public void openStackFrame()
Start a new stack frame without parameters


openStackFrame

public void openStackFrame(Value[] arguments)
Start a new stack frame supplying parameters positionally


closeStackFrame

public void closeStackFrame()
Close the current stack frame for local variables


useLocalParameter

public boolean useLocalParameter(int fingerprint,
                                 DefiningVariable binding,
                                 boolean isTunnel)
                          throws XPathException
Use local parameter. This is called when a local xsl:param element is processed. If a parameter of the relevant name was supplied, it is bound to the xsl:param element. Otherwise the method returns false, so the xsl:param default will be evaluated

Parameters:
fingerprint - The fingerprint of the parameter name
binding - The XSLParam element to bind its value to
isTunnel - True if a tunnel parameter is required, else false
Returns:
true if a parameter of this name was supplied, false if not
Throws:
XPathException

setLocalVariable

public void setLocalVariable(int slotNumber,
                             Value value)
Set the value of a local variable. Note, it is safe to call this when setting XSLT variables, as these always run on the stack. When setting range variables within XPath expressions, however, this method should not be used, because in delayed evaluation mode the variables might be stored on the heap, within the XPathContext object. Use the XPathContext#setLocalVariable method instead.

Parameters:
slotNumber - identifies the variable
value - the value of the variable

evaluateGlobalVariable

public Value evaluateGlobalVariable(DefiningVariable binding)
Get the value of a global variable

Parameters:
binding - the Binding that establishes the unique instance of the variable
Returns:
the Value of the variable if defined, null otherwise.

getLocalVariable

public Value getLocalVariable(int slotNumber)
Get the value of a local variable, given its slot number

Parameters:
slotNumber - identifies the local variable
Returns:
the value of the variable

getCurrentStackFrame

public Object[] getCurrentStackFrame()
Get a reference to the current stackframe containing local variables. This is used when creating a Closure, which is used for lazy evaluation of expressions. The Closure contains an expression and a copy of all the local variables on which it depends.

Returns:
the current stack frame. Position 0 contains a ParameterSet containing the supplied values; this should not be needed. Remaining positions contain slots holding Values of local variables.

getTunnelParameters

public ParameterSet getTunnelParameters()
Get the set of tunnel parameters from the local stackframe


getValue

public Value getValue(DefiningVariable binding,
                      int frameId)
Get the value of a variable in the given frame

Parameters:
binding - the Binding that establishes the unique instance of the variable
frameId - the id of the frame, see getFrameId
Returns:
the Value of the variable if defined, null otherwise.

getFrameId

public int getFrameId()
Get the id of the current frame.

Returns:
an id, that may be given to getValue(Binding,int)

assignVariable

public void assignVariable(DefiningVariable binding,
                           Value value)
Assign a new value to a variable

Parameters:
binding - identifies the local or global variable or parameter