net.sf.saxon.expr.instruct

Class GlobalVariable

java.lang.Object

net.sf.saxon.expr.instruct.Actor

net.sf.saxon.expr.instruct.GlobalVariable

All Implemented Interfaces:

javax.xml.transform.SourceLocator, Binding, ContextOriginator, ExpressionOwner, Location, Declaration, InstructionInfo, org.xml.sax.Locator

Direct Known Subclasses:

GlobalParam, UndeclaredVariable

public class GlobalVariable
extends Actor
implements Binding, Declaration, InstructionInfo, ContextOriginator

A compiled global variable in a stylesheet or query.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.List<BindingReference>	references

Fields inherited from class net.sf.saxon.expr.instruct.Actor

body

Constructor Summary

Constructors

Constructor and Description
GlobalVariable() Create a global variable

Method Summary

Modifier and Type	Method and Description
protected Sequence	actuallyEvaluate(XPathContext context, Component target) Evaluate the global variable, and save its value for use in subsequent references.
void	addReference(VariableReference ref, boolean isLoopingReference) Register a variable reference that refers to the variable bound in this expression
void	compile(Executable exec, int slot) Create a compiled representation of this global variable
Sequence	evaluateVariable(XPathContext context) Evaluate the variable
Sequence	evaluateVariable(XPathContext context, Component target) Evaluate the variable
void	export(ExpressionPresenter presenter) Diagnostic print of expression structure.
int	getBinderySlotNumber() Get the slot number allocated to this variable in the Bindery
int	getComponentKind() Get the kind of component that this represents, using integer constants such as StandardNames.XSL_FUNCTION
int	getConstructType() Get the type of construct.
protected java.lang.String	getFlags()
int	getHostLanguage() Get the host language (XSLT, XQuery, XPath) used to implement the code in this container
IntegerValue[]	getIntegerBoundsForVariable() If the variable is bound to an integer, get the minimum and maximum possible values.
int	getLocalSlotNumber() If this is a local variable held on the local stack frame, return the corresponding slot number.
StructuredQName	getObjectName() Get a name identifying the object of the expression, for example a function name, template name, variable name, key name, element name, etc.
GlobalVariable	getOriginalVariable() Get the original declaration of this variable
java.util.Iterator<java.lang.String>	getProperties() Get an iterator over all the properties available.
java.lang.Object	getProperty(java.lang.String name) Get the value of a particular property of the instruction.
SequenceType	getRequiredType() Get the required type of this variable
Expression	getSelectExpression() Get the expression to which this variable is bound
Sequence	getSelectValue(XPathContext context, Component target) Evaluate the variable.
SymbolicName	getSymbolicName() Get the symbolic name of the component
GlobalVariable	getUltimateOriginalVariable() Get the original declaration of this variable, or its original declaration, transitively
StructuredQName	getVariableQName() Get the name of the variable
void	init(Expression select, StructuredQName qName) Initialize the properties of the variable
boolean	isAssignable() Test whether it is permitted to assign to the variable using the saxon:assign extension element.
boolean	isGlobal() Is this a global variable?
boolean	isIndexedVariable() Ask whether this is an indexed variable
boolean	isPrivate() Ask whether this global variable is private
boolean	isRequiredParam() Ask whether this variable represents a required parameter
boolean	isUnused() Ask whether this variable is unused.
java.util.Iterator	iterateReferences() Iterate over the references to this variable
void	lookForCycles(java.util.Stack<java.lang.Object> referees, XQueryFunctionLibrary globalFunctionLibrary) Check for cycles in this variable definition
void	registerReference(BindingReference ref) Register a variable reference that refers to this global variable
void	setAssignable(boolean assignable) Indicate whether this variable is assignable using saxon:assign
void	setBinderySlotNumber(int s) Set the slot number of this variable in the Bindery
void	setContainsLocals(SlotManager map) The expression that initializes a global variable may itself use local variables.
protected static void	setDependencies(GlobalVariable var, XPathContext context) Get the variable that is immediately dependent on this one, and register the dependency, so that circularities can be detected across threads.
void	setIndexedVariable() Mark this as an indexed variable, to allow fast searching
void	setOriginalVariable(GlobalVariable var) Say that this (XQuery) variable is a copy of some originally declared variable.
void	setPrivate(boolean b) Say whether this global variable is private
void	setRequiredParam(boolean requiredParam) Indicate that this variable represents a required parameter
void	setRequiredType(SequenceType required) Set the required type of this variable
void	setSelectExpression(Expression select) Set the expression to which this variable is bound
void	setUnused(boolean unused) Say whether this variable is unused.
void	setVariableQName(StructuredQName s) Set the name of the variable
void	typeCheck(ExpressionVisitor visitor) Type check the compiled representation of this global variable

