net.sf.saxon.instruct
Class GeneralVariable

java.lang.Object
  extended by net.sf.saxon.expr.Expression
      extended by net.sf.saxon.instruct.Instruction
          extended by net.sf.saxon.instruct.GeneralVariable
All Implemented Interfaces:
Serializable, SourceLocator, Binding, EvaluableItem, SequenceIterable, TailCallReturner, InstructionInfoProvider
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
 
Fields inherited from class net.sf.saxon.expr.Expression
EVALUATE_METHOD, ITERATE_METHOD, PROCESS_METHOD
 
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 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.
 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
computeCardinality, computeSpecialProperties, createsNewNodes, evaluateAsString, getImplementationMethod, getInstructionInfo, getSourceLocator, isXSLT, process, processLeavingTail, promote
 
Methods inherited from class net.sf.saxon.expr.Expression
addToPathMap, adoptChildExpression, checkPermittedContents, computeDependencies, computeStaticProperties, display, doPromotion, effectiveBooleanValue, explain, findParentOf, getColumnNumber, getContainer, getDependencies, getExecutable, getHostLanguage, getIntrinsicDependencies, getLineNumber, getLocationId, getLocationProvider, getPublicId, getSlotsUsed, getSpecialProperties, getSystemId, hasLoopingSubexpression, implementsStaticTypeCheck, iterateEvents, markTailFunctionCalls, setContainer, setFiltered, setFlattened, setLocationId, staticTypeCheck, suppressValidation, toString
 
Methods inherited from class java.lang.Object
equals, 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
 

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 parent pointer and 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

iterateSubExpressions

public Iterator 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)


Copyright (C) Michael H. Kay. All rights reserved.