Package org.zkoss.zk.scripting.util

## Class GenericInterpreter

- java.lang.Object
- - org.zkoss.zk.scripting.util.GenericInterpreter

- All Implemented Interfaces:
    `Interpreter`
  Direct Known Subclasses:
    `BSHInterpreter`, `GroovyInterpreter`, `JRubyInterpreter`, `JythonInterpreter`, `RhinoInterpreter`

      public abstract class GenericInterpreter
      extends java.lang.Object
      implements Interpreter

  A skeletal class for implementing a interpreter (`Interpreter`).

  Derive classes usually override `exec(java.lang.String)` instead of `interpret(java.lang.String, org.zkoss.zk.ui.ext.Scope)`; In addition, don't override `getVariable(java.lang.String)`, `setVariable(java.lang.String, java.lang.Object)` and `unsetVariable(java.lang.String)`. Instead, override `get(String)`, `contains(String)`, `set(String,Object)` and `unset(String)` instead.

  If an interpreter doesn't support hierarchical scopes, it can simply implement a global scope, and then use `getFromNamespace(java.lang.String)` to retrieve variables from ZK's hierarchical scopes.

  If it supports hierarchical scopes (example: `BSHInterpreter`), it can maintain a one-to-one relationship among interpreter's scopes and ZK's `IdSpace`. Thus, it can retrieve the correct scope by giving ZK's `IdSpace`, and vice versa. It also has to implement `get(Scope,String)`, `contains(Scope,String)` `set(Scope,String,Object)` and `unset(Scope,String)`.

  Whether to support hierarchical scopes is optional.

  Author:
    tomyeh

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.Object` | `UNDEFINED` | Used by `getFromNamespace(java.lang.String)` to denote a variable is not defined.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `GenericInterpreter()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `afterExec()` | Called after `exec(java.lang.String)`, `get(java.lang.String)` and many others.
    `protected void` | `afterInterpret​(Scope scope)` | Called after `exec(java.lang.String)`.
    `protected void` | `beforeExec()` | Called before `exec(java.lang.String)`, `get(java.lang.String)` and many others.
    `protected void` | `beforeInterpret​(Scope scope)` | Called before `exec(java.lang.String)`.
    `protected boolean` | `contains​(java.lang.String name)` | Tests whether a variable is defined in this interpreter.
    `protected boolean` | `contains​(Scope scope, java.lang.String name)` | Tests whether a variable is defined in the interpreter's scope associated with the specified scope.
    `boolean` | `containsVariable​(java.lang.String name)` | Tests whether the variable exists.
    `boolean` | `containsVariable​(Scope scope, java.lang.String name)` | Tests whether the variable exists by using the specified name as a reference to identify the interpreter's scope.
    `void` | `destroy()` | Reset the owner (`getOwner()`) to null.
    `protected abstract void` | `exec​(java.lang.String script)` | Executes the specified script.
    `protected java.lang.Object` | `get​(java.lang.String name)` | Gets the variable from the interpreter.
    `protected java.lang.Object` | `get​(Scope scope, java.lang.String name)` | Gets the variable from the interpreter's scope associated with the giving scope.
    `java.lang.Class` | `getClass​(java.lang.String clsnm)` | Returns null since retrieving class is not supported.
    `protected Scope` | `getCurrent()` | Returns the current scope, or null if no scope is allowed.
    `protected java.lang.Object` | `getFromNamespace​(java.lang.String name)` | Returns the variable through scopes and variable resolvers, or `UNDEFINED` if the variable not defined.
    `protected java.lang.Object` | `getFromNamespace​(Scope scope, java.lang.String name, boolean recurse)` | Returns the variable through the specified scopes and variable resolvers, or `UNDEFINED` if the variable is not defined.
    `Function` | `getFunction​(java.lang.String name, java.lang.Class[] argTypes)` | Returns null since retrieving methods is not supported.
    `Function` | `getFunction​(Scope scope, java.lang.String name, java.lang.Class[] argTypes)` | Returns null since retrieving methods is not supported.
    `protected static java.lang.Object` | `getImplicit​(java.lang.String name)` | Returns the value of the implicit variables.
    `java.lang.String` | `getLanguage()` | Returns the scripting language this interpreter is associated with.
    `Page` | `getOwner()` | Returns the owner of this interpreter.
    `java.lang.Object` | `getVariable​(java.lang.String name)` | Retrieve the variable.
    `java.lang.Object` | `getVariable​(Scope scope, java.lang.String name)` | Returns the value of a variable defined in this interpreter's scope identified by the specified scope.
    `void` | `init​(Page owner, java.lang.String zslang)` | Initializes the interpreter.
    `void` | `interpret​(java.lang.String script, Scope scope)` | Handles the scope and then invoke `exec(java.lang.String)`.
    `protected void` | `set​(java.lang.String name, java.lang.Object value)` | Sets the variable to the interpreter.
    `protected void` | `set​(Scope scope, java.lang.String name, java.lang.Object value)` | Sets the variable to the interpreter's scope associated with the giving scope.
    `void` | `setVariable​(java.lang.String name, java.lang.Object value)` | Sets the variable to this interpreter.
    `void` | `setVariable​(Scope scope, java.lang.String name, java.lang.Object value)` | Sets the value of a variable to this interpreter's scope identified by the specified scope.
    `protected void` | `unset​(java.lang.String name)` | Removes the variable from the interpreter.
    `protected void` | `unset​(Scope scope, java.lang.String name)` | Removes the variable from the interpreter.
    `void` | `unsetVariable​(java.lang.String name)` | Removes the variable from this interpreter.
    `void` | `unsetVariable​(Scope scope, java.lang.String name)` | Removes the value of a variable defined in the interpreter's scope identified by the specified scope.

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

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

    - ### Methods inherited from interface org.zkoss.zk.scripting.Interpreter

      `getNativeInterpreter`