Methods inherited from class net.sf.saxon.expr.instruct.Actor

allocateAllBindingSlots, allocateBindingSlotsRecursive, getBody, getColumnNumber, getDeclaredVisibility, getDeclaringComponent, getLineNumber, getLocation, getPackageData, getPublicId, getRetainedStaticContext, getStackFrameMap, getSystemId, isExportable, makeDeclaringComponent, saveLocation, setBody, setChildExpression, setDeclaredVisibility, setDeclaringComponent, setLineNumber, setPackageData, setRetainedStaticContext, setStackFrameMap, setSystemId

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.sf.saxon.expr.parser.Location

getColumnNumber, getLineNumber, getPublicId, getSystemId, saveLocation

Field Detail

references

protected java.util.List<BindingReference> references

Constructor Detail

GlobalVariable

public GlobalVariable()

Create a global variable

Method Detail

init

public void init(Expression select,
                 StructuredQName qName)

Initialize the properties of the variable

Parameters:

select - the expression to which the variable is bound

qName - the name of the variable

getSymbolicName

public SymbolicName getSymbolicName()

Get the symbolic name of the component

Specified by:

getSymbolicName in class Actor

Returns:

the symbolic name

setSelectExpression

public void setSelectExpression(Expression select)

Set the expression to which this variable is bound

Parameters:

select - the initializing expression. May be null in the case of a global parameter with no initializer.

getSelectExpression

public Expression getSelectExpression()

Get the expression to which this variable is bound

Returns:

the initializing expression

setRequiredType

public void setRequiredType(SequenceType required)

Set the required type of this variable

Parameters:

required - the required type

getRequiredType

public SequenceType getRequiredType()

Get the required type of this variable

Specified by:

getRequiredType in interface Binding

Returns:

the required type

setOriginalVariable

public void setOriginalVariable(GlobalVariable var)

Say that this (XQuery) variable is a copy of some originally declared variable. It's a separate variable when imported into another module, but it retains the link to the original.

Parameters:

var - the variable in the imported module from which this variable is derived

getOriginalVariable

public GlobalVariable getOriginalVariable()

Get the original declaration of this variable

Returns:

the variable in the imported module from which this variable is derived

getUltimateOriginalVariable

public GlobalVariable getUltimateOriginalVariable()

Get the original declaration of this variable, or its original declaration, transitively

Returns:

the real variable declaration in some transitively imported module from which this variable is ultimately derived

setUnused

public void setUnused(boolean unused)

Say whether this variable is unused. Normally, unused variables are not compiled. However, in XSLT with debugging enabled (that is, with compileWithTracing set), dummy unused variables are created in respect of global variables that are declared but never referenced. These variables are included in the list of variables known to the Executable, but they are never evaluated, and do not have slot numbers allocated in the bindery.

Parameters:

unused - set to true if this global variable is to be marked as unused.

isUnused

public boolean isUnused()

Ask whether this variable is unused. Normally, unused variables are not compiled. However, in XSLT with debugging enabled (that is, with compileWithTracing set), dummy unused variables are created in respect of global variables that are declared but never referenced. These variables are included in the list of variables known to the Executable, but they are never evaluated, and do not have slot numbers allocated in the bindery.

Returns:

true if this global variable is marked as unused.

isPrivate

public boolean isPrivate()

Ask whether this global variable is private

Returns:

true if this variable is private

setPrivate

public void setPrivate(boolean b)

Say whether this global variable is private

Parameters:

