org.eclipse.actf.validation.doc.codeproc
Interface ICodeProcessor

All Known Implementing Classes:
AbstractCodeInterpreter, AbstractCodeProcessor, JavaScriptCodeInterpreter

public interface ICodeProcessor

responsible for processing any code within a validation document. A ICodeProcessor may be implemented as one type:

Author:
Mike Squillace

Field Summary
static String FACTORY_PROCESSOR_KEY
           
static String SCRIPTLANG_ID
          pool id for script languages pool - value is 'scriptlang'
 
Method Summary
 void addScript(String code)
          add the specified code as a script for this processor.
 void addScript(String scriptName, InputStream scriptStream)
          add the code in the given stream to be executed later by this processor
 void addScript(String scriptName, String scriptCode)
          add the script code with the specified script name to this processor for later execution
 void addScripts(Map scriptMap)
          add the given scripts to this processor for later execution or compilation.
 Object evaluateArguments(String arg, Class returnType)
          attempt to evaluate the given string as an argument of the specified type
 Object[] evaluateArguments(String args, Class[] paramTypes)
          attempt to evaluate the given string as a set of arguments of objects corresponding to the specified types.
 String getClasspath()
          returns the classpath being used from within script code or to compile source code generated during argument evaluation.
 Object getEnvironment()
          used to retreave the environment of this processor so as to be passed to the setEnvironment(Object) of a newly instantiated processor
 char getExpressionDelimiter()
          get the default expression delimiter for the language.
 String getInitCode()
          get the initialization code for this processor.
 String getLanguage()
          get the language identifier for this processor
 IModel getModel()
          return model used by this processor
 String getScript(String scriptName)
          get the code associated with the given script name
 boolean isCompilerProcessor()
          tests whether or not this processor is a compiler.
 String[] makeExpressionList(String str)
          split the specified string into "expressions" bounded by the delimiter returned by getExpressionDelimiter.
 String prepareCode(String code)
          prepare code for execution or compilation (e.g. by resolving entity references or removing CDATA tags)
 boolean processCode(String[] params)
          process the code according to the implementation of this processor (i.e.
 void setClasspath(String cp)
          set the classpath for this processor.
 void setEnvironment(Object env)
          set the environment for this processor.
 void setIdVisibility(String visibility)
          set the visibility for symbols in the XML document.
 void setLanguage(String lang)
          set the language identifier for this processor.
 void setLocal(String name, Object obj, String vParam)
          declare a new identifier to this processor for use in scripts.
 void setModel(IModel model)
          set the model for this processor
 

Field Detail

SCRIPTLANG_ID

static final String SCRIPTLANG_ID
pool id for script languages pool - value is 'scriptlang'

See Also:
Constant Field Values

FACTORY_PROCESSOR_KEY

static final String FACTORY_PROCESSOR_KEY
See Also:
Constant Field Values
Method Detail

setModel

void setModel(IModel model)
set the model for this processor

Parameters:
model - -- model

getModel

IModel getModel()
return model used by this processor

Returns:
model used by this processor

getClasspath

String getClasspath()
returns the classpath being used from within script code or to compile source code generated during argument evaluation. This classpath is not necessarily the same as that used by the ACTF validation engine.

Returns:
classpath being used by underlying interpreter or compiler
See Also:
setClasspath(String)

setClasspath

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.

Parameters:
cp - - classpath to use
See Also:
"resources/raven.xml"

setLanguage

void setLanguage(String lang)
set the language identifier for this processor. This should match one of the keys in the 'scriptlang' pool in the actf.xml file.

Parameters:
lang - -- language identifier for this processor
See Also:
"resources/actf.xml"

getLanguage

String getLanguage()
get the language identifier for this processor

Returns:
language identifier for this processor

setEnvironment

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

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

getEnvironment

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

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

setIdVisibility

void setIdVisibility(String visibility)
                     throws IllegalArgumentException
set the visibility for symbols in the XML document. Visibility determines which (if any) of the symbols declared via the rib:id attribute will be visible in scripts or compiled classes. Options for this parameter include:

The setLocal method of implementations of this interface should take care to set the environment according to the constraints of this property.

Note: Not utilized in ACTF

Parameters:
visibility - -- one of "ALL", "NONE", or "<reg_expression>"
Throws:
IllegalArgumentException - if argument cannot be processed

addScript

void addScript(String code)
add the specified code as a script for this processor. This code may be executed as is upon invoking this method if the processor is an implementation of an interpreter or simply added to a body of code to be compiled later and executed upon initialization or instantiation of the compiled class.

Parameters:
code - -- code to be added to this processor

addScript

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

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

addScript

void addScript(String scriptName,
               InputStream scriptStream)
add the code in the given stream to be executed later by this processor

Parameters:
scriptName - -- name of script
scriptStream - -- stream containing code for script

addScripts

void addScripts(Map scriptMap)
add the given scripts to this processor for later execution or compilation. The map is keyed by script name and contains values holding the code to be executed or included in the execution.

Parameters:
scriptMap - -- map keyed by script names with values containing code to be executed

getScript

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

String getInitCode()
get the initialization code for this processor. This is code typically hard-coded into the implementation to be run upon initialization of the interpreter or upon instantiation of a compiled class.

Returns:
initialization code for this processor

setLocal

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

By specifying an override parameter "either "true" or "false"), the following behavior should result:

Note: Only first two parameters relevant to ACTF; always pass 'true' to vParam.

Parameters:
name - -- identifier for this object
obj - -- object being declared (may be null)
vParam - -- either "true" or "false", the rib:visible attribute value (may also be null, in which case the behavior specified via setIdVisibility will be adopted
See Also:
setIdVisibility(String)

getExpressionDelimiter

char getExpressionDelimiter()
get the default expression delimiter for the language. This will typically be either a comma (,) or semicolon (;). This can also be set via the 'exprdelim' property in the raven.xml file.

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

makeExpressionList

String[] makeExpressionList(String str)
                            throws IllegalArgumentException
split the specified string into "expressions" bounded by the delimiter returned by getExpressionDelimiter. Although what constitutes an expression is language-dependent, this method will insure that each String in the given list is consistent and complete. The following tokens can be recognized:

The default implementation in both org.eclipse.actf.validation.doc.scripting.AbstractCodeInterpreter and org.eclipse.actf.validation.doc.scripting.BaseCodeCompiler implement this method in the manner described above.

Parameters:
str - -- string to be split
Returns:
array of String objects representing tokens in specified string
Throws:
IllegalArgumentException - if symbol mismatch occurs

prepareCode

String prepareCode(String code)
prepare code for execution or compilation (e.g. by resolving entity references or removing CDATA tags)

Parameters:
code - -- code to be prepared
Returns:
code readied for execution or compilation

evaluateArguments

Object evaluateArguments(String arg,
                         Class returnType)
                         throws EvaluationException
attempt to evaluate the given string as an argument of the specified type

Parameters:
arg - -- 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

Object[] evaluateArguments(String args,
                           Class[] paramTypes)
                           throws EvaluationException
attempt to evaluate the given string as a set of arguments of objects corresponding to the specified types.

Parameters:
args - -- arguments to be evaluated
paramTypes - -- desired types of returned objects
Returns:
newly created objects resulting from evaluation
Throws:
EvaluationException - if evaluation was not successful

isCompilerProcessor

boolean isCompilerProcessor()
tests whether or not this processor is a compiler.

Returns:
true if this processor is a compiler implementation, false otherwise

processCode

boolean processCode(String[] params)
process the code according to the implementation of this processor (i.e. whether it is a code compiler or code interpreter.

This method may perform one of two processes:

Parameters:
params - -- parameters for execution or for compilation
Returns:
result of process (true for success, false otherwise)