org.aspectj.org.eclipse.jdt.core.eval

Interface IEvaluationContext

All Known Implementing Classes:

EvaluationContextWrapper

public interface IEvaluationContext

An evaluation context supports evaluating code snippets.

A code snippet is pretty much any valid piece of Java code that could be pasted into the body of a method and compiled. However, there are two areas where the rules are slightly more liberal.

First, a code snippet can return heterogeneous types. Inside the same code snippet an int could be returned on one line, and a String on the next, etc. For example, the following would be considered a valid code snippet:

 
 char c = '3';
 switch (c) {
   case '1': return 1;
   case '2': return '2';
   case '3': return "3";
   default: return null;
 }
 
 

Second, if the last statement is only an expression, the return keyword is implied. For example, the following returns false:

 
 int i = 1;
 i == 2
 
 

Global variables are an additional feature of evaluation contexts. Within an evaluation context, global variables maintain their value across evaluations. These variables are particularly useful for storing the result of an evaluation for use in subsequent evaluations.

The evaluation context remembers the name of the package in which code snippets are run. The user can set this to any package, thereby gaining access to types that are normally only visible within that package.

Finally, the evaluation context remembers a list of import declarations. The user can import any packages and types so that the code snippets may refer to types by their shorter simple names.

Example of use:

 
 IJavaProject project = getJavaProject();
 IEvaluationContext context = project.newEvaluationContext();
 String codeSnippet = "int i= 0; i++";
 ICodeSnippetRequestor requestor = ...;
 context.evaluateCodeSnippet(codeSnippet, requestor, progressMonitor);
 
 

IJavaProject.newEvaluationContext can be used to obtain an instance.

See Also:

IJavaProject.newEvaluationContext()

Method Summary

Modifier and Type	Method and Description
IGlobalVariable[]	allVariables() Returns the global variables declared in this evaluation context.
void	codeComplete(java.lang.String codeSnippet, int position, CompletionRequestor requestor) Performs a code completion at the given position in the given code snippet, reporting results to the given completion requestor.
void	codeComplete(java.lang.String codeSnippet, int position, CompletionRequestor requestor, IProgressMonitor monitor) Performs a code completion at the given position in the given code snippet, reporting results to the given completion requestor.
void	codeComplete(java.lang.String codeSnippet, int position, CompletionRequestor requestor, WorkingCopyOwner owner, IProgressMonitor monitor) Performs a code completion at the given position in the given code snippet, reporting results to the given completion requestor.
void	codeComplete(java.lang.String codeSnippet, int position, ICodeCompletionRequestor requestor) Deprecated. - use codeComplete(String, int, ICompletionRequestor) instead
void	codeComplete(java.lang.String codeSnippet, int position, ICompletionRequestor requestor) Deprecated. Use codeComplete(String,int,CompletionRequestor) instead.
void	codeComplete(java.lang.String codeSnippet, int position, ICompletionRequestor requestor, WorkingCopyOwner owner) Deprecated. Use #codeComplete(String,int,CompletionRequestor,WorkingCopyOwner) instead.
IJavaElement[]	codeSelect(java.lang.String codeSnippet, int offset, int length) Resolves and returns a collection of Java elements corresponding to the source code at the given positions in the given code snippet.
IJavaElement[]	codeSelect(java.lang.String codeSnippet, int offset, int length, WorkingCopyOwner owner) Resolves and returns a collection of Java elements corresponding to the source code at the given positions in the given code snippet.
void	deleteVariable(IGlobalVariable variable) Deletes the given variable from this evaluation context.
void	evaluateCodeSnippet(java.lang.String codeSnippet, ICodeSnippetRequestor requestor, IProgressMonitor progressMonitor) Evaluates the given code snippet.
void	evaluateCodeSnippet(java.lang.String codeSnippet, java.lang.String[] localVariableTypeNames, java.lang.String[] localVariableNames, int[] localVariableModifiers, IType declaringType, boolean isStatic, boolean isConstructorCall, ICodeSnippetRequestor requestor, IProgressMonitor progressMonitor) Evaluates the given code snippet in the context of a suspended thread.
void	evaluateVariable(IGlobalVariable variable, ICodeSnippetRequestor requestor, IProgressMonitor progressMonitor) Evaluates the given global variable.
java.lang.String[]	getImports() Returns the import declarations for this evaluation context.
java.lang.String	getPackageName() Returns the name of the package in which code snippets are to be compiled and run.
IJavaProject	getProject() Returns the Java project this evaluation context was created for.
IGlobalVariable	newVariable(java.lang.String typeName, java.lang.String name, java.lang.String initializer) Creates a new global variable with the given name, type, and initializer.
void	setImports(java.lang.String[] imports) Sets the import declarations for this evaluation context.
void	setPackageName(java.lang.String packageName) Sets the dot-separated name of the package in which code snippets are to be compiled and run.
void	validateImports(ICodeSnippetRequestor requestor) Validates this evaluation context's import declarations.

