net.sf.saxon.instruct
Class GeneralVariable

java.lang.Object
  net.sf.saxon.expr.Expression
      net.sf.saxon.instruct.Instruction
          net.sf.saxon.instruct.GeneralVariable

All Implemented Interfaces:

Serializable, SourceLocator, LocationProvider, SaxonLocator, Binding, EvaluableItem, SequenceIterable, TailCallReturner, InstructionInfo, Locator

Direct Known Subclasses:

Assign, GlobalVariable, LocalParam, LocalVariable, WithParam

public abstract class GeneralVariable
extends Instruction
implements Binding

This class defines common behaviour across xsl:variable, xsl:param, and xsl:with-param; also saxon:assign

See Also:

Serialized Form

Field Summary

protected int	evaluationMode
protected int	referenceCount
protected int	slotNumber
protected StructuredQName	variableQName

Fields inherited from class net.sf.saxon.expr.Expression

EVALUATE_METHOD, ITERATE_METHOD, locationId, PROCESS_METHOD, staticProperties

Constructor Summary

GeneralVariable()
Create a general variable

Method Summary

Expression	copy() Copy an expression.
Item	evaluateItem(XPathContext context) Evaluate an expression as a single item.
void	explain(ExpressionPresenter out) Diagnostic print of expression structure.
int	getCardinality() Get the cardinality of the result of this instruction.
int	getEvaluationMode() Get the evaluation mode of the variable
int	getInstructionNameCode() Get the name of this instruction (that is xsl:variable, xsl:param etc) for diagnostics
ItemType	getItemType(TypeHierarchy th) Get the type of the result of this instruction.
int	getLocalSlotNumber() If this is a local variable held on the local stack frame, return the corresponding slot number.
SequenceType	getRequiredType() Get the required type of this variable
Expression	getSelectExpression() Get the expression to which this variable is bound
ValueRepresentation	getSelectValue(XPathContext context) Evaluate the variable.
int	getSlotNumber() Get the slot number allocated to this variable
StructuredQName	getVariableQName() Get the name of this 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() Indicate whether the binding is local or global.
boolean	isImplicitlyRequiredParam() Ask whether this variable represents a parameter that is implicitly required, because there is no usable default value
boolean	isRequiredParam() Ask whether this variable represents a required parameter
boolean	isTunnelParam() Ask whether this variable represents a tunnel parameter
SequenceIterator	iterate(XPathContext context) Return an Iterator to iterate over the values of a sequence.
Iterator<Expression>	iterateSubExpressions() Get all the XPath expressions associated with this instruction (in XSLT terms, the expression present on attributes of the instruction, as distinct from the child instructions in a sequence construction)
Expression	optimize(ExpressionVisitor visitor, ItemType contextItemType) Perform optimisation of an expression and its subexpressions.
protected void	promoteInst(PromotionOffer offer) Handle promotion offers, that is, non-local tree rewrites.
boolean	replaceSubExpression(Expression original, Expression replacement) Replace one subexpression by a replacement subexpression
void	setAssignable(boolean assignable) Indicate whether this variable is assignable using saxon:assign
void	setImplicitlyRequiredParam(boolean requiredParam) Indicate that this variable represents a parameter that is implicitly required (because there is no usable default value)
void	setReferenceCount(int refCount) Set the nominal number of references to this variable
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	setSlotNumber(int s) Set the slot number of this variable
void	setTunnel(boolean tunnel) Indicate whether this variable represents a tunnel parameter
void	setVariableQName(StructuredQName s) Set the name of the variable
Expression	simplify(ExpressionVisitor visitor) Simplify this expression
Expression	typeCheck(ExpressionVisitor visitor, ItemType contextItemType) Perform type checking of an expression and its subexpressions.

Methods inherited from class net.sf.saxon.instruct.Instruction

assembleParams, assembleTunnelParams, computeCardinality, computeSpecialProperties, createsNewNodes, dynamicError, evaluateAsString, getConstructType, getImplementationMethod, getSourceLocator, isXSLT, process, processLeavingTail, promote

Methods inherited from class net.sf.saxon.expr.Expression

