biz.bbeans.buju
Class BInterpreter

java.lang.Object
  biz.bbeans.buju.BInterpreter

Direct Known Subclasses:

BAdminInterpreter

public class BInterpreter

extends Object

A wrapper for the Java interpreter engine.

Constructor Summary

BInterpreter(String initScript)
Create a private (non-shared) interpreter with the given initial script.

BInterpreter(String initScript, boolean shared)
Create a shared or private interpreter with the given initial script.

Method Summary

Object	eval(String line) Evaluate the line of script.
Object	eval(String line, long timeout) Evaluate the line of script.
Interpreter	getInterpreter() Get the interpreter engine wrapped by this BInterpreter.
Map	getProperties() Get the properties Map.
boolean	isLocked() Get the locked state of this interpreter.
boolean	isShared() Get the immutable shared state of this interpreter.
void	lock(long timeout) Lock this interpreter.
void	pop() Pop the last-in namespace from the namespace stack and set it on the interpreter.
void	push() Push the current namespace of the interpreter onto the namespace stack, and create and set a new child namespace for the interpreter.
void	set(String name, Object val) Set the named variable to the given value in the interpreter's current namespace.
void	unlock(long timeout) Unlock this interpreter.

Methods inherited from class java.lang.Object

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

Constructor Detail

BInterpreter

public BInterpreter(String initScript)
             throws EvalError

Create a private (non-shared) interpreter with the given initial script.

Parameters:

initScript - Initial script for the interpreter to evaluate.

Throws:

EvalError - If the initial script does not evaluate properly.

BInterpreter

public BInterpreter(String initScript,
                    boolean shared)
             throws EvalError

Create a shared or private interpreter with the given initial script.

Parameters:

initScript - Initial script for the interpreter to evaluate.

shared - True if shared, false if private. Shared interpreters check locks before doing an evaluation.

Throws:

EvalError - If the initial script does not evaluate properly.

Method Detail

getInterpreter

public Interpreter getInterpreter()

Get the interpreter engine wrapped by this BInterpreter.

Returns:

Interpreter engine instance.

isShared

public boolean isShared()

Get the immutable shared state of this interpreter.

Returns:

True if shared, false if private.

isLocked

public boolean isLocked()

Get the locked state of this interpreter.

Returns:

True if another live thread has this interpreter locked.

lock

public void lock(long timeout)
          throws InterruptedException

Lock this interpreter. If the lock is unavailable for more than the given timeout value, interrupt the thread. Although a private interpreter can be locked, there is no advantage, because it is only visible to one connection thread.

Parameters:

timeout - Time in milleseconds to wait before interrupting a block due to inability of the thread to lock the interpreter. A value of zero will never interrupt a blocked thread, potentially leaving it blocked forever. Any negative value will interrupt the blocked thread immediately.

Throws:

InterruptedException - If the lock is unavailable longer than the specified timeout period.

unlock

public void unlock(long timeout)
            throws InterruptedException

Unlock this interpreter. To unlock the interpreter the method will try to get the lock. If the lock is unavailable for more than the given timeout value, the thread is interrupted. Although a private interpreter can be locked and unlocked, there is no advantage, because it is only visible to one connection thread.

Parameters:

timeout - Time in milleseconds to wait before interrupting a block due to inability of the thread to lock the interpreter. A value of zero will never interrupt the thread, potentially leaving it blocked forever. Any negative value will interrupt the blocked thread immediately.

Throws:

InterruptedException - If the lock is unavailable longer than the specified timeout period.

eval

public Object eval(String line)
            throws EvalError,
                   InterruptedException

Evaluate the line of script. If this interpreter is shared, fail immediately if another thread has it locked.

Parameters:

line - Line of script.

Returns:

Result of evaluation.

Throws:

EvalError - If the script has an evaluation problem.

InterruptedException - If this interpreter is locked by another thread.

eval

public Object eval(String line,
                   long timeout)
            throws EvalError,
                   InterruptedException

Evaluate the line of script. If this interpreter is locked by another thread, wait the given timeout period for the lock to become available before interrupting this thread.

Parameters:

line - Line of script.

timeout - Time in milleseconds to wait before interrupting a block due to inability of the thread lock the interpreter. A value of zero will never interrupt the thread, potentially leaving it blocked forever. Any negative value will interrupt the blocked thread immediately.

Returns:

Result of evaluation.

Throws:

InterruptedException - If the lock is unavailable longer than the specified timeout period.

EvalError - If the script has an evaluation problem.

InterruptedException - If the timeout expires before the thread can lock the interpreter.

set

public void set(String name,
                Object val)
         throws EvalError,
                IllegalStateException

Set the named variable to the given value in the interpreter's current namespace. This method is only used while creating the admin interpreter. It does not honor the interpreter lock, so can not be used by shared interpreters.

Parameters:

name - Name of the variable.

val - Value of the variable.

Throws:

EvalError - If the evaluation has a problem.

IllegalStateException - If the interpreter is shared.

getProperties

public Map getProperties()

Get the properties Map. The properties Map is meant for use by the admin script to store other information associated with this interpreter. It is initially empty. The Map returned is structurally thread-safe.

Returns:

The properties Map.

push

public void push()

Push the current namespace of the interpreter onto the namespace stack, and create and set a new child namespace for the interpreter. The name of the new namespace is "n" + stack.size(). The child namespace will have visibility on all variables and methods that the parent namespace had. Any typed variable declarations will "shadow" a variable with the same name in the parent's scope. Any typed or new variable declarations will become invisible when the child namespace is popped, but any assignment of value to to a variable in the parent's scope will remain. Although this operation is not prohibited on shared interpreters, it would probably be very confusing to the sharers.

pop

public void pop()

Pop the last-in namespace from the namespace stack and set it on the interpreter.