- - ### Field Detail

    - #### UNDEFINED

          public static final java.lang.Object UNDEFINED

      Used by `getFromNamespace(java.lang.String)` to denote a variable is not defined.
      Since:
        2.4.0

  - ### Constructor Detail

    - #### GenericInterpreter

          protected GenericInterpreter()

  - ### Method Detail

    - #### exec

          protected abstract void exec​(java.lang.String script)

      Executes the specified script. Deriving class shall provide an implementation of this method, rather than overriding `interpret(java.lang.String, org.zkoss.zk.ui.ext.Scope)`.

    - #### contains

          protected boolean contains​(java.lang.String name)

      Tests whether a variable is defined in this interpreter. Optional. Implement it if the interpreter can tell the difference between null and undefined.

      By default, it tests whether `get(String)` returns non-null.

      Since:
        2.4.0

    - #### contains

          protected boolean contains​(Scope scope,
                                     java.lang.String name)

      Tests whether a variable is defined in the interpreter's scope associated with the specified scope. Optional. Implement it if the interpreter can tell the difference between null and undefined.

      By default, it tests whether `get(Scope, String)` returns non-null.

      Since:
        5.0.0

    - #### get

          protected java.lang.Object get​(java.lang.String name)

      Gets the variable from the interpreter. Optional. Implement it if you want to expose variables defined in the interpreter to Java codes.

      `beforeExec()` is called first, before this method is invoked.

      An empty (and fake) scope is pushed so `getFromNamespace(java.lang.String)` always returns null.

    - #### get

          protected java.lang.Object get​(Scope scope,
                                         java.lang.String name)

      Gets the variable from the interpreter's scope associated with the giving scope. Optional. Implement it if you want to expose variables defined in the interpreter to Java codes.

      This method is implemented only if the interpreter that supports hierarchical scopes (`HierarchicalAware`).

      Default: the same as `get(String)`.

      `beforeExec()` is called first, before this method is invoked.

      An empty (and fake) scope is pushed so `getFromNamespace(java.lang.String)` always returns null.

      Since:
        5.0.0

    - #### set

          protected void set​(java.lang.String name,
                             java.lang.Object value)

      Sets the variable to the interpreter. Optional. Implement it if you want to allow Java codes to define a variable in the interpreter.

      `beforeExec()` is called first, before this method is invoked.

    - #### set

          protected void set​(Scope scope,
                             java.lang.String name,
                             java.lang.Object value)

      Sets the variable to the interpreter's scope associated with the giving scope. Optional. Implement it if you want to allow Java codes to define a variable in the interpreter.

      This method is implemented only if the interpreter that supports hierarchical scopes (`HierarchicalAware`).

      Default: the same as `set(String, Object)`.

      `beforeExec()` is called first, before this method is invoked.

      Since:
        5.0.0

    - #### unset

          protected void unset​(java.lang.String name)

      Removes the variable from the interpreter. Optional. Implement it if you want to allow Java codes to undefine a variable from the interpreter.

      `beforeExec()` is called first, before this method is invoked.

    - #### unset

          protected void unset​(Scope scope,
                               java.lang.String name)

      Removes the variable from the interpreter. Optional. Implement it if you want to allow Java codes to undefine a variable from the interpreter.

      This method is implemented only if the interpreter that supports hierarchical scopes (`HierarchicalAware`).

      Default: the same as `unset(String)`.

      `beforeExec()` is called first, before this method is invoked.

      Since:
        5.0.0

    - #### beforeInterpret

          protected void beforeInterpret​(Scope scope)

      Called before `exec(java.lang.String)`.

      Default: call `beforeExec()` and push the scope as the active one.

      Since:
        5.0.0

    - #### afterInterpret

          protected void afterInterpret​(Scope scope)

      Called after `exec(java.lang.String)`.

      Default: call `afterExec()`.

      Since:
        5.0.0

    - #### beforeExec

          protected void beforeExec()

      Called before `exec(java.lang.String)`, `get(java.lang.String)` and many others.

      Default: does nothing.

    - #### afterExec

          protected void afterExec()

      Called after `exec(java.lang.String)`, `get(java.lang.String)` and many others.

      Default: does nothing.

    - #### getFromNamespace

          protected java.lang.Object getFromNamespace​(java.lang.String name)

      Returns the variable through scopes and variable resolvers, or `UNDEFINED` if the variable not defined.

      It is usually called to search scopes and variable resolvers, when the real interpreter failed to find a variable in its own scope.

      Note: We use `UNDEFINED` to denote undefined since 2.4.0, while null is a valid value.

    - #### getFromNamespace

          protected java.lang.Object getFromNamespace​(Scope scope,
                                                      java.lang.String name,
                                                      boolean recurse)

      Returns the variable through the specified scopes and variable resolvers, or `UNDEFINED` if the variable is not defined.

      It is usually called to search scopes and variable resolvers, when the real interpreter failed to find a variable in its own scope.

      This method is used with the interpreter that supports hierarchical scopes (`HierarchicalAware`).

      Parameters:
        `scope` - the scope to search from (never null). Note: if `getCurrent()` returns null, this method simply returns null (i.e., ignoring scope).
        `recurse` - whether to look for the parent scope, if any.
      Since:
        5.0.0

    - #### getImplicit

          protected static java.lang.Object getImplicit​(java.lang.String name)

      Returns the value of the implicit variables. It is called by `getFromNamespace(java.lang.String)`, so you don't need to invoke this method if you invoke `getFromNamespace(java.lang.String)`. However, you have to invoke this method as the last step, if you implement your own getFromNamespace from scratch.
      Since:
        3.6.0

    - #### init

          public void init​(Page owner,
                           java.lang.String zslang)

      Description copied from interface: `Interpreter`
      Initializes the interpreter. It is called once when the new instance of interpreter is constructed.
      Specified by:
        `init` in interface `Interpreter`
        `zslang` - the language this interpreter is associated with

    - #### destroy

          public void destroy()

      Reset the owner (`getOwner()`) to null.
      Specified by:
        `destroy` in interface `Interpreter`

    - #### getOwner

          public Page getOwner()

      Description copied from interface: `Interpreter`
      Returns the owner of this interpreter.
      Specified by:
        `getOwner` in interface `Interpreter`

    - #### getLanguage

          public java.lang.String getLanguage()

      Description copied from interface: `Interpreter`
      Returns the scripting language this interpreter is associated with.
      Specified by:
        `getLanguage` in interface `Interpreter`

    - #### interpret

          public void interpret​(java.lang.String script,
                                Scope scope)

      Handles the scope and then invoke `exec(java.lang.String)`.

      Don't override this method, rather, override `exec(java.lang.String)`.

      Specified by:
        `interpret` in interface `Interpreter`
        `scope` - the scope as the context to interpret the script. If null, the current scope is assumed. The current scope is `Scopes.getCurrent(org.zkoss.zk.ui.Page)`, which is the event target's scope, if the thread is processing an event. The event target is `Event.getTarget()`. Otherwise, the current scope is the owner page (`Interpreter.getOwner()`.
      Since:
        5.0.0

    - #### getClass

          public java.lang.Class getClass​(java.lang.String clsnm)

      Returns null since retrieving class is not supported.
      Specified by:
        `getClass` in interface `Interpreter`

    - #### getFunction

          public Function getFunction​(java.lang.String name,
                                      java.lang.Class[] argTypes)

      Returns null since retrieving methods is not supported.
      Specified by:
        `getFunction` in interface `Interpreter`
        `argTypes` - the list of argument (a.k.a., parameter) types. If null, Class[0] is assumed.
      Since:
        3.0.0

    - #### getFunction

          public Function getFunction​(Scope scope,
                                      java.lang.String name,
                                      java.lang.Class[] argTypes)

      Returns null since retrieving methods is not supported.
      Since:
        5.0.0

    - #### containsVariable

          public boolean containsVariable​(java.lang.String name)

      Tests whether the variable exists.

      Deriving class shall override `contains(String)`, instead of this method.

      Specified by:
        `containsVariable` in interface `Interpreter`
      Since:
        2.4.0

    - #### containsVariable

          public boolean containsVariable​(Scope scope,
                                          java.lang.String name)

      Tests whether the variable exists by using the specified name as a reference to identify the interpreter's scope.

      Deriving class shall override `contains(Scope,String)`, instead of this method.

      Since:
        5.0.0

    - #### getVariable

          public java.lang.Object getVariable​(java.lang.String name)

      Retrieve the variable.

      Deriving class shall override `get(String)`, instead of this method.

      Specified by:
        `getVariable` in interface `Interpreter`

    - #### getVariable

          public java.lang.Object getVariable​(Scope scope,
                                              java.lang.String name)

      Returns the value of a variable defined in this interpreter's scope identified by the specified scope. Note: it doesn't search the specified scope (`Scope`).

      Deriving class shall override `get(Scope,String)`, instead of this method.

      This method is part of `HierarchicalAware`. It is defined here to simplify the implementation of the deriving classes, if they support the hierarchical scopes.

      Since:
        5.0.0

    - #### setVariable

          public final void setVariable​(java.lang.String name,
                                        java.lang.Object value)

      Sets the variable to this interpreter.

      Deriving class shall override `set(String,Object)`, instead of this method.

      Specified by:
        `setVariable` in interface `Interpreter`

    - #### setVariable

          public final void setVariable​(Scope scope,
                                        java.lang.String name,
                                        java.lang.Object value)

      Sets the value of a variable to this interpreter's scope identified by the specified scope.

      Deriving class shall override `set(Scope,String,Object)`, instead of this method.

      Since:
        5.0.0

    - #### unsetVariable

          public final void unsetVariable​(java.lang.String name)

      Removes the variable from this interpreter.

      Deriving class shall override `unset(String)`, instead of this method.

      Specified by:
        `unsetVariable` in interface `Interpreter`

    - #### unsetVariable

          public final void unsetVariable​(Scope scope,
                                          java.lang.String name)

      Removes the value of a variable defined in the interpreter's scope identified by the specified scope.

      Deriving class shall override `unset(Scope,String)`, instead of this method.

      Since:
        5.0.0

    - #### getCurrent

          protected Scope getCurrent()

      Returns the current scope, or null if no scope is allowed. Note: if this method returns null, it means the interpreter shall not search variables defined in ZK scope.

      This method will handle `Scopes.getCurrent(org.zkoss.zk.ui.Page)` automatically.

      Since:
        5.0.0