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

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