Method Detail

allVariables

IGlobalVariable[] allVariables()

Returns the global variables declared in this evaluation context. The variables are maintained in the order they are created in.

Returns:

the list of global variables

codeComplete

void codeComplete(java.lang.String codeSnippet,
                  int position,
                  ICompletionRequestor requestor)
           throws JavaModelException

Deprecated. Use codeComplete(String,int,CompletionRequestor) instead.

Performs a code completion at the given position in the given code snippet, reporting results to the given completion requestor.

Note that code completion does not involve evaluation.

Parameters:

codeSnippet - the code snippet to complete in

position - the character position in the code snippet to complete at, or -1 indicating the beginning of the snippet

requestor - the code completion requestor capable of accepting all possible types of completions

Throws:

JavaModelException - if code completion could not be performed. Reasons include:

• The position specified is less than -1 or is greater than the snippet's length (INDEX_OUT_OF_BOUNDS)

Since:

2.0

codeComplete

void codeComplete(java.lang.String codeSnippet,
                  int position,
                  ICompletionRequestor requestor,
                  WorkingCopyOwner owner)
           throws JavaModelException

Deprecated. Use #codeComplete(String,int,CompletionRequestor,WorkingCopyOwner) instead.

Performs a code completion at the given position in the given code snippet, reporting results to the given completion requestor. It considers types in the working copies with the given owner first. In other words, the owner's working copies will take precedence over their original compilation units in the workspace.

Note that if a working copy is empty, it will be as if the original compilation unit had been deleted.

Note that code completion does not involve evaluation.

Parameters:

codeSnippet - the code snippet to complete in

position - the character position in the code snippet to complete at, or -1 indicating the beginning of the snippet

requestor - the code completion requestor capable of accepting all possible types of completions

owner - the owner of working copies that take precedence over their original compilation units

Throws:

JavaModelException - if code completion could not be performed. Reasons include:

• The position specified is less than -1 or is greater than the snippet's length (INDEX_OUT_OF_BOUNDS)

Since:

3.0

codeComplete

void codeComplete(java.lang.String codeSnippet,
                  int position,
                  CompletionRequestor requestor)
           throws JavaModelException

Performs a code completion at the given position in the given code snippet, reporting results to the given completion requestor.

Note that code completion does not involve evaluation.

Parameters:

codeSnippet - the code snippet to complete in

position - the character position in the code snippet to complete at, or -1 indicating the beginning of the snippet

requestor - the code completion requestor capable of accepting all possible types of completions

Throws:

JavaModelException - if code completion could not be performed. Reasons include:

• The position specified is less than -1 or is greater than the snippet's length (INDEX_OUT_OF_BOUNDS)

Since:

3.1

codeComplete

void codeComplete(java.lang.String codeSnippet,
                  int position,
                  CompletionRequestor requestor,
                  IProgressMonitor monitor)
           throws JavaModelException

Performs a code completion at the given position in the given code snippet, reporting results to the given completion requestor.

Note that code completion does not involve evaluation.

If IProgressMonitor is not null then some proposals which can be very long to compute are proposed. To avoid that the code assist operation take too much time a IProgressMonitor which automatically cancel the code assist operation when a specified amount of time is reached could be used.

 new IProgressMonitor() {
     private final static int TIMEOUT = 500; //ms
     private long endTime;
     public void beginTask(String name, int totalWork) {
         fEndTime= System.currentTimeMillis() + TIMEOUT;
     }
     public boolean isCanceled() {
         return endTime <= System.currentTimeMillis();
     }
     ...
 };
 

Parameters:

codeSnippet - the code snippet to complete in

position - the character position in the code snippet to complete at, or -1 indicating the beginning of the snippet

requestor - the code completion requestor capable of accepting all possible types of completions

monitor - the progress monitor used to report progress

Throws:

JavaModelException - if code completion could not be performed. Reasons include:

• The position specified is less than -1 or is greater than the snippet's length (INDEX_OUT_OF_BOUNDS)

Since:

3.5

codeComplete

void codeComplete(java.lang.String codeSnippet,
                  int position,
                  CompletionRequestor requestor,
                  WorkingCopyOwner owner,
                  IProgressMonitor monitor)
           throws JavaModelException

