Package 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`, `Locatable`, `Declaration`, `Location`, `Traceable`, `TraceableComponent`, `org.xml.sax.Locator`
  Direct Known Subclasses:
    `GlobalParam`, `UndeclaredVariable`

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

  A compiled global variable in a stylesheet or query.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected java.util.List<BindingReference>` | `references` |

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

      `body`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `GlobalVariable()` | Create a global variable

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected GroundedValue` | `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.
    `GroundedValue` | `evaluateVariable​(XPathContext context)` | Evaluate the variable
    `GroundedValue` | `evaluateVariable​(XPathContext context, Component target)` | Evaluate the variable
    `void` | `export​(ExpressionPresenter presenter)` | Diagnostic print of expression structure.
    `void` | `gatherProperties​(java.util.function.BiConsumer<java.lang.String,​java.lang.Object> consumer)` | Get the properties of this object to be included in trace messages, by supplying the property values to a supplied consumer function
    `int` | `getBinderySlotNumber()` | Get the slot number allocated to this variable in the Bindery
    `java.lang.String` | `getDescription()` | Get a description of the variable for use in diagnostics
    `protected java.lang.String` | `getFlags()` |
    `HostLanguage` | `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
    `GroundedValue` | `getSelectValue​(XPathContext context, Component target)` | Evaluate the variable.
    `SymbolicName` | `getSymbolicName()` | Get the symbolic name of the component
    `java.lang.String` | `getTracingTag()` | Get a string used to identify this kind of component when used in tracing output
    `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` | `isStatic()` | Ask whether this variable is declared to be static
    `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` | `setStatic​(boolean declaredStatic)` | Say whether this variable is declared to be static
    `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, getChildExpression, getColumnNumber, getComponentName, getDeclaredVisibility, getDeclaringComponent, getLineNumber, getLocation, getPackageData, getPublicId, getRetainedStaticContext, getStackFrameMap, getSystemId, isExportable, makeDeclaringComponent, obtainDeclaringComponent, saveLocation, setBody, setChildExpression, setColumnNumber, 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.Locatable

      `getLocation`

    - ### Methods inherited from interface net.sf.saxon.trace.TraceableComponent

      `getBody, setBody`

- - ### 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

    - #### getTracingTag

          public java.lang.String getTracingTag()

      Description copied from class: `Actor`
      Get a string used to identify this kind of component when used in tracing output
      Specified by:
        `getTracingTag` in interface `TraceableComponent`
      Overrides:
        `getTracingTag` in class `Actor`
      Returns:
        an identifying string

    - #### gatherProperties

          public void gatherProperties​(java.util.function.BiConsumer<java.lang.String,​java.lang.Object> consumer)

      Get the properties of this object to be included in trace messages, by supplying the property values to a supplied consumer function
      Specified by:
        `gatherProperties` in interface `Traceable`
      Parameters:
        `consumer` - the function to which the properties should be supplied, as (property name, value) pairs.

    - #### setStatic

          public void setStatic​(boolean declaredStatic)

      Say whether this variable is declared to be static
      Parameters:
        `declaredStatic` - true if the variable is declared with static="yes"

    - #### isStatic

          public boolean isStatic()

      Ask whether this variable is declared to be static
      Returns:
        true if the variable is declared with static="yes"

    - #### 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

    - #### 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 `Traceable`
      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.
      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.
      Overrides:
        `getProperties` in class `Actor`
      Returns:
        an iterator over the properties.

    - #### getHostLanguage

          public HostLanguage getHostLanguage()

      Get the host language (XSLT, XQuery, XPath) used to implement the code in this container
      Returns:
        typically `HostLanguage.XSLT` or `HostLanguage.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. Used in XQuery only.
      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 GroundedValue 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 GroundedValue 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 GroundedValue evaluateVariable​(XPathContext context,
                                                Component target)
                                         throws XPathException

      Evaluate the variable
      Throws:
        `XPathException`

    - #### actuallyEvaluate

          protected GroundedValue 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

    - #### getDescription

          public java.lang.String getDescription()

      Get a description of the variable for use in diagnostics

    - #### 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` - the variable reference to be registered
        `isLoopingReference` - - true if the reference occurs within a loop, such as the predicate of a filter expression

    - #### 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()