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, JythonInterpreter, RhinoInterpreter
public abstract class GenericInterpreter extends 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 Details

  • Constructor Details

    • GenericInterpreter

      protected GenericInterpreter()

  • Method Details

    • exec

      protected abstract void exec(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(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, 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 Object get(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 Object get(Scope scope, 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(String name, 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, String name, 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(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, 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 Object getFromNamespace(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 Object getFromNamespace(Scope scope, 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 Object getImplicit(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, 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 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(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 Class getClass(String clsnm)
      Returns null since retrieving class is not supported.
      Specified by:
      getClass in interface Interpreter

    • getFunction

      public org.zkoss.xel.Function getFunction(String name, 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 org.zkoss.xel.Function getFunction(Scope scope, String name, Class[] argTypes)
      Returns null since retrieving methods is not supported.
      Since:
      5.0.0

    • containsVariable

      public boolean containsVariable(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, 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 Object getVariable(String name)
      Retrieve the variable.

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

      Specified by:
      getVariable in interface Interpreter

    • getVariable

      public Object getVariable(Scope scope, 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(String name, 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, String name, 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(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, 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