addToPathMap, adoptChildExpression, checkForUpdatingSubexpressions, checkPermittedContents, computeDependencies, computeStaticProperties, doPromotion, dynamicError, effectiveBooleanValue, evaluatePendingUpdates, explain, getColumnNumber, getColumnNumber, getContainer, getDependencies, getExecutable, getHostLanguage, getIntrinsicDependencies, getLineNumber, getLineNumber, getLocationId, getLocationProvider, getObjectName, getProperties, getProperty, getPublicId, getSlotsUsed, getSpecialProperties, getSystemId, getSystemId, hasLoopingSubexpression, implementsStaticTypeCheck, isSubtreeExpression, isUpdatingExpression, isVacuousExpression, iterateEvents, iterateSameFocusSubExpressions, markTailFunctionCalls, resetLocalStaticProperties, setContainer, setFiltered, setFlattened, setLocationId, staticTypeCheck, suppressValidation, toString, typeError

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.saxon.expr.Binding

evaluateVariable

Methods inherited from interface javax.xml.transform.SourceLocator

getColumnNumber, getLineNumber, getPublicId, getSystemId

Field Detail

variableQName

protected StructuredQName variableQName

slotNumber

protected int slotNumber

referenceCount

protected int referenceCount

evaluationMode

protected int evaluationMode

Constructor Detail

GeneralVariable

public GeneralVariable()

Create a general 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

setSelectExpression

public void setSelectExpression(Expression select)

Set the expression to which this variable is bound

Parameters:

select - the initializing expression

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

setAssignable

public void setAssignable(boolean assignable)

Indicate whether this variable is assignable using saxon:assign

Parameters:

assignable - true if this variable is assignable

setRequiredParam

public void setRequiredParam(boolean requiredParam)

Indicate that this variable represents a required parameter

Parameters:

requiredParam - true if this is a required parameter

setImplicitlyRequiredParam

public void setImplicitlyRequiredParam(boolean requiredParam)

Indicate that this variable represents a parameter that is implicitly required (because there is no usable default value)

Parameters:

requiredParam - true if this is an implicitly required parameter

setTunnel

public void setTunnel(boolean tunnel)

Indicate whether this variable represents a tunnel parameter

Parameters:

tunnel - true if this is a tunnel parameter

setReferenceCount

public void setReferenceCount(int refCount)

Set the nominal number of references to this variable

Parameters:

refCount - the nominal number of references

getEvaluationMode

public int getEvaluationMode()

Get the evaluation mode of the variable

Returns:

