org.apache.xpath

## Class VariableStack

- java.lang.Object
- - org.apache.xpath.VariableStack

- All Implemented Interfaces:
    java.lang.Cloneable
  Direct Known Subclasses:
    JAXPVariableStack

      public class VariableStack
      extends java.lang.Object
      implements java.lang.Cloneable

  Defines a class to keep track of a stack for template arguments and variables.

  This has been changed from the previous incarnations of this class to be fairly low level.

  Usage:
    **For internal use only**

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `CLEARLIMITATION` limitation for 1K

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `VariableStack()` Constructor for a variable stack.
    `VariableStack(int initStackSize)` Constructor for a variable stack.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearLocalSlots(int start, int len)` Use this to clear the variables in a section of the stack.
    `java.lang.Object` | `clone()` Returns a clone of this variable stack.
    `XObject` | `elementAt(int i)` Get the element at the given index, regardless of stackframe.
    `XObject` | `getGlobalVariable(XPathContext xctxt, int index)` Get a global variable or parameter from the global stack frame.
    `XObject` | `getGlobalVariable(XPathContext xctxt, int index, boolean destructiveOK)` Get a global variable or parameter from the global stack frame.
    `XObject` | `getLocalVariable(int index, int frame)` Get a local variable or parameter in the current stack frame.
    `XObject` | `getLocalVariable(XPathContext xctxt, int index)` Get a local variable or parameter in the current stack frame.
    `XObject` | `getLocalVariable(XPathContext xctxt, int index, boolean destructiveOK)` Get a local variable or parameter in the current stack frame.
    `int` | `getStackFrame()` Get the position from where the search should start, which is either the searchStart property, or the top of the stack if that value is -1.
    `XObject` | `getVariableOrParam(XPathContext xctxt, QName qname)` Get a variable based on it's qualified name.
    `boolean` | `isLocalSet(int index)` Tell if a local variable has been set or not.
    `int` | `link(int size)` Allocates memory (called a stackframe) on the stack; used to store local variables and parameter arguments.
    `void` | `reset()` Reset the stack to a start position.
    `void` | `setGlobalVariable(int index, XObject val)` Set a global variable or parameter in the global stack frame.
    `void` | `setLocalVariable(int index, XObject val)` Set a local variable or parameter in the current stack frame.
    `void` | `setLocalVariable(int index, XObject val, int stackFrame)` Set a local variable or parameter in the specified stack frame.
    `void` | `setStackFrame(int sf)` Set the current stack frame.
    `int` | `size()` Get size of the stack.
    `void` | `unlink()` Free up the stack frame that was last allocated with `link(int size)`.
    `void` | `unlink(int currentFrame)` Free up the stack frame that was last allocated with `link(int size)`.

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

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

- - ### Field Detail

    - #### CLEARLIMITATION

          public static final int CLEARLIMITATION

      limitation for 1K
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### VariableStack

          public VariableStack()

      Constructor for a variable stack.

    - #### VariableStack

          public VariableStack(int initStackSize)

      Constructor for a variable stack.
      Parameters:
        `initStackSize` - The initial stack size. Must be at least one. The stack can grow if needed.

  - ### Method Detail

    - #### clone

          public java.lang.Object clone()
                                 throws java.lang.CloneNotSupportedException

      Returns a clone of this variable stack.
      Overrides:
        `clone` in class `java.lang.Object`
      Returns:
        a clone of this variable stack.
      Throws:
        `java.lang.CloneNotSupportedException`

    - #### elementAt

          public XObject elementAt(int i)

      Get the element at the given index, regardless of stackframe.
      Parameters:
        `i` - index from zero.
      Returns:
        The item at the given index.

    - #### size

          public int size()

      Get size of the stack.
      Returns:
        the total size of the execution stack.

    - #### reset

          public void reset()

      Reset the stack to a start position.

    - #### setStackFrame

          public void setStackFrame(int sf)

      Set the current stack frame.
      Parameters:
        `sf` - The new stack frame position.

    - #### getStackFrame

          public int getStackFrame()

      Get the position from where the search should start, which is either the searchStart property, or the top of the stack if that value is -1.
      Returns:
        The current stack frame position.

    - #### link

          public int link(int size)

      Allocates memory (called a stackframe) on the stack; used to store local variables and parameter arguments.

      I use the link/unlink concept because of distant Motorola 68000 assembler memories.

      Parameters:
        `size` - The size of the stack frame allocation. This ammount should normally be the maximum number of variables that you can have allocated at one time in the new stack frame.
      Returns:
        The bottom of the stack frame, from where local variable addressing should start from.

    - #### unlink

          public void unlink()

      Free up the stack frame that was last allocated with `link(int size)`.

    - #### unlink

          public void unlink(int currentFrame)

      Free up the stack frame that was last allocated with `link(int size)`.
      Parameters:
        `currentFrame` - The current frame to set to after the unlink.

    - #### setLocalVariable

          public void setLocalVariable(int index,
                                       XObject val)

      Set a local variable or parameter in the current stack frame.
      Parameters:
        `index` - Local variable index relative to the current stack frame bottom.
        `val` - The value of the variable that is being set.

    - #### setLocalVariable

          public void setLocalVariable(int index,
                                       XObject val,
                                       int stackFrame)

      Set a local variable or parameter in the specified stack frame.
      Parameters:
        `index` - Local variable index relative to the current stack frame bottom. NEEDSDOC @param stackFrame
        `val` - The value of the variable that is being set.

    - #### getLocalVariable

          public XObject getLocalVariable(XPathContext xctxt,
                                          int index)
                                   throws javax.xml.transform.TransformerException

      Get a local variable or parameter in the current stack frame.
      Parameters:
        `xctxt` - The XPath context, which must be passed in order to lazy evaluate variables.
        `index` - Local variable index relative to the current stack frame bottom.
      Returns:
        The value of the variable.
      Throws:
        `javax.xml.transform.TransformerException`

    - #### getLocalVariable

          public XObject getLocalVariable(int index,
                                          int frame)
                                   throws javax.xml.transform.TransformerException

      Get a local variable or parameter in the current stack frame.
      Parameters:
        `index` - Local variable index relative to the given frame bottom. NEEDSDOC @param frame
      Returns:
        The value of the variable.
      Throws:
        `javax.xml.transform.TransformerException`

    - #### getLocalVariable

          public XObject getLocalVariable(XPathContext xctxt,
                                          int index,
                                          boolean destructiveOK)
                                   throws javax.xml.transform.TransformerException

      Get a local variable or parameter in the current stack frame.
      Parameters:
        `xctxt` - The XPath context, which must be passed in order to lazy evaluate variables.
        `index` - Local variable index relative to the current stack frame bottom.
      Returns:
        The value of the variable.
      Throws:
        `javax.xml.transform.TransformerException`

    - #### isLocalSet

          public boolean isLocalSet(int index)
                             throws javax.xml.transform.TransformerException

      Tell if a local variable has been set or not.
      Parameters:
        `index` - Local variable index relative to the current stack frame bottom.
      Returns:
        true if the value at the index is not null.
      Throws:
        `javax.xml.transform.TransformerException`

    - #### clearLocalSlots

          public void clearLocalSlots(int start,
                                      int len)

      Use this to clear the variables in a section of the stack. This is used to clear the parameter section of the stack, so that default param values can tell if they've already been set. It is important to note that this function has a 1K limitation.
      Parameters:
        `start` - The start position, relative to the current local stack frame.
        `len` - The number of slots to be cleared.

    - #### setGlobalVariable

          public void setGlobalVariable(int index,
                                        XObject val)

      Set a global variable or parameter in the global stack frame.
      Parameters:
        `index` - Local variable index relative to the global stack frame bottom.
        `val` - The value of the variable that is being set.

    - #### getGlobalVariable

          public XObject getGlobalVariable(XPathContext xctxt,
                                           int index)
                                    throws javax.xml.transform.TransformerException

      Get a global variable or parameter from the global stack frame.
      Parameters:
        `xctxt` - The XPath context, which must be passed in order to lazy evaluate variables.
        `index` - Global variable index relative to the global stack frame bottom.
      Returns:
        The value of the variable.
      Throws:
        `javax.xml.transform.TransformerException`

    - #### getGlobalVariable

          public XObject getGlobalVariable(XPathContext xctxt,
                                           int index,
                                           boolean destructiveOK)
                                    throws javax.xml.transform.TransformerException

      Get a global variable or parameter from the global stack frame.
      Parameters:
        `xctxt` - The XPath context, which must be passed in order to lazy evaluate variables.
        `index` - Global variable index relative to the global stack frame bottom.
      Returns:
        The value of the variable.
      Throws:
        `javax.xml.transform.TransformerException`

    - #### getVariableOrParam

          public XObject getVariableOrParam(XPathContext xctxt,
                                            QName qname)
                                     throws javax.xml.transform.TransformerException

      Get a variable based on it's qualified name. This is for external use only.
      Parameters:
        `xctxt` - The XPath context, which must be passed in order to lazy evaluate variables.
        `qname` - The qualified name of the variable.
      Returns:
        The evaluated value of the variable.
      Throws:
        `javax.xml.transform.TransformerException`

Copyright © 2023 Apache XML Project. All Rights Reserved.