org.zkoss.zk.scripting.util
Class GenericInterpreter

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

All Implemented Interfaces:

Interpreter

Direct Known Subclasses:

BSHInterpreter

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

A skeletal class for implementing a interpreter (Interpreter) that support Namespace.

Derive classes usually override exec(java.lang.String) instead of interpret(java.lang.String, org.zkoss.zk.scripting.Namespace); 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 hierachical scopes, it can simply implement a global scope, and then use getFromNamespace(java.lang.String) to retrieve variables from ZK's hierachical namespaces.

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

Whether to support hierachical namespaces is optional.

Author:

tomyeh

Field Summary

static java.lang.Object

UNDEFINED Used by getFromNamespace(java.lang.String) to denote a variable is not defined.

Constructor Summary

protected

GenericInterpreter()

Method Summary

protected void	afterExec() Called after exec(java.lang.String), get(java.lang.String) and many others.
protected void	afterInterpret(Namespace ns) 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(Namespace ns) Called before exec(java.lang.String).
protected boolean	contains(Namespace ns, java.lang.String name) Tests whether a variable is defined in the interpreter's scope associated with the specified namespace.
protected boolean	contains(java.lang.String name) Tests whether a variable is defined in this interpreter.
boolean	containsVariable(Namespace ns, java.lang.String name) Tests whether the variable exists by using the specified name as a reference to identify the interpreter's scope.
boolean	containsVariable(java.lang.String name) Tests whether the variable exists.
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(Namespace ns, java.lang.String name) Gets the variable from the interpreter's scope associated with the giving namespace.
protected java.lang.Object	get(java.lang.String name) Gets the variable from the interpreter.
java.lang.Class	getClass(java.lang.String clsnm) Returns null since retrieving class is not supported.
protected Namespace	getCurrent() Returns the current namespace, or null if no namespace is allowed.
protected java.lang.Object	getFromNamespace(Namespace ns, java.lang.String name) Returns the variable through the specified namespaces and variable resolvers, or UNDEFINED if the variable is not defined.
protected java.lang.Object	getFromNamespace(java.lang.String name) Returns the variable through namespaces and variable resolvers, or UNDEFINED if the variable not defined.
org.zkoss.xel.Function	getFunction(Namespace ns, java.lang.String name, java.lang.Class[] argTypes) Returns null since retrieving methods is not supported.
org.zkoss.xel.Function	getFunction(java.lang.String name, java.lang.Class[] argTypes) Returns null since retrieving methods is not supported.
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(Namespace ns, java.lang.String name) Returns the value of a variable defined in this interpreter's scope identified by the specified namespace.
java.lang.Object	getVariable(java.lang.String name) Retrieve the variable.
void	init(Page owner, java.lang.String zslang) Initializes the interpreter.
void	interpret(java.lang.String script, Namespace ns) Handles the namespace and then invoke exec(java.lang.String).
protected void	set(Namespace ns, java.lang.String name, java.lang.Object value) Sets the variable to the interpreter's scope associated with the giving namespace.
protected void	set(java.lang.String name, java.lang.Object value) Sets the variable to the interpreter.
void	setVariable(Namespace ns, java.lang.String name, java.lang.Object value) Sets the value of a variable to this interpreter's scope identified by the specified namespace.
void	setVariable(java.lang.String name, java.lang.Object value) Sets the variable to this interpreter.
protected void	unset(Namespace ns, java.lang.String name) Removes the variable from the interpreter.
protected void	unset(java.lang.String name) Removes the variable from the interpreter.
void	unsetVariable(Namespace ns, java.lang.String name) Removes the value of a variable defined in the interpreter's scope identified by the specified namespace.
void	unsetVariable(java.lang.String name) Removes the variable from this interpreter.

Methods inherited from class java.lang.Object

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

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.scripting.Namespace).

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

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) namespace is pushed so getFromNamespace(java.lang.String) always returns null.

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.

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.

contains

protected boolean contains(Namespace ns,
                           java.lang.String name)

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

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

Since:

2.4.0

get

protected java.lang.Object get(Namespace ns,
                               java.lang.String name)

Gets the variable from the interpreter's scope associated with the giving namespace. 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 hierachical scopes (HierachicalAware).

Default: the same as get(String).

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

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

set

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

Sets the variable to the interpreter's scope associated with the giving namespace. 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 hierachical scopes (HierachicalAware).

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

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

Since:

2.4.0

unset

protected void unset(Namespace ns,
                     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 hierachical scopes (HierachicalAware).

Default: the same as unset(String).

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

Since:

2.4.0

beforeInterpret

protected void beforeInterpret(Namespace ns)

Called before exec(java.lang.String).

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

afterInterpret

protected void afterInterpret(Namespace ns)

Called after exec(java.lang.String).

Default: call afterExec().

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 namespaces and variable resolvers, or UNDEFINED if the variable not defined.

It is usually called to search namespaces 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(Namespace ns,
                                            java.lang.String name)

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

It is usually called to search namespaces 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 hierachical scopes (HierachicalAware).

Parameters:

ns - the namespace to search from (never null). Note: if getCurrent() returns null, this method simply returns null (i.e., ignoring ns).

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,
                      Namespace ns)

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

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

Specified by:

interpret in interface Interpreter

ns - the namspace. If null, the current namespace is assumed. The current namespace is Namespaces.getCurrent(org.zkoss.zk.ui.Page), which is the event target's namespace, if the thread is processing an event. The event target is Event.getTarget(). Otherwise, the current namespace is the owner page's namespace (Interpreter.getOwner().

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 org.zkoss.xel.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 (aka., parameter) types. If null, Class[0] is assumed.

Since:

3.0.0

getFunction

public org.zkoss.xel.Function getFunction(Namespace ns,
                                          java.lang.String name,
                                          java.lang.Class[] argTypes)

Returns null since retrieving methods is not supported.

Since:

3.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

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

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

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

containsVariable

public boolean containsVariable(Namespace ns,
                                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(Namespace,String), instead of this method.

Since:

2.4.0

getVariable

public java.lang.Object getVariable(Namespace ns,
                                    java.lang.String name)

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

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

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

setVariable

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

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

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

Since:

2.4.0

unsetVariable

public final void unsetVariable(Namespace ns,
                                java.lang.String name)

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

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

Since:

2.4.0

getCurrent

protected Namespace getCurrent()

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

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