the evaluation mode (a constant in ExpressionTool

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

getItemType

public ItemType getItemType(TypeHierarchy th)

Get the type of the result of this instruction. An xsl:variable instruction returns nothing, so the type is empty.

Overrides:

getItemType in class Instruction

Parameters:

th - the type hierarchy cache

Returns:

the empty type.

getCardinality

public int getCardinality()

Get the cardinality of the result of this instruction. An xsl:variable instruction returns nothing, so the type is empty.

Overrides:

getCardinality in class Expression

Returns:

the empty cardinality.

isGlobal

public boolean isGlobal()

Description copied from interface: Binding

Indicate whether the binding is local or global. A global binding is one that has a fixed value for the life of a query or transformation; any other binding is local.

Specified by:

isGlobal in interface Binding

Returns:

true if the binding is global

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.

Specified by:

getLocalSlotNumber in interface Binding

Returns:

the slot number on the local stack frame

isRequiredParam

public final boolean isRequiredParam()

Ask whether this variable represents a required parameter

Returns:

true if this is a required parameter

isImplicitlyRequiredParam

public final boolean isImplicitlyRequiredParam()

Ask whether this variable represents a parameter that is implicitly required, because there is no usable default value

Returns:

true if this variable is an implicitly required parameter

isTunnelParam

public final boolean isTunnelParam()

Ask whether this variable represents a tunnel parameter

Returns:

true if this is a tunnel parameter

getInstructionNameCode

public int getInstructionNameCode()

Get the name of this instruction (that is xsl:variable, xsl:param etc) for diagnostics

Overrides:

getInstructionNameCode in class Instruction

Returns:

the name of this instruction, as a name pool name code

simplify

public Expression simplify(ExpressionVisitor visitor)
                    throws XPathException

Simplify this expression

Specified by:

simplify in class Instruction

Parameters:

visitor - an expression

Returns:

the simplified expression

Throws:

XPathException

typeCheck

public Expression typeCheck(ExpressionVisitor visitor,
                            ItemType contextItemType)
                     throws XPathException

Description copied from class: Expression

Perform type checking of an expression and its subexpressions. This is the second phase of static optimization.

This checks statically that the operands of the expression have the correct type; if necessary it generates code to do run-time type checking or type conversion. A static type error is reported only if execution cannot possibly succeed, that is, if a run-time type error is inevitable. The call may return a modified form of the expression.

This method is called after all references to functions and variables have been resolved to the declaration of the function or variable. However, the types of such functions and variables may not be accurately known if they have not been explicitly declared.

If the implementation returns a value other than "this", then it is required to ensure that the location information in the returned expression have been set up correctly. It should not rely on the caller to do this, although for historical reasons many callers do so.

Overrides:

typeCheck in class Expression

Parameters:

visitor - an expression visitor

contextItemType - the static type of "." at the point where this expression is invoked. The parameter is set to null if it is known statically that the context item will be undefined. If the type of the context item is not known statically, the argument is set to Type.ITEM_TYPE

Returns:

the original expression, rewritten to perform necessary run-time type checks, and to perform other type-related optimizations

Throws:

XPathException - if an error is discovered during this phase (typically a type error)

optimize

public Expression optimize(ExpressionVisitor visitor,
                           ItemType contextItemType)
                    throws XPathException

Description copied from class: Expression

Perform optimisation of an expression and its subexpressions. This is the third and final phase of static optimization.

This method is called after all references to functions and variables have been resolved to the declaration of the function or variable, and after all type checking has been done.

Overrides:

optimize in class Expression

Parameters:

visitor - an expression visitor

contextItemType - the static type of "." at the point where this expression is invoked. The parameter is set to null if it is known statically that the context item will be undefined. If the type of the context item is not known statically, the argument is set to Type.ITEM_TYPE

Returns:

the original expression, rewritten if appropriate to optimize execution

Throws:

XPathException - if an error is discovered during this phase (typically a type error)

copy

public Expression copy()

Copy an expression. This makes a deep copy.

Specified by:

copy in class Expression

Returns:

the copy of the original expression

evaluateItem

public Item evaluateItem(XPathContext context)
                  throws XPathException

Evaluate an expression as a single item. This always returns either a single Item or null (denoting the empty sequence). No conversion is done. This method should not be used unless the static type of the expression is a subtype of "item" or "item?": that is, it should not be called if the expression may return a sequence. There is no guarantee that this condition will be detected.

Specified by:

evaluateItem in interface EvaluableItem

Overrides:

evaluateItem in class Instruction

Parameters:

context - The context in which the expression is to be evaluated

Returns:

the node or atomic value that results from evaluating the expression; or null to indicate that the result is an empty sequence

Throws:

XPathException - if any dynamic error occurs evaluating the expression

iterate

public SequenceIterator iterate(XPathContext context)
                         throws XPathException

Return an Iterator to iterate over the values of a sequence. The value of every expression can be regarded as a sequence, so this method is supported for all expressions. This default implementation relies on the process() method: it "pushes" the results of the instruction to a sequence in memory, and then iterates over this in-memory sequence. In principle instructions should implement a pipelined iterate() method that avoids the overhead of intermediate storage.

Specified by:

iterate in interface SequenceIterable

Overrides:

iterate in class Instruction

Parameters:

context - supplies the context for evaluation

Returns:

a SequenceIterator that can be used to iterate over the result of the expression

Throws:

XPathException - if any dynamic error occurs evaluating the expression

getSelectValue

public ValueRepresentation getSelectValue(XPathContext context)
                                   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 XPath dynamic context

Returns:

the result of evaluating the variable

Throws:

XPathException

promoteInst

protected void promoteInst(PromotionOffer offer)
                    throws XPathException

Handle promotion offers, that is, non-local tree rewrites.

Overrides:

promoteInst in class Instruction

Parameters:

offer - The type of rewrite being offered

Throws:

XPathException

iterateSubExpressions

public Iterator<Expression> iterateSubExpressions()

Get all the XPath expressions associated with this instruction (in XSLT terms, the expression present on attributes of the instruction, as distinct from the child instructions in a sequence construction)

Overrides:

iterateSubExpressions in class Expression

Returns:

an iterator containing the sub-expressions of this expression

replaceSubExpression

public boolean replaceSubExpression(Expression original,
                                    Expression replacement)

Replace one subexpression by a replacement subexpression

Overrides:

replaceSubExpression in class Expression

Parameters:

original - the original subexpression

replacement - the replacement subexpression

Returns:

true if the original subexpression is found

explain

public void explain(ExpressionPresenter out)

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

Specified by:

explain in class Expression

Parameters:

out - the expression presenter used to display the structure

getSlotNumber

public int getSlotNumber()

Get the slot number allocated to this variable

Returns:

the slot number, that is the position allocated to the variable on its stack frame

setSlotNumber

public void setSlotNumber(int s)

Set the slot number of this variable

Parameters:

s - the slot number, that is, the position allocated to this variable on its 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 this variable

Specified by:

getVariableQName in interface Binding

Returns:

the name of this variable (a QName)