b - true if this variable is external

setAssignable

public void setAssignable(boolean assignable)

Indicate whether this variable is assignable using saxon:assign

Parameters:

assignable - true if this variable is assignable

isAssignable

public final boolean isAssignable()

Test whether it is permitted to assign to the variable using the saxon:assign extension element. This will only be true if the extra attribute saxon:assignable="yes" is present.

Specified by:

isAssignable in interface Binding

Returns:

true if the binding is assignable

getConstructType

public int getConstructType()

Get the type of construct. This will either be the fingerprint of a standard XSLT instruction name (values in StandardNames: all less than 1024) or it will be a constant in class LocationKind.

Specified by:

getConstructType in interface InstructionInfo

Returns:

an integer identifying the kind of construct

getObjectName

public StructuredQName getObjectName()

Get a name identifying the object of the expression, for example a function name, template name, variable name, key name, element name, etc. This is used only where the name is known statically.

Specified by:

getObjectName in interface InstructionInfo

Returns:

the QName of the object declared or manipulated by this instruction or expression

getProperty

public java.lang.Object getProperty(java.lang.String name)

Get the value of a particular property of the instruction. Properties of XSLT instructions are generally known by the name of the stylesheet attribute that defines them.

Specified by:

getProperty in interface InstructionInfo

Overrides:

getProperty in class Actor

Parameters:

name - The name of the required property

Returns:

The value of the requested property, or null if the property is not available

getProperties

public java.util.Iterator<java.lang.String> getProperties()

Get an iterator over all the properties available. The values returned by the iterator will be of type String, and each string can be supplied as input to the getProperty() method to retrieve the value of the property. The iterator may return properties whose value is null.

Specified by:

getProperties in interface InstructionInfo

Overrides:

getProperties in class Actor

Returns:

an iterator over the properties.

getHostLanguage

public int getHostLanguage()

Get the host language (XSLT, XQuery, XPath) used to implement the code in this container

Returns:

typically Configuration.XSLT or Configuration.XQUERY

setIndexedVariable

public void setIndexedVariable()

Mark this as an indexed variable, to allow fast searching

isIndexedVariable

public boolean isIndexedVariable()

Ask whether this is an indexed variable

Returns:

true if this variable is indexed

setContainsLocals

public void setContainsLocals(SlotManager map)

The expression that initializes a global variable may itself use local variables. In this case a stack frame needs to be allocated while evaluating the global variable

Parameters:

map - The stack frame map for local variables used while evaluating this global variable.

isGlobal

public boolean isGlobal()

Is this a global variable?

Specified by:

isGlobal in interface Binding

Returns:

true (yes, it is a global variable)

registerReference

public void registerReference(BindingReference ref)

Register a variable reference that refers to this global variable

Parameters:

ref - the variable reference

iterateReferences

public java.util.Iterator iterateReferences()

Iterate over the references to this variable

Returns:

an iterator over the references: returns objects of class VariableReference

getBinderySlotNumber

public int getBinderySlotNumber()

Get the slot number allocated to this variable in the Bindery

Returns:

the slot number, that is the position allocated to the variable within the Bindery

setBinderySlotNumber

public void setBinderySlotNumber(int s)

Set the slot number of this variable in the Bindery

Parameters:

s - the slot number, that is, the position allocated to this variable within the Bindery

setRequiredParam

public void setRequiredParam(boolean requiredParam)

Indicate that this variable represents a required parameter

Parameters:

requiredParam - true if this is a required parameter

isRequiredParam

public boolean isRequiredParam()

Ask whether this variable represents a required parameter

Returns:

true if this variable represents a required parameter

compile

public void compile(Executable exec,
                    int slot)
             throws XPathException

Create a compiled representation of this global variable

Parameters:

exec - the executable

slot - the slot number allocated to this variable

Throws:

XPathException - if compile-time errors are found.

typeCheck

public void typeCheck(ExpressionVisitor visitor)
               throws XPathException

Type check the compiled representation of this global variable

Parameters:

visitor - an expression visitor

Throws:

XPathException - if compile-time errors are found.

lookForCycles