Performs a code completion at the given position in the given code snippet, reporting results to the given completion requestor. It considers types in the working copies with the given owner first. In other words, the owner's working copies will take precedence over their original compilation units in the workspace.

Note that if a working copy is empty, it will be as if the original compilation unit had been deleted.

Note that code completion does not involve evaluation.

If IProgressMonitor is not null then some proposals which can be very long to compute are proposed. To avoid that the code assist operation take too much time a IProgressMonitor which automatically cancel the code assist operation when a specified amount of time is reached could be used.

 new IProgressMonitor() {
     private final static int TIMEOUT = 500; //ms
     private long endTime;
     public void beginTask(String name, int totalWork) {
         fEndTime= System.currentTimeMillis() + TIMEOUT;
     }
     public boolean isCanceled() {
         return endTime <= System.currentTimeMillis();
     }
     ...
 };
 

Parameters:

codeSnippet - the code snippet to complete in

position - the character position in the code snippet to complete at, or -1 indicating the beginning of the snippet

requestor - the code completion requestor capable of accepting all possible types of completions

owner - the owner of working copies that take precedence over their original compilation units

monitor - the progress monitor used to report progress

Throws:

JavaModelException - if code completion could not be performed. Reasons include:

• The position specified is less than -1 or is greater than the snippet's length (INDEX_OUT_OF_BOUNDS)

Since:

3.5

codeSelect

IJavaElement[] codeSelect(java.lang.String codeSnippet,
                          int offset,
                          int length)
                   throws JavaModelException

Resolves and returns a collection of Java elements corresponding to the source code at the given positions in the given code snippet.

Note that code select does not involve evaluation, and problems are never reported.

Parameters:

codeSnippet - the code snippet to resolve in

offset - the position in the code snippet of the first character of the code to resolve

length - the length of the selected code to resolve

Returns:

the (possibly empty) list of selection Java elements

Throws:

JavaModelException - if code resolve could not be performed. Reasons include:

• The position specified is less than -1 or is greater than the snippet's length (INDEX_OUT_OF_BOUNDS)

codeSelect

IJavaElement[] codeSelect(java.lang.String codeSnippet,
                          int offset,
                          int length,
                          WorkingCopyOwner owner)
                   throws JavaModelException

Resolves and returns a collection of Java elements corresponding to the source code at the given positions in the given code snippet. It considers types in the working copies with the given owner first. In other words, the owner's working copies will take precedence over their original compilation units in the workspace.

Note that if a working copy is empty, it will be as if the original compilation unit had been deleted.

Note that code select does not involve evaluation, and problems are never reported.

Parameters:

codeSnippet - the code snippet to resolve in

offset - the position in the code snippet of the first character of the code to resolve

length - the length of the selected code to resolve

owner - the owner of working copies that take precedence over their original compilation units

Returns:

the (possibly empty) list of selection Java elements

Throws:

JavaModelException - if code resolve could not be performed. Reasons include:

• The position specified is less than -1 or is greater than the snippet's length (INDEX_OUT_OF_BOUNDS)

Since:

3.0

deleteVariable

void deleteVariable(IGlobalVariable variable)

Deletes the given variable from this evaluation context. Does nothing if the given variable has already been deleted.

Parameters:

variable - the global variable

evaluateCodeSnippet

void evaluateCodeSnippet(java.lang.String codeSnippet,
                         java.lang.String[] localVariableTypeNames,
                         java.lang.String[] localVariableNames,
                         int[] localVariableModifiers,
                         IType declaringType,
                         boolean isStatic,
                         boolean isConstructorCall,
                         ICodeSnippetRequestor requestor,
                         IProgressMonitor progressMonitor)
                  throws JavaModelException

Evaluates the given code snippet in the context of a suspended thread. The code snippet is compiled along with this context's package declaration, imports, and global variables. The given requestor's acceptProblem method is called for each compilation problem that is detected. Then the resulting class files are handed to the given requestor's acceptClassFiles method to deploy and run.

The requestor is expected to:

1. send the class files to the target VM,
2. load them (starting with the code snippet class),
3. create a new instance of the code snippet class,
4. run the method run() of the code snippet,
5. retrieve the values of the local variables,
6. retrieve the returned value of the code snippet

This method is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

codeSnippet - the code snippet

localVariableTypeNames - the dot-separated fully qualified names of the types of the local variables.

localVariableNames - the names of the local variables as they are declared in the user's code.

localVariableModifiers - the modifiers of the local variables (default modifier or final modifier).

