net.sf.saxon.xpath

## Class JAXPVariable

- java.lang.Object
- - net.sf.saxon.xpath.JAXPVariable

- All Implemented Interfaces:
    Binding

      public final class JAXPVariable
      extends Object
      implements Binding

  An object representing an XPath variable for use in the JAXP XPath API. The object is created at compile time when the parser tries to bind a variable reference; the value is fetched at run-time from the XPathVariableResolver. With this interface, there is no way of reporting a static error if the variable has not been declared.

  In Saxon terms, this class is both a VariableDeclaration and a Binding. Unlike a normal VariableDeclaration, it isn't created in advance, but is created on demand when the parser encounters a variable reference. This actually means that if the XPath expression contains two references to the same variable, two VariableDeclarations will be created; however, they will be indistinguishable to the VariableResolver. Acting as a VariableDeclaration, the object goes through the motions of fixing up a binding to a variable reference (in practice, of course, there is exactly one reference to the variable). Acting as a run-time binding, it then evaluates the variable by calling the XPathVariableResolver supplied by the API caller. If no XPathVariableResolver was supplied, an error is reported when a variable is encountered; but if the variable resolver doesn't recognize the variable name, it returns null, which is treated as an empty sequence.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `JAXPVariable(StructuredQName name, XPathVariableResolver resolver)` Private constructor: for use only be the protected factory method make()

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addReference(boolean isLoopingReference)` Register a variable reference that refers to the variable bound in this expression
    `Sequence` | `evaluateVariable(XPathContext context)` Get the value of the variable.
    `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.
    `SequenceType` | `getRequiredType()` Get the declared type of the variable
    `StructuredQName` | `getVariableQName()` Get the name of the variable as a structured QName
    `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.
    `void` | `registerReference(BindingReference ref)` Method called by the XPath expression parser to register a reference to this variable.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### JAXPVariable

          protected JAXPVariable(StructuredQName name,
                      XPathVariableResolver resolver)

      Private constructor: for use only be the protected factory method make()
      Parameters:
        `name` - the name of the variable
        `resolver` - the resolver used in conjunction with this variable

  - ### Method Detail

    - #### getRequiredType

          public SequenceType getRequiredType()

      Description copied from interface: `Binding`
      Get the declared type of the variable
      Specified by:
        `getRequiredType` in interface `Binding`
      Returns:
        the declared type

    - #### isGlobal

          public boolean isGlobal()

      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

    - #### 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 for an XSLT global variable where the extra attribute saxon:assignable="yes" is present.
      Specified by:
        `isAssignable` in interface `Binding`
      Returns:
        true if the binding is assignable

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

    - #### getVariableQName

          public StructuredQName getVariableQName()

      Get the name of the variable as a structured QName
      Specified by:
        `getVariableQName` in interface `Binding`
      Returns:
        the name of the variable, as a structured QName

    - #### addReference

          public void addReference(boolean isLoopingReference)

      Description copied from interface: `Binding`
      Register a variable reference that refers to the variable bound in this expression
      Specified by:
        `addReference` in interface `Binding`
      Parameters:
        `isLoopingReference` - - true if the reference occurs within a loop, such as the predicate of a filter expression

    - #### registerReference

          public void registerReference(BindingReference ref)

      Method called by the XPath expression parser to register a reference to this variable. This method should not be called by users of the API.

    - #### evaluateVariable

          public Sequence evaluateVariable(XPathContext context)
                                    throws XPathException

      Get the value of the variable. This method is used by the XPath execution engine to retrieve the value.
      Specified by:
        `evaluateVariable` in interface `Binding`
      Parameters:
        `context` - The dynamic evaluation context
      Returns:
        The value of the variable
      Throws:
        `XPathException` - if an error occurs while evaluating the variable

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

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