org.eclipse.actf.validation.doc.scripting
Class AbstractCodeInterpreter

java.lang.Object
  extended by org.eclipse.actf.validation.doc.codeproc.AbstractCodeProcessor
      extended by org.eclipse.actf.validation.doc.scripting.AbstractCodeInterpreter
All Implemented Interfaces:
ICodeProcessor
Direct Known Subclasses:
JavaScriptCodeInterpreter

public abstract class AbstractCodeInterpreter
extends AbstractCodeProcessor

used to evaluate expressions and execute scripts given in the XML document. By default, all text content of elements and expressions within curly braces {...} will be evaluated by the interpreter.

Note: Although this class provides the full implementation of the CodeInterpreter interface, it is recommended that the AbstractCodeInterpreter class be extended by those wishing to use scripting languages not currently supported by or packaged with this application.

Author:
Mike Squillace

Field Summary
protected  org.apache.bsf.BSFManager manager
           
 
Fields inherited from class org.eclipse.actf.validation.doc.codeproc.AbstractCodeProcessor
classpath, configuration, language, model
 
Fields inherited from interface org.eclipse.actf.validation.doc.codeproc.ICodeProcessor
FACTORY_PROCESSOR_KEY, SCRIPTLANG_ID
 
Constructor Summary
AbstractCodeInterpreter(String language, IModel model)
          create a code interpreter for processing scripts and expressions in the specified language.
 
Method Summary
 void addScript(String code)
          execute the script code specified.
 void addScript(String scriptName, String scriptCode)
          add the script code with the specified script name to this interpreter for later execution
 Object evaluateArguments(String code, Class returnType)
          attempt to evaluate the given string as an argument of the specified type.
 Object[] evaluateArguments(String code, Class[] paramTypes)
          attempt to evaluate the given code and return an array of objects corresponding to the specified types.
protected abstract  String formatPackageImport(String packageName)
           
 Object getEnvironment()
          used to retreave the environment of this interpreter so as to be passed to the setEnvironment(Object) of a newly instantiated interpreter
 char getExpressionDelimiter()
          the expression delimiter is always a semicolon (;) unless getLanguageSupportsTuples() returns true
 String getInitCode()
          get the initialization code for this interpreter
 boolean getLanguageSupportsTuples()
          return whether or not the language of this interpreter supports "tuples".
protected  String getNullValue()
          return the equivalent of a null value
 String getScript(String scriptName)
          get the code associated with the given script name
protected  void initClasspath()
          initializes the underlying scripting engine with the classpath supplied via setClasspath.
 boolean isCompilerProcessor()
          tests whether or not this processor is a compiler.
protected  void postInit()
          perform initialization after instantiating underlying interpreter.
protected  void preInit()
          perform initialization prior to instantiating the underlying script interpreter.
 boolean processCode(String[] params)
          execute the code in params[0].
 void setClasspath(String cp)
          set the classpath for this processor. The classpath is used in one of two ways, depending upon the type of processor being used:

  • For interpreters, the classpath will be used to define where classes are found from within a script code block. For example, it will be the classpath used to aid the underlying interpreter resolve import statements.
  • For compilers, it is the classpath used to resolve references at compilation time. This is especially important for code that is generated by ACTF for the evaluation of arguments or wrappers for event handlers.

The classpath for a processor isnot necessarily the same as that used by ACTF validation engines. A default value is supplied in the ValidationConstants.CODE_PROCESSOR_CLASSPATH_KEY property in the raven.xml file.

 void setEnvironment(Object env)
          set the environment for this interpreter.
protected  void setLanguageSupportsTuples(boolean b)
          set whether or not the scripting language supports tuples
 void setLocal(String name, Object obj, String vParam)
          declare a new identifier to this interpreter for use in scripts
protected abstract  Object toJavaObject(Object o, Class c)
          overwritten by those interpreters that wrap the results of evaluations in API-specific instances
protected abstract  Object[] toJavaObjects(Object o, Class[] paramTypes)
          convert the given object to an array of objects of the specified types.
 
Methods inherited from class org.eclipse.actf.validation.doc.codeproc.AbstractCodeProcessor
addScript, addScripts, getClasspath, getFileContents, getLanguage, getModel, isIdVisible, makeExpressionList, prepareCode, setIdVisibility, setLanguage, setModel
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

manager

protected org.apache.bsf.BSFManager manager
Constructor Detail

AbstractCodeInterpreter

public AbstractCodeInterpreter(String language,
                               IModel model)
create a code interpreter for processing scripts and expressions in the specified language. The specified language must match one of those given in the raven.xml file.

Note: this constructor calls initClasspath() if a scripting engine for the specified language can be found.

Parameters:
language - -- language of scripts in the document to be processed
model - -- model to be used
See Also:
"resources/actf.xml"
Method Detail

preInit

protected void preInit()
                throws Exception
perform initialization prior to instantiating the underlying script interpreter. This default implementation does nothing.

Throws:
Exception

postInit

protected void postInit()
                 throws Exception
perform initialization after instantiating underlying interpreter. This default implementation does nothing.

Throws:
Exception

setClasspath