declaringType - the type in which the code snippet is evaluated.

isStatic - whether the code snippet is evaluated in a static member of the declaring type.

isConstructorCall - whether the code snippet is evaluated in a constructor of the declaring type.

requestor - the code snippet requestor

progressMonitor - a progress monitor

Throws:

JavaModelException - if a runtime problem occurred or if this context's project has no build state

evaluateCodeSnippet

void evaluateCodeSnippet(java.lang.String codeSnippet,
                         ICodeSnippetRequestor requestor,
                         IProgressMonitor progressMonitor)
                  throws JavaModelException

Evaluates the given code snippet. The code snippet is compiled along with this context's package declaration, imports, and global variables. The given requestor's acceptProblem method is called for each compilation problem that is detected. Then the resulting class files are handed to the given requestor's acceptClassFiles method to deploy and run. The requestor is also responsible for getting the result back.

This method is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

codeSnippet - the code snippet

requestor - the code snippet requestor

progressMonitor - a progress monitor

Throws:

JavaModelException - if a runtime problem occurred or if this context's project has no build state

evaluateVariable

void evaluateVariable(IGlobalVariable variable,
                      ICodeSnippetRequestor requestor,
                      IProgressMonitor progressMonitor)
               throws JavaModelException

Evaluates the given global variable. During this operation, this context's package declaration, imports, and all its declared variables are verified. The given requestor's acceptProblem method will be called for each problem that is detected.

This method is long-running; progress and cancellation are provided by the given progress monitor.

Parameters:

variable - the global variable

requestor - the code snippet requestor

progressMonitor - a progress monitor

Throws:

JavaModelException - if a runtime problem occurred or if this context's project has no build state

getImports

java.lang.String[] getImports()

Returns the import declarations for this evaluation context. Returns and empty list if there are no imports (the default if the imports have never been set). The syntax for the import corresponds to a fully qualified type name, or to an on-demand package name as defined by ImportDeclaration (JLS2 7.5). For example, "java.util.Hashtable" or "java.util.*".

Returns:

the list of import names

getPackageName

java.lang.String getPackageName()

Returns the name of the package in which code snippets are to be compiled and run. Returns an empty string for the default package (the default if the package name has never been set). For example, "com.example.myapp".

Returns:

the dot-separated package name, or the empty string indicating the default package

getProject

IJavaProject getProject()

Returns the Java project this evaluation context was created for.

Returns:

the Java project

newVariable

IGlobalVariable newVariable(java.lang.String typeName,
                            java.lang.String name,
                            java.lang.String initializer)

Creates a new global variable with the given name, type, and initializer.

The typeName and initializer are interpreted in the context of this context's package and import declarations.

The syntax for a type name corresponds to Type in Field Declaration (JLS2 8.3).

Parameters:

typeName - the type name

name - the name of the global variable

initializer - the initializer expression, or null if the variable is not initialized

Returns:

a new global variable with the given name, type, and initializer

setImports

void setImports(java.lang.String[] imports)

Sets the import declarations for this evaluation context. An empty list indicates there are no imports. The syntax for the import corresponds to a fully qualified type name, or to an on-demand package name as defined by ImportDeclaration (JLS2 7.5). For example, "java.util.Hashtable" or "java.util.*".

Parameters:

imports - the list of import names

setPackageName

void setPackageName(java.lang.String packageName)

Sets the dot-separated name of the package in which code snippets are to be compiled and run. For example, "com.example.myapp".

Parameters:

packageName - the dot-separated package name, or the empty string indicating the default package

validateImports

void validateImports(ICodeSnippetRequestor requestor)
              throws JavaModelException

Validates this evaluation context's import declarations. The given requestor's acceptProblem method is called for each problem that is detected.

Parameters:

requestor - the code snippet requestor

Throws:

JavaModelException - if this context's project has no build state

codeComplete

void codeComplete(java.lang.String codeSnippet,
                  int position,
                  ICodeCompletionRequestor requestor)
           throws JavaModelException

Deprecated. - use codeComplete(String, int, ICompletionRequestor) instead

Performs a code completion at the given position in the given code snippet, reporting results to the given completion requestor.

Note that code completion does not involve evaluation.

Parameters:

codeSnippet - the code snippet to complete in

position - the character position in the code snippet to complete at, or -1 indicating the beginning of the snippet

requestor - the code completion requestor capable of accepting all possible types of completions

Throws:

JavaModelException - if code completion could not be performed. Reasons include:

• The position specified is less than -1 or is greater than the snippet's length (INDEX_OUT_OF_BOUNDS)