net.sf.saxon.expr.instruct

## Class GlobalVariable

- java.lang.Object
- - net.sf.saxon.expr.instruct.GeneralVariable
  - - net.sf.saxon.expr.instruct.GlobalVariable

- All Implemented Interfaces:
    Serializable, SourceLocator, LocationProvider, SaxonLocator, Binding, Container, Declaration, InstructionInfo, Locator
  Direct Known Subclasses:
    GlobalParam, UndeclaredVariable

      public class GlobalVariable
      extends GeneralVariable
      implements Container, Declaration, InstructionInfo

  A compiled global variable in a stylesheet or query.
  See Also:
    Serialized Form

- - ### Field Summary

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

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

      `evaluationMode, referenceCount, slotNumber, variableQName`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GlobalVariable()` Create a global variable

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Sequence` | `actuallyEvaluate(XPathContext context)` Evaluate the global variable, and save its value for use in subsequent references.
    `void` | `compile(Executable exec, int slot)` Create a compiled representation of this global variable
    `Sequence` | `evaluateVariable(XPathContext context)` Evaluate the variable
    `int` | `getColumnNumber(long locationId)` Get the column number within the document, entity, or module containing a particular location
    `int` | `getConstructType()` Get the type of construct.
    `Container` | `getContainer()` Get the container in which this expression is located.
    `int` | `getContainerGranularity()` Get the granularity of the container.
    `Executable` | `getExecutable()` Get the executable containing this global variable
    `int` | `getHostLanguage()` Get the host language (XSLT, XQuery, XPath) used to implement the code in this container
    `int` | `getLineNumber()` Get the line number where the declaration appears
    `int` | `getLineNumber(long locationId)` Get the line number within the document, entity or module containing a particular location
    `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
    `Iterator<String>` | `getProperties()` Get an iterator over all the properties available.
    `Object` | `getProperty(String name)` Get the value of a particular property of the instruction.
    `Sequence` | `getSelectValue(XPathContext context)` Evaluate the variable.
    `String` | `getSystemId()` Get the system ID of the module containing the variable declaration
    `GlobalVariable` | `getUltimateOriginalVariable()` Get the original declaration of this variable, or its original declaration, transitively
    `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
    `Iterator` | `iterateReferences()` Iterate over the references to this variable
    `void` | `lookForCycles(Stack<Container> 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` | `setContainsLocals(SlotManager map)` The expression that initializes a global variable may itself use local variables.
    `protected static void` | `setDependencies(Bindery bindery, 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` | `setExecutable(Executable executable)` Set the containing executable
    `void` | `setIndexedVariable()` Mark this as an indexed variable, to allow fast searching
    `void` | `setLineNumber(int lineNumber)` Set the line number where the variable declaration appears in the source
    `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 a "parameter" (an external variable, in XQuery terminology)
    `void` | `setSystemId(String systemId)` Set the system ID of the module where the variable declaration appears
    `void` | `typeCheck(ExpressionVisitor visitor)` Type check the compiled representation of this global variable

    - ### Methods inherited from class net.sf.saxon.expr.instruct.GeneralVariable

      `addReference, checkAgainstRequiredType, computeEvaluationMode, copy, explain, getCardinality, getColumnNumber, getEvaluationMode, getInstructionNameCode, getIntegerBoundsForVariable, getLocalSlotNumber, getLocationId, getLocationProvider, getPublicId, getRequiredType, getSelectExpression, getSlotNumber, getSystemId, getVariableQName, init, isImplicitlyRequiredParam, isRequiredParam, isTunnelParam, iterateSubExpressions, optimize, replaceSubExpression, setContainer, setImplicitlyRequiredParam, setLocationId, setReferenceCount, setRequiredParam, setRequiredType, setSelectExpression, setSlotNumber, setTunnel, setVariableQName, simplify, typeCheck`

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

      `getLocationProvider`

    - ### Methods inherited from interface org.xml.sax.Locator

      `getColumnNumber, getPublicId`

    - ### Methods inherited from interface javax.xml.transform.SourceLocator

      `getColumnNumber, getPublicId`

    - ### Methods inherited from interface net.sf.saxon.event.LocationProvider

      `getSystemId`

- - ### Field Detail

    - #### references

          protected List<BindingReference> references

  - ### Constructor Detail

    - #### GlobalVariable

          public GlobalVariable()

      Create a global variable

  - ### Method Detail

    - #### getExecutable

          public Executable getExecutable()

      Get the executable containing this global variable
      Specified by:
        `getExecutable` in interface `Container`
      Overrides:
        `getExecutable` in class `GeneralVariable`
      Returns:
        the containing executable

    - #### setExecutable

          public void setExecutable(Executable executable)

      Set the containing executable
      Parameters:
        `executable` - the executable that contains this global variable

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

    - #### setLineNumber

          public void setLineNumber(int lineNumber)

      Set the line number where the variable declaration appears in the source
      Parameters:
        `lineNumber` - the line number

    - #### getLineNumber

          public int getLineNumber()

      Get the line number where the declaration appears
      Specified by:
        `getLineNumber` in interface `SourceLocator`
      Specified by:
        `getLineNumber` in interface `InstructionInfo`
      Specified by:
        `getLineNumber` in interface `Locator`
      Overrides:
        `getLineNumber` in class `GeneralVariable`
      Returns:
        the line number of the expression within the containing module

    - #### getLineNumber

          public int getLineNumber(long locationId)

      Description copied from interface: `LocationProvider`
      Get the line number within the document, entity or module containing a particular location
      Specified by:
        `getLineNumber` in interface `LocationProvider`
      Parameters:
        `locationId` - identifier of the location in question (as passed down the Receiver pipeline)
      Returns:
        the line number within the document, entity or module, or -1 if no information is available.

    - #### setSystemId

          public void setSystemId(String systemId)

      Set the system ID of the module where the variable declaration appears
      Parameters:
        `systemId` - the System ID (base URI)

    - #### getSystemId

          public String getSystemId()

      Get the system ID of the module containing the variable declaration
      Specified by:
        `getSystemId` in interface `SourceLocator`
      Specified by:
        `getSystemId` in interface `InstructionInfo`
      Specified by:
        `getSystemId` in interface `Locator`
      Overrides:
        `getSystemId` in class `GeneralVariable`
      Returns:
        the System ID (base URI)

    - #### getColumnNumber

          public int getColumnNumber(long locationId)

      Get the column number within the document, entity, or module containing a particular location
      Specified by:
        `getColumnNumber` in interface `LocationProvider`
      Parameters:
        `locationId` - identifier of the location in question (as passed down the Receiver pipeline)
      Returns:
        the column number within the document, entity, or module, or -1 if this is not available

    - #### 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 a "parameter" (an external variable, in XQuery terminology)
      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`
      Overrides:
        `isAssignable` in class `GeneralVariable`
      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 `Location`.
      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 Object getProperty(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`
      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 Iterator<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`
      Returns:
        an iterator over the properties.

    - #### getContainer

          public Container getContainer()

      Get the container in which this expression is located. This will usually be a top-level construct such as a function or global variable, and XSLT template, or an XQueryExpression. In the case of free-standing XPath expressions it will be the StaticContext object
      Overrides:
        `getContainer` in class `GeneralVariable`
      Returns:
        the expression's container

    - #### getHostLanguage

          public int getHostLanguage()

      Get the host language (XSLT, XQuery, XPath) used to implement the code in this container
      Specified by:
        `getHostLanguage` in interface `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

    - #### getContainerGranularity

          public int getContainerGranularity()

      Get the granularity of the container.
      Specified by:
        `getContainerGranularity` in interface `Container`
      Returns:
        0 for a temporary container created during parsing; 1 for a container that operates at the level of an XPath expression; 2 for a container at the level of a global function or template

    - #### 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`
      Overrides:
        `isGlobal` in class `GeneralVariable`
      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 Iterator iterateReferences()

      Iterate over the references to this variable
      Returns:
        an iterator over the references: returns objects of class `VariableReference`

    - #### 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(Stack<Container> 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)
                                  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
      Overrides:
        `getSelectValue` in class `GeneralVariable`
      Parameters:
        `context` - the XPath dynamic context
      Returns:
        the result of evaluating the variable
      Throws:
        `XPathException` - if evaluation of the select expression fails with a dynamic error

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

    - #### actuallyEvaluate

          protected Sequence actuallyEvaluate(XPathContext context)
                                       throws XPathException

      Evaluate the global variable, and save its value for use in subsequent references.
      Parameters:
        `context` - the XPath dynamic context
      Returns:
        the value of the variable
      Throws:
        `XPathException` - if evaluation fails

    - #### setDependencies

          protected static void setDependencies(Bindery bindery,
                             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:
        `bindery` - the Bindery
        `var` - the global variable or parameter being evaluated
        `context` - the dynamic evaluation context
      Throws:
        `XPathException`

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.