public void setClasspath(String cp)
set the classpath for this processor. The classpath is used in one of two ways, depending upon the type of processor being used:

The classpath for a processor isnot necessarily the same as that used by ACTF validation engines. A default value is supplied in the ValidationConstants.CODE_PROCESSOR_CLASSPATH_KEY property in the raven.xml file.

Specified by:
setClasspath in interface ICodeProcessor
Overrides:
setClasspath in class AbstractCodeProcessor
Parameters:
cp - - classpath to use
See Also:
"resources/raven.xml"

setEnvironment

public void setEnvironment(Object env)
set the environment for this interpreter. This method is primarily to be called when a new interpreter is instantiated and is to have the same environment (e.g. local variables) as another interpreter; thus, it should be called in concert with getEnvironment()

Parameters:
env - -- environment of another interpreter retreaved via getEnvironment()

getEnvironment

public Object getEnvironment()
used to retreave the environment of this interpreter so as to be passed to the setEnvironment(Object) of a newly instantiated interpreter

Returns:
environment of this interpreter
See Also:
setEnvironment(Object)

initClasspath

protected void initClasspath()
initializes the underlying scripting engine with the classpath supplied via setClasspath. This will be the classpath referenced from within actual script code.

See Also:
setClasspath(String)

getLanguageSupportsTuples

public boolean getLanguageSupportsTuples()
return whether or not the language of this interpreter supports "tuples". Special processing is available for scripting languages that support "tuples", delimited expressions that can be treated as and evaluated as a single expression

Returns:
true if language supports primitive tuple data type, false otherwise

getExpressionDelimiter

public char getExpressionDelimiter()
the expression delimiter is always a semicolon (;) unless getLanguageSupportsTuples() returns true

Returns:
expression delimiter
See Also:
"resources/raven.xml"

setLanguageSupportsTuples

protected void setLanguageSupportsTuples(boolean b)
set whether or not the scripting language supports tuples

Parameters:
b - -- true if language does, in fact, support tuples

addScript

public void addScript(String code)
execute the script code specified. The interpreter wil, upon execution, reflect the new environment engendered by this code

Parameters:
code - -- code to be executed

addScript

public void addScript(String scriptName,
                      String scriptCode)
add the script code with the specified script name to this interpreter for later execution

Parameters:
scriptName - -- name or id of script
scriptCode - -- code to be executed

getScript

public String getScript(String scriptName)
get the code associated with the given script name

Parameters:
scriptName - -- name of script for which code is desired
Returns:
code of script with given name or null if name is not valid

getInitCode

public String getInitCode()
get the initialization code for this interpreter

Returns:
initialization code for this interpreter (run once at instantiation)

formatPackageImport

protected abstract String formatPackageImport(String packageName)

setLocal

public void setLocal(String name,
                     Object obj,
                     String vParam)
declare a new identifier to this interpreter for use in scripts

Parameters:
name - -- identifier for this object
obj - -- object being declared (this may not be null
vParam - -- visibility parameter
See Also:
ICodeProcessor.setIdVisibility(String)

processCode

public boolean processCode(String[] params)
execute the code in params[0]. Remaining parameters are not currently supported.

Parameters:
params - -- name of script to be executed in [0] (the remainder of the array is ignored)
Returns:
result of process (true for success, false otherwise)

evaluateArguments

public Object evaluateArguments(String code,
                                Class returnType)
                         throws EvaluationException
attempt to evaluate the given string as an argument of the specified type. The given string is evaluated according to the syntax and semantics of the particular interpreter being used.

Parameters:
code - -- argument to be evaluated
returnType - -- desired type of returned object
Returns:
newly created object resulting from evaluation
Throws:
EvaluationException - if evaluation was not successful

evaluateArguments

public Object[] evaluateArguments(String code,
                                  Class[] paramTypes)
                           throws EvaluationException
attempt to evaluate the given code and return an array of objects corresponding to the specified types. In the context of a code interpreter, this method is typically used when languageSupportsTuples() returns true

Parameters:
code - -- code to be evaluated
paramTypes - -- desired types of returned objects
Returns:
newly created objects resulting from evaluation
Throws:
EvaluationException - if evaluation was not successful
See Also:
getLanguageSupportsTuples()

isCompilerProcessor

public boolean isCompilerProcessor()
Description copied from interface: ICodeProcessor
tests whether or not this processor is a compiler.

Returns:
false

toJavaObject

protected abstract Object toJavaObject(Object o,
                                       Class c)
overwritten by those interpreters that wrap the results of evaluations in API-specific instances

Parameters:
o - -- wrapped object
c - -- desired type
Returns:
"unwrapped" o as type c

toJavaObjects

protected abstract Object[] toJavaObjects(Object o,
                                          Class[] paramTypes)
convert the given object to an array of objects of the specified types. This version is typically used by those interpreters in which languageSupportsTuples() returns true

Parameters:
o - -- API-dependent tuple object
paramTypes - -- desired types of returned objects
Returns:
array of objects of the specified types or null if conversion could not be performed
See Also:
getLanguageSupportsTuples()

getNullValue

protected String getNullValue()
return the equivalent of a null value

Returns:
null-value equivalent