net.sf.saxon.expr.instruct

## Class Bindery

- java.lang.Object
- - net.sf.saxon.expr.instruct.Bindery

-     public final class Bindery
      extends Object

  The Bindery class holds information about variables and their values. From Saxon 8.1, it is used only for global variables: local variables are now held in the XPathContext object. Variables are identified by a Binding object. Values will always be of class Value.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Bindery()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `allocateGlobals(SlotManager map)` Define how many slots are needed for global variables
    `void` | `defineGlobalParameters(GlobalParameterSet params)` Define global parameters
    `Sequence` | `getGlobalVariable(int slot)` Get the value of a global variable whose slot number is known
    `SlotManager` | `getGlobalVariableMap()` Get the Global Variable Map, containing the mapping of variable names (fingerprints) to slot numbers.
    `Sequence[]` | `getGlobalVariables()` Get all the global variables, as an array.
    `Sequence` | `getGlobalVariableValue(GlobalVariable binding)` Get the value of a global variable
    `boolean` | `isApplyFunctionConversionRulesToExternalVariables()` Ask whether the function conversion rules should be applied to supplied parameter values.
    `void` | `registerDependency(GlobalVariable one, GlobalVariable two)` Register the dependency of one variable ("one") upon another ("two"), throwing an exception if this would establish a cycle of dependencies.
    `Sequence` | `saveGlobalVariableValue(GlobalVariable binding, Sequence value)` Save the value of a global variable, and mark evaluation as complete.
    `void` | `setApplyFunctionConversionRulesToExternalVariables(boolean convert)` Say whether the function conversion rules should be applied to supplied parameter values.
    `boolean` | `setExecuting(GlobalVariable binding)` Set/Unset a flag to indicate that a particular global variable is currently being evaluated.
    `void` | `setGlobalVariable(GlobalVariable binding, Sequence value)` Provide a value for a global variable
    `void` | `setNotExecuting(GlobalVariable binding)` Indicate that a global variable is not currently being evaluated
    `boolean` | `useGlobalParameter(StructuredQName qName, int slot, SequenceType requiredType, XPathContext context)` Use global parameter.

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

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

- - ### Constructor Detail

    - #### Bindery

          public Bindery()

  - ### Method Detail

    - #### allocateGlobals

          public void allocateGlobals(SlotManager map)

      Define how many slots are needed for global variables
      Parameters:
        `map` - the SlotManager that keeps track of slot allocation for global variables.

    - #### setApplyFunctionConversionRulesToExternalVariables

          public void setApplyFunctionConversionRulesToExternalVariables(boolean convert)

      Say whether the function conversion rules should be applied to supplied parameter values. For example, this allows an integer to be supplied as the value for a parameter where the expected type is xs:double. The default is true.
      Parameters:
        `convert` - true if function conversion rules are to be applied to supplied values; if false, the supplied value must match the required type exactly.
      Since:
        9.3

    - #### isApplyFunctionConversionRulesToExternalVariables

          public boolean isApplyFunctionConversionRulesToExternalVariables()

      Ask whether the function conversion rules should be applied to supplied parameter values. For example, this allows an integer to be supplied as the value for a parameter where the expected type is xs:double. The default is true.
      Returns:
        true if function conversion rules are to be applied to supplied values; if false, the supplied value must match the required type exactly.
      Since:
        9.3

    - #### defineGlobalParameters

          public void defineGlobalParameters(GlobalParameterSet params)

      Define global parameters
      Parameters:
        `params` - The ParameterSet passed in by the user, eg. from the command line

    - #### useGlobalParameter

          public boolean useGlobalParameter(StructuredQName qName,
                                   int slot,
                                   SequenceType requiredType,
                                   XPathContext context)
                                     throws XPathException

      Use global parameter. This is called when a global xsl:param element is processed. If a parameter of the relevant name was supplied, it is bound to the xsl:param element. Otherwise the method returns false, so the xsl:param default will be evaluated.
      Parameters:
        `qName` - The name of the parameter
        `slot` - The slot number allocated to the parameter
        `requiredType` - The declared type of the parameter
        `context` - the XPath dynamic evaluation context
      Returns:
        true if a parameter of this name was supplied, false if not
      Throws:
        `XPathException` - if a dynamic error occurs, for example if the supplied parameter value does not match the required type

    - #### setGlobalVariable

          public void setGlobalVariable(GlobalVariable binding,
                               Sequence value)

      Provide a value for a global variable
      Parameters:
        `binding` - identifies the variable
        `value` - the value of the variable

    - #### setExecuting

          public boolean setExecuting(GlobalVariable binding)
                               throws XPathException

      Set/Unset a flag to indicate that a particular global variable is currently being evaluated. Note that this code is not synchronized, so there is no absolute guarantee that two threads will not both evaluate the same global variable; however, apart from wasted time, it is harmless if they do.
      Parameters:
        `binding` - the global variable in question
      Returns:
        true if evaluation of the variable should proceed; false if it is found that the variable has now been evaluated in another thread.
      Throws:
        `XPathException` - If an attempt is made to set the flag when it is already set, this means the definition of the variable is circular.

    - #### setNotExecuting

          public void setNotExecuting(GlobalVariable binding)

      Indicate that a global variable is not currently being evaluated
      Parameters:
        `binding` - the global variable

    - #### saveGlobalVariableValue

          public Sequence saveGlobalVariableValue(GlobalVariable binding,
                                         Sequence value)

      Save the value of a global variable, and mark evaluation as complete.
      Parameters:
        `binding` - the global variable in question
        `value` - the value that this thread has obtained by evaluating the variable
      Returns:
        the value actually given to the variable. Exceptionally this will be different from the supplied value if another thread has evaluated the same global variable concurrently. The returned value should be used in preference, to ensure that all threads agree on the value. They could be different if for example the variable is initialized using the collection() function.

    - #### getGlobalVariableValue

          public Sequence getGlobalVariableValue(GlobalVariable binding)

      Get the value of a global variable
      Parameters:
        `binding` - the Binding that establishes the unique instance of the variable
      Returns:
        the Value of the variable if defined, null otherwise.

    - #### getGlobalVariable

          public Sequence getGlobalVariable(int slot)

      Get the value of a global variable whose slot number is known
      Parameters:
        `slot` - the slot number of the required variable
      Returns:
        the Value of the variable if defined, null otherwise.

    - #### getGlobalVariableMap

          public SlotManager getGlobalVariableMap()

      Get the Global Variable Map, containing the mapping of variable names (fingerprints) to slot numbers. This is provided for use by debuggers.
      Returns:
        the SlotManager containing information about the assignment of slot numbers to global variables and parameters

    - #### getGlobalVariables

          public Sequence[] getGlobalVariables()

      Get all the global variables, as an array. This is provided for use by debuggers that know the layout of the global variables within the array.
      Returns:
        the array of global varaibles.

    - #### registerDependency

          public void registerDependency(GlobalVariable one,
                                GlobalVariable two)
                                  throws XPathException

      Register the dependency of one variable ("one") upon another ("two"), throwing an exception if this would establish a cycle of dependencies.
      Parameters:
        `one` - the first (dependent) variable
        `two` - the second (dependee) variable
      Throws:
        `XPathException` - if adding this dependency creates a cycle of dependencies among global variables.

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