public void lookForCycles(java.util.Stack<java.lang.Object> referees,
                          XQueryFunctionLibrary globalFunctionLibrary)
                   throws XPathException

Check for cycles in this variable definition

Parameters:

referees - the calls leading up to this one; it's an error if this variable is on the stack, because that means it calls itself directly or indirectly. The stack may contain variable definitions (GlobalVariable objects) and user-defined functions (UserFunction objects). It will never contain the same object more than once.

globalFunctionLibrary - the library containing all global functions

Throws:

XPathException - if cycles are found

getSelectValue

public Sequence getSelectValue(XPathContext context,
                               Component target)
                        throws XPathException

Evaluate the variable. That is, get the value of the select expression if present or the content of the element otherwise, either as a tree or as a sequence

Parameters:

context - the dynamic evaluation context

target - the component representing the variable to be evaluated

Returns:

the value of the variable

Throws:

XPathException - if a dynamic error occurs during evaluation

evaluateVariable

public Sequence evaluateVariable(XPathContext context)
                          throws XPathException

Evaluate the variable

Specified by:

evaluateVariable in interface Binding

Parameters:

context - the XPath dynamic evaluation context

Returns:

the result of evaluating the variable

Throws:

XPathException - if an error occurs while evaluating the variable

evaluateVariable

public Sequence evaluateVariable(XPathContext context,
                                 Component target)
                          throws XPathException

Evaluate the variable

Throws:

XPathException

actuallyEvaluate

protected Sequence actuallyEvaluate(XPathContext context,
                                    Component target)
                             throws XPathException

Evaluate the global variable, and save its value for use in subsequent references.

Parameters:

context - the XPath dynamic context

target - the component representing this variable (in the context of a package where it is used)

Returns:

the value of the variable

Throws:

XPathException - if evaluation fails

setDependencies

protected static void setDependencies(GlobalVariable var,
                                      XPathContext context)
                               throws XPathException

Get the variable that is immediately dependent on this one, and register the dependency, so that circularities can be detected across threads. This relies on the fact that when the initialiser for variable X contains a reference to variable Y, then when Y is evaluated, a stack frame will be found on the context stack representing the evaluation of X. We don't set a dependency from X to Y if the value of Y was already available in the Bindery; it's not needed, because in this case we know that evaluation of Y is unproblematic, and can't lead to any circularities.

Parameters:

var - the global variable or parameter being evaluated

context - the dynamic evaluation context

Throws:

XPathException

getIntegerBoundsForVariable

public IntegerValue[] getIntegerBoundsForVariable()

If the variable is bound to an integer, get the minimum and maximum possible values. Return null if unknown or not applicable

Specified by:

getIntegerBoundsForVariable in interface Binding

Returns:

a pair of integers containing the minimum and maximum values for the integer value; or null if the value is not an integer or the range is unknown

getLocalSlotNumber

public int getLocalSlotNumber()

If this is a local variable held on the local stack frame, return the corresponding slot number. In other cases, return -1.

Returns:

the slot number on the local stack frame

setVariableQName

public void setVariableQName(StructuredQName s)

Set the name of the variable

Parameters:

s - the name of the variable (a QName)

getVariableQName

public StructuredQName getVariableQName()

Get the name of the variable

Specified by:

getVariableQName in interface Binding

Returns:

the name of the variable, as a structured QName

addReference

public void addReference(VariableReference ref,
                         boolean isLoopingReference)

Register a variable reference that refers to the variable bound in this expression

Specified by:

addReference in interface Binding

Parameters:

ref -

isLoopingReference - - true if the reference occurs within a loop, such as the predicate of a filter expression

getComponentKind

public int getComponentKind()

Get the kind of component that this represents, using integer constants such as StandardNames.XSL_FUNCTION

Specified by:

getComponentKind in class Actor

export

public void export(ExpressionPresenter presenter)
            throws XPathException

Diagnostic print of expression structure. The abstract expression tree is written to the supplied outputstream.

Specified by:

export in class Actor

Parameters:

presenter - the expression presenter used to display the structure

Throws:

XPathException

getFlags

protected java.lang.String getFlags()