com.pdmfc.tea.runtime
Class STeaRuntime

java.lang.Object
  com.pdmfc.tea.runtime.SContext
      com.pdmfc.tea.runtime.STeaRuntime

public class STeaRuntime
extends SContext

Represents a Tea interpreter.

Usage of this class is preferable to the direct manipulation of SContext objects when running a Tea program.

Constructor Summary

STeaRuntime()
Initializes this toplevel context.

Method Summary

void	addFunction(java.lang.String functionName, SObjFunction function)
void	addModule(SModule pkg) Initializes the package in this context.
void	addModule(java.lang.String className) Initializes a package in this context.
void	end() Signals that this context is no longer to be used.
java.lang.Object	execute(SCode code) Executes the given Tea program.
void	holdStop() Signals this interpreter that it must wait for a call to the releaseStop() method before calling stop() for all packages in the stop() method.
void	releaseStop() The complement to holdStop().
void	setImportDirs(java.util.List dirList)
void	setImportDirs(java.lang.String dirListStr) Utility method for initializing the TEA_LIBRARY variable.
void	setImportDirs(java.lang.String dirList, SCompiler compiler) Deprecated. A call to this method should be replaced by a call to the setImportDirs(String) method and using the execute(SCode) method.
void	start() Signals that this context will be used shortly after.
void	stop() Signals that this context will not be used until a call to the start() method is made again.

Methods inherited from class com.pdmfc.tea.runtime.SContext

clearAll, clone, getParent, getVar, getVarObject, isDefined, newChild, newVar, newVar, setVar

Methods inherited from class java.lang.Object

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

Constructor Detail

STeaRuntime

public STeaRuntime()
            throws STeaException

Initializes this toplevel context.

Throws:

STeaException

Method Detail

setImportDirs

public void setImportDirs(java.lang.String dirList,
                          SCompiler compiler)
                   throws STeaException

Deprecated. A call to this method should be replaced by a call to the setImportDirs(String) method and using the execute(SCode) method.

Sets the list of directories from where the import Tea function will try to read files.

A Tea global variable named TEA_LIBRARY will be created. This variable will contain a list of strings. Each string element is the pathname of one of the directories represented by dirList.

For each directory, a Tea script named init.tea will be executed, if it exits.

This method must not be invoked between calls to start() and stop. Internally start() is is called just before executing the init.tea scripts and stop() is called just afterwards.

Parameters:

dirList - List of directories. Each directory is separated by a path separator character.

compiler - Tea compiler that will be used to compile the init.tea scripts.

Throws:

com.pdmfc.tea.SException - Thrown if there were any problems executing one of the init.tea scripts.

STeaException

setImportDirs

public void setImportDirs(java.lang.String dirListStr)

Utility method for initializing the TEA_LIBRARY variable. This variable will be initialized with a list of strings. These strings are obtained from dirListStr by spliting it using the plataform path separator character as separator between elements.

The elements in the list that is stored in the TEA_LIBRARY variable represent directory pathnames or URLs. These directories and URLs will be used to look for files when the Tea import function is called. If a character in a URL is the same as the path separator character (e.g. ":" in unix) then it should be replaced by a "|" character.

This method is supposed to be called prior to invoking execute(SCode).

Parameters:

dirListStr - A string representing a list of directory pathnames and URLs. The elements are separated by the platform path separator characeter.

setImportDirs

public void setImportDirs(java.util.List dirList)

addFunction

public final void addFunction(java.lang.String functionName,
                              SObjFunction function)

addModule

public void addModule(SModule pkg)
               throws STeaException

Initializes the package in this context. Tipically this will add new commands to the context.

Parameters:

pkg - Reference to the SModule object to be initialized.

Throws:

STeaException

addModule

public void addModule(java.lang.String className)
               throws STeaException

Initializes a package in this context. An object of the java class named className is instantiated. That class must be derived from the SModule class. The newly created SModule object is initialized inside this context.

Parameters:

className - The name of the java class, derived from SModule, of the object to be inSantiated.

Throws:

STeaException - Thrown if there were any problems loading the class or inSantiating the object.

start

public void start()

Signals that this context will be used shortly after. All the packages loaded so far are signaled.

stop

public void stop()

Signals that this context will not be used until a call to the start() method is made again. All the packages loaded so far are signaled with a call to their stop() method.

Before calling the packages' stop() method the current thread waits until all necessary calls to releaseStop() are performed. The calls to releaseStop() must be as many as the ones to holdStop. Note that as the current thread sleeps, the calls to releaseStop() must be made from another thread.

holdStop

public void holdStop()

Signals this interpreter that it must wait for a call to the releaseStop() method before calling stop() for all packages in the stop() method. Note that for each call to this method there must be a corresponding call to releaseStop() before the stop() method exits.

releaseStop

public void releaseStop()

The complement to holdStop().

end

public void end()

Signals that this context is no longer to be used. All the packages that had been loaded so far are signaled. Then they are discarded.

execute

public java.lang.Object execute(SCode code)
                         throws STeaException

Executes the given Tea program. The Tea variable TEA_LIBRARY is supposed to have been created and contain a list of strings. This variable is tipically set by a call to the setImportDirs(String) method.

Parameters:

code - The Tea program to execute.

Returns:

The result of executing the Tea code. This will be the value returned by the last function invocation in the program.

Throws:

STeaException - Thrown if there were any errors while executing the Tea program. It may also be thrown the first time this method is called if there were errors executing the init.tea scripts in the import directories.