Package org.zkoss.zk.scripting.bsh

## Class BSHInterpreter

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

- All Implemented Interfaces:
    `HierarchicalAware`, `Interpreter`, `SerializableAware`

      public class BSHInterpreter
      extends GenericInterpreter
      implements SerializableAware, HierarchicalAware

  The interpreter that uses BeanShell to interpret zscript codes.

  Unlike many other implementations, it supports the hierarchical scopes (`HierarchicalAware`). That is, it uses an independent BeanShell NameSpace (a.k.a. interpreter's scope) to store the variables/classes/methods defined in BeanShell script for each ZK scope (`Scope`). Since one-to-one relationship between BeanShell's scope and ZK scope, the invocation of BeanShell methods can execute correctly without knowing what scope it is. However, if you want your codes portable across different interpreters, you had better to call `Scopes.beforeInterpret(org.zkoss.zk.ui.ext.Scope)` to prepare the proper scope, before calling any method defined in zscript.

  ## How serialization work?

  First, all NameSpace objects have to serialize. Second, the top-level namespace (GlobalNS) is wrapped with NSWrap, which is not serializable. It is serialized when `SerializableAware.write(java.io.ObjectOutputStream, org.zkoss.zk.scripting.SerializableAware.Filter)` is called (triggered by PageImpl's write).

  On the other hand, all non-top-level namespaces (NS) are wrapped with NSWrapSR which is serializable, so they are serialized with the attributes of a ID space owner being serialized.

  Author:
    tomyeh

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.zkoss.zk.scripting.SerializableAware

      `SerializableAware.Filter`

  - ### Field Summary

    - ### Fields inherited from class org.zkoss.zk.scripting.util.GenericInterpreter

      `UNDEFINED`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `BSHInterpreter()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `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.
    `void` | `destroy()` | Reset the owner (`GenericInterpreter.getOwner()`) to null.
    `protected 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.
    `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.
    `java.lang.Object` | `getNativeInterpreter()` | Returns the native interpreter, or null if it is not initialized or destroyed.
    `void` | `init​(Page owner, java.lang.String zslang)` | Initializes the interpreter.
    `protected void` | `loadDefaultImports​(bsh.NameSpace bshns)` | Called when the top-level BeanShell scope is created.
    `void` | `read​(java.io.ObjectInputStream s)` | Reads the name and value of the variable from the specified input stream.
    `protected void` | `set​(java.lang.String name, java.lang.Object val)` | Sets the variable to the interpreter.
    `protected void` | `set​(Scope scope, java.lang.String name, java.lang.Object val)` | Sets the variable to the interpreter's scope associated with the giving 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` | `write​(java.io.ObjectOutputStream s, SerializableAware.Filter filter)` | Writes the name and value of the variables of this namespace to the specified stream.

    - ### Methods inherited from class org.zkoss.zk.scripting.util.GenericInterpreter

      `afterExec, afterInterpret, beforeExec, beforeInterpret, containsVariable, containsVariable, getCurrent, getFromNamespace, getFromNamespace, getImplicit, getLanguage, getOwner, getVariable, getVariable, interpret, setVariable, setVariable, unsetVariable, unsetVariable`

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

      `containsVariable, getVariable, setVariable, unsetVariable`

- - ### Constructor Detail

    - #### BSHInterpreter

          public BSHInterpreter()

  - ### Method Detail

    - #### loadDefaultImports

          protected void loadDefaultImports​(bsh.NameSpace bshns)

      Called when the top-level BeanShell scope is created. By default, it does nothing.

      Note: to speed up the performance, this implementation disabled `NameSpace.loadDefaultImports()`. It only imports the java.lang and java.util packages. If you want the built command and import packages, you can override this method. For example,

          protected void loadDefaultImports(NameSpace bshns) {
            bshns.importCommands("/bsh/commands");
          }

      Since:
        3.0.2

    - #### exec

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

      Description copied from class: `GenericInterpreter`
      Executes the specified script. Deriving class shall provide an implementation of this method, rather than overriding `GenericInterpreter.interpret(java.lang.String, org.zkoss.zk.ui.ext.Scope)`.
      Specified by:
        `exec` in class `GenericInterpreter`

    - #### contains

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

      Description copied from class: `GenericInterpreter`
      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 `GenericInterpreter.get(String)` returns non-null.

      Overrides:
        `contains` in class `GenericInterpreter`

    - #### contains

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

      Description copied from class: `GenericInterpreter`
      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 `GenericInterpreter.get(Scope, String)` returns non-null.

      Overrides:
        `contains` in class `GenericInterpreter`

    - #### get

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

      Description copied from class: `GenericInterpreter`
      Gets the variable from the interpreter. Optional. Implement it if you want to expose variables defined in the interpreter to Java codes.

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

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

      Overrides:
        `get` in class `GenericInterpreter`

    - #### get

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

      Description copied from class: `GenericInterpreter`
      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 `GenericInterpreter.get(String)`.

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

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

      Overrides:
        `get` in class `GenericInterpreter`

    - #### set

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

      Description copied from class: `GenericInterpreter`
      Sets the variable to the interpreter. Optional. Implement it if you want to allow Java codes to define a variable in the interpreter.

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

      Overrides:
        `set` in class `GenericInterpreter`

    - #### set

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

      Description copied from class: `GenericInterpreter`
      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 `GenericInterpreter.set(String, Object)`.

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

      Overrides:
        `set` in class `GenericInterpreter`

    - #### unset

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

      Description copied from class: `GenericInterpreter`
      Removes the variable from the interpreter. Optional. Implement it if you want to allow Java codes to undefine a variable from the interpreter.

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

      Overrides:
        `unset` in class `GenericInterpreter`

    - #### unset

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

      Description copied from class: `GenericInterpreter`
      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 `GenericInterpreter.unset(String)`.

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

      Overrides:
        `unset` in class `GenericInterpreter`

    - #### 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`
      Overrides:
        `init` in class `GenericInterpreter`
        `zslang` - the language this interpreter is associated with

    - #### destroy

          public void destroy()

      Description copied from class: `GenericInterpreter`
      Reset the owner (`GenericInterpreter.getOwner()`) to null.
      Specified by:
        `destroy` in interface `Interpreter`
      Overrides:
        `destroy` in class `GenericInterpreter`

    - #### getNativeInterpreter

          public java.lang.Object getNativeInterpreter()

      Returns the native interpreter, or null if it is not initialized or destroyed. From application's standpoint, it never returns null, and the returned object must be an instance of `Interpreter`
      Specified by:
        `getNativeInterpreter` in interface `Interpreter`
      Since:
        3.0.2

    - #### getClass

          public java.lang.Class<?> getClass​(java.lang.String clsnm)

      Description copied from class: `GenericInterpreter`
      Returns null since retrieving class is not supported.
      Specified by:
        `getClass` in interface `Interpreter`
      Overrides:
        `getClass` in class `GenericInterpreter`

    - #### getFunction

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

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

    - #### getFunction

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

      Description copied from class: `GenericInterpreter`
      Returns null since retrieving methods is not supported.
      Specified by:
        `getFunction` in interface `HierarchicalAware`
      Overrides:
        `getFunction` in class `GenericInterpreter`
      Parameters:
        `scope` - the scope used as a reference to identify the correct scope for searching the method. Note: this method doesn't look for any variable stored in scope.
        `argTypes` - the list of argument (a.k.a., parameter) types. If null, Class[0] is assumed.

    - #### write

          public void write​(java.io.ObjectOutputStream s,
                            SerializableAware.Filter filter)
                     throws java.io.IOException

      Description copied from interface: `SerializableAware`
      Writes the name and value of the variables of this namespace to the specified stream.

      If the variable's value is not serializable, it won't be written.

      To read back, use `SerializableAware.read(java.io.ObjectInputStream)`.

      Specified by:
        `write` in interface `SerializableAware`
      Throws:
        `java.io.IOException`

    - #### read

          public void read​(java.io.ObjectInputStream s)
                    throws java.io.IOException,
                           java.lang.ClassNotFoundException

      Description copied from interface: `SerializableAware`
      Reads the name and value of the variable from the specified input stream.
      Specified by:
        `read` in interface `SerializableAware`
      Throws:
        `java.io.IOException`
        `java.lang.ClassNotFoundException`
      See Also:
        `SerializableAware.write(java.io.ObjectOutputStream, org.zkoss.zk.scripting.SerializableAware.Filter)`