| /******************************************************************************* |
| * Copyright (c) 2000, 2004 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.jdt.core.eval; |
| |
| import org.eclipse.core.runtime.IProgressMonitor; |
| import org.eclipse.jdt.core.*; |
| import org.eclipse.jdt.core.IJavaElement; |
| import org.eclipse.jdt.core.IJavaProject; |
| import org.eclipse.jdt.core.IType; |
| import org.eclipse.jdt.core.JavaModelException; |
| |
| /** |
| * An evaluation context supports evaluating code snippets. |
| * <p> |
| * 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. |
| * <p> |
| * First, a code snippet can return heterogeneous types. Inside the same code |
| * snippet an <code>int</code> could be returned on one line, and a |
| * <code>String</code> on the next, etc. For example, the following would be |
| * considered a valid code snippet: |
| * <pre> |
| * <code> |
| * char c = '3'; |
| * switch (c) { |
| * case '1': return 1; |
| * case '2': return '2'; |
| * case '3': return "3"; |
| * default: return null; |
| * } |
| * </code> |
| * </pre> |
| * </p> |
| * <p> |
| * Second, if the last statement is only an expression, the <code>return</code> |
| * keyword is implied. For example, the following returns <code>false</code>: |
| * <pre> |
| * <code> |
| * int i = 1; |
| * i == 2 |
| * </code> |
| * </pre> |
| * </p> |
| * <p> |
| * 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. |
| * </p> |
| * <p> |
| * 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. |
| * </p> |
| * <p> |
| * 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. |
| * </p> |
| * <p> |
| * Example of use: |
| * <pre> |
| * <code> |
| * IJavaProject project = getJavaProject(); |
| * IEvaluationContext context = project.newEvaluationContext(); |
| * String codeSnippet = "int i= 0; i++"; |
| * ICodeSnippetRequestor requestor = ...; |
| * context.evaluateCodeSnippet(codeSnippet, requestor, progressMonitor); |
| * </code> |
| * </pre> |
| * </p> |
| * <p> |
| * This interface is not intended to be implemented by clients. |
| * <code>IJavaProject.newEvaluationContext</code> can be used to obtain an |
| * instance. |
| * </p> |
| * |
| * @see IJavaProject#newEvaluationContext() |
| */ |
| public interface IEvaluationContext { |
| /** |
| * Returns the global variables declared in this evaluation context. |
| * The variables are maintained in the order they are created in. |
| * |
| * @return the list of global variables |
| */ |
| public IGlobalVariable[] allVariables(); |
| /** |
| * Performs a code completion at the given position in the given code snippet, |
| * reporting results to the given completion requestor. |
| * <p> |
| * Note that code completion does not involve evaluation. |
| * <p> |
| * |
| * @param codeSnippet the code snippet to complete in |
| * @param position the character position in the code snippet to complete at, |
| * or -1 indicating the beginning of the snippet |
| * @param requestor the code completion requestor capable of accepting all |
| * possible types of completions |
| * @exception JavaModelException if code completion could not be performed. Reasons include: |
| * <ul> |
| * <li>The position specified is less than -1 or is greater than the snippet's |
| * length (INDEX_OUT_OF_BOUNDS)</li> |
| * </ul> |
| * @since 2.0 |
| * @deprecated Use {@link #codeComplete(String,int,CompletionRequestor)} instead. |
| */ |
| public void codeComplete( |
| String codeSnippet, |
| int position, |
| ICompletionRequestor requestor) |
| 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. |
| * <p> |
| * Note that if a working copy is empty, it will be as if the original compilation |
| * unit had been deleted. |
| * </p> |
| * <p> |
| * Note that code completion does not involve evaluation. |
| * <p> |
| * |
| * @param codeSnippet the code snippet to complete in |
| * @param position the character position in the code snippet to complete at, |
| * or -1 indicating the beginning of the snippet |
| * @param requestor the code completion requestor capable of accepting all |
| * possible types of completions |
| * @param owner the owner of working copies that take precedence over their original compilation units |
| * @exception JavaModelException if code completion could not be performed. Reasons include: |
| * <ul> |
| * <li>The position specified is less than -1 or is greater than the snippet's |
| * length (INDEX_OUT_OF_BOUNDS)</li> |
| * </ul> |
| * @since 3.0 |
| * @deprecated Use {@link #codeComplete(String,int,CompletionRequestor,WorkingCopyOwner)} instead. |
| */ |
| public void codeComplete( |
| String codeSnippet, |
| int position, |
| ICompletionRequestor requestor, |
| WorkingCopyOwner owner) |
| throws JavaModelException; |
| /** |
| * Performs a code completion at the given position in the given code snippet, |
| * reporting results to the given completion requestor. |
| * <p> |
| * Note that code completion does not involve evaluation. |
| * <p> |
| * |
| * @param codeSnippet the code snippet to complete in |
| * @param position the character position in the code snippet to complete at, |
| * or -1 indicating the beginning of the snippet |
| * @param requestor the code completion requestor capable of accepting all |
| * possible types of completions |
| * @exception JavaModelException if code completion could not be performed. Reasons include: |
| * <ul> |
| * <li>The position specified is less than -1 or is greater than the snippet's |
| * length (INDEX_OUT_OF_BOUNDS)</li> |
| * </ul> |
| * @since 3.1 |
| */ |
| public void codeComplete( |
| 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. |
| * 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. |
| * <p> |
| * Note that if a working copy is empty, it will be as if the original compilation |
| * unit had been deleted. |
| * </p> |
| * <p> |
| * Note that code completion does not involve evaluation. |
| * <p> |
| * |
| * @param codeSnippet the code snippet to complete in |
| * @param position the character position in the code snippet to complete at, |
| * or -1 indicating the beginning of the snippet |
| * @param requestor the code completion requestor capable of accepting all |
| * possible types of completions |
| * @param owner the owner of working copies that take precedence over their original compilation units |
| * @exception JavaModelException if code completion could not be performed. Reasons include: |
| * <ul> |
| * <li>The position specified is less than -1 or is greater than the snippet's |
| * length (INDEX_OUT_OF_BOUNDS)</li> |
| * </ul> |
| * @since 3.0 |
| */ |
| public void codeComplete( |
| String codeSnippet, |
| int position, |
| CompletionRequestor requestor, |
| 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. |
| * <p> |
| * Note that code select does not involve evaluation, and problems are never |
| * reported. |
| * <p> |
| * |
| * @param codeSnippet the code snippet to resolve in |
| * @param offset the position in the code snippet of the first character |
| * of the code to resolve |
| * @param length the length of the selected code to resolve |
| * @return the (possibly empty) list of selection Java elements |
| * @exception JavaModelException if code resolve could not be performed. |
| * Reasons include: |
| * <ul> |
| * <li>The position specified is less than -1 or is greater than the snippet's |
| * length (INDEX_OUT_OF_BOUNDS)</li> |
| * </ul> |
| */ |
| public IJavaElement[] codeSelect(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. |
| * 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. |
| * <p> |
| * Note that if a working copy is empty, it will be as if the original compilation |
| * unit had been deleted. |
| * </p> |
| * <p> |
| * Note that code select does not involve evaluation, and problems are never |
| * reported. |
| * <p> |
| * |
| * @param codeSnippet the code snippet to resolve in |
| * @param offset the position in the code snippet of the first character |
| * of the code to resolve |
| * @param length the length of the selected code to resolve |
| * @param owner the owner of working copies that take precedence over their original compilation units |
| * @return the (possibly empty) list of selection Java elements |
| * @exception JavaModelException if code resolve could not be performed. |
| * Reasons include: |
| * <ul> |
| * <li>The position specified is less than -1 or is greater than the snippet's |
| * length (INDEX_OUT_OF_BOUNDS)</li> |
| * </ul> |
| * @since 3.0 |
| */ |
| public IJavaElement[] codeSelect(String codeSnippet, int offset, int length, WorkingCopyOwner owner) |
| throws JavaModelException; |
| /** |
| * Deletes the given variable from this evaluation context. Does nothing if |
| * the given variable has already been deleted. |
| * |
| * @param variable the global variable |
| */ |
| public void deleteVariable(IGlobalVariable variable); |
| /** |
| * 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 |
| * <code>acceptProblem</code> method is called for each compilation problem that |
| * is detected. Then the resulting class files are handed to the given |
| * requestor's <code>acceptClassFiles</code> method to deploy and run. |
| * <p> |
| * The requestor is expected to: |
| * <ol> |
| * <li>send the class files to the target VM, |
| * <li>load them (starting with the code snippet class), |
| * <li>create a new instance of the code snippet class, |
| * <li>run the method <code>run()</code> of the code snippet, |
| * <li>retrieve the values of the local variables, |
| * <li>retrieve the returned value of the code snippet |
| * </ol> |
| * </p> |
| * <p> |
| * This method is long-running; progress and cancellation are provided |
| * by the given progress monitor. |
| * </p> |
| * |
| * @param codeSnippet the code snippet |
| * @param localVariableTypeNames the dot-separated fully qualified names of the types of the local variables. |
| * @param localVariableNames the names of the local variables as they are declared in the user's code. |
| * @param localVariableModifiers the modifiers of the local variables (default modifier or final modifier). |
| * @param declaringType the type in which the code snippet is evaluated. |
| * @param isStatic whether the code snippet is evaluated in a static member of the declaring type. |
| * @param isConstructorCall whether the code snippet is evaluated in a constructor of the declaring type. |
| * @param requestor the code snippet requestor |
| * @param progressMonitor a progress monitor |
| * @exception JavaModelException if a runtime problem occurred or if this |
| * context's project has no build state |
| */ |
| public void evaluateCodeSnippet( |
| String codeSnippet, |
| String[] localVariableTypeNames, |
| String[] localVariableNames, |
| int[] localVariableModifiers, |
| IType declaringType, |
| boolean isStatic, |
| boolean isConstructorCall, |
| 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 <code>acceptProblem</code> method |
| * is called for each compilation problem that is detected. Then the resulting |
| * class files are handed to the given requestor's <code>acceptClassFiles</code> |
| * method to deploy and run. The requestor is also responsible for getting the |
| * result back. |
| * <p> |
| * This method is long-running; progress and cancellation are provided |
| * by the given progress monitor. |
| * </p> |
| * |
| * @param codeSnippet the code snippet |
| * @param requestor the code snippet requestor |
| * @param progressMonitor a progress monitor |
| * @exception JavaModelException if a runtime problem occurred or if this |
| * context's project has no build state |
| */ |
| public void evaluateCodeSnippet( |
| String codeSnippet, |
| ICodeSnippetRequestor requestor, |
| IProgressMonitor progressMonitor) |
| throws JavaModelException; |
| /** |
| * Evaluates the given global variable. During this operation, |
| * this context's package declaration, imports, and <it>all</it> its declared |
| * variables are verified. The given requestor's <code>acceptProblem</code> |
| * method will be called for each problem that is detected. |
| * <p> |
| * This method is long-running; progress and cancellation are provided |
| * by the given progress monitor. |
| * </p> |
| * |
| * @param variable the global variable |
| * @param requestor the code snippet requestor |
| * @param progressMonitor a progress monitor |
| * @exception JavaModelException if a runtime problem occurred or if this |
| * context's project has no build state |
| */ |
| public void evaluateVariable( |
| IGlobalVariable variable, |
| ICodeSnippetRequestor requestor, |
| IProgressMonitor progressMonitor) |
| throws JavaModelException; |
| /** |
| * 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, <code>"java.util.Hashtable"</code> or <code>"java.util.*"</code>. |
| * |
| * @return the list of import names |
| */ |
| public String[] getImports(); |
| /** |
| * 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, <code>"com.example.myapp"</code>. |
| * |
| * @return the dot-separated package name, or the empty string indicating the |
| * default package |
| */ |
| public String getPackageName(); |
| /** |
| * Returns the Java project this evaluation context was created for. |
| * |
| * @return the Java project |
| */ |
| public IJavaProject getProject(); |
| /** |
| * Creates a new global variable with the given name, type, and initializer. |
| * <p> |
| * The <code>typeName</code> and <code>initializer</code> are interpreted in |
| * the context of this context's package and import declarations. |
| * </p> |
| * <p> |
| * The syntax for a type name corresponds to Type in Field Declaration (JLS2 8.3). |
| * </p> |
| * |
| * @param typeName the type name |
| * @param name the name of the global variable |
| * @param initializer the initializer expression, or <code>null</code> if the |
| * variable is not initialized |
| * @return a new global variable with the given name, type, and initializer |
| */ |
| public IGlobalVariable newVariable( |
| String typeName, |
| String name, |
| String initializer); |
| /** |
| * 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, <code>"java.util.Hashtable"</code> |
| * or <code>"java.util.*"</code>. |
| * |
| * @param imports the list of import names |
| */ |
| public void setImports(String[] imports); |
| /** |
| * Sets the dot-separated name of the package in which code snippets are |
| * to be compiled and run. For example, <code>"com.example.myapp"</code>. |
| * |
| * @param packageName the dot-separated package name, or the empty string |
| * indicating the default package |
| */ |
| public void setPackageName(String packageName); |
| /** |
| * Validates this evaluation context's import declarations. The given requestor's |
| * <code>acceptProblem</code> method is called for each problem that is detected. |
| * |
| * @param requestor the code snippet requestor |
| * @exception JavaModelException if this context's project has no build state |
| */ |
| public void validateImports(ICodeSnippetRequestor requestor) |
| throws JavaModelException; |
| |
| /** |
| * Performs a code completion at the given position in the given code snippet, |
| * reporting results to the given completion requestor. |
| * <p> |
| * Note that code completion does not involve evaluation. |
| * <p> |
| * |
| * @param codeSnippet the code snippet to complete in |
| * @param position the character position in the code snippet to complete at, |
| * or -1 indicating the beginning of the snippet |
| * @param requestor the code completion requestor capable of accepting all |
| * possible types of completions |
| * @exception JavaModelException if code completion could not be performed. Reasons include: |
| * <ul> |
| * <li>The position specified is less than -1 or is greater than the snippet's |
| * length (INDEX_OUT_OF_BOUNDS)</li> |
| * </ul> |
| * @deprecated - use codeComplete(String, int, ICompletionRequestor) instead |
| */ |
| public void codeComplete( |
| String codeSnippet, |
| int position, |
| org.eclipse.jdt.core.ICodeCompletionRequestor requestor) |
| throws JavaModelException; |
| |
| } |