path: root/org.eclipse.jdt.core/model/org/eclipse/jdt/core/eval/IEvaluationContext.java

/*******************************************************************************
 * Copyright (c) 2000, 2019 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * 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>
 * <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>
 * 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>
 * 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>
 * <code>IJavaProject.newEvaluationContext</code> can be used to obtain an
 * instance.
 * </p>
 *
 * @see IJavaProject#newEvaluationContext()
 * @noimplement This interface is not intended to be implemented by clients.
 */
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.
	 * <p>
	 * Note that code completion does not involve evaluation.
	 * <p>
	 * If {@link IProgressMonitor} is not <code>null</code> then some proposals which
	 * can be very long to compute are proposed. To avoid that the code assist operation
	 * take too much time a {@link IProgressMonitor} which automatically cancel the code
	 * assist operation when a specified amount of time is reached could be used.
	 *
	 * <pre>
	 * 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();
	 *     }
	 *     ...
	 * };
	 * </pre>
	 * <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 monitor the progress monitor used to report progress
	 * @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.5
	 */
	public void codeComplete(
		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.
	 * 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.1
	 */
	public void codeComplete(
		String codeSnippet,
		int position,
		CompletionRequestor 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.
	 * 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>
	 * If {@link IProgressMonitor} is not <code>null</code> then some proposals which
	 * can be very long to compute are proposed. To avoid that the code assist operation
	 * take too much time a {@link IProgressMonitor} which automatically cancel the code
	 * assist operation when a specified amount of time is reached could be used.
	 *
	 * <pre>
	 * 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();
	 *     }
	 *     ...
	 * };
	 * </pre>
	 * <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
	 * @param monitor the progress monitor used to report progress
	 * @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.5
	 */
	public void codeComplete(
		String codeSnippet,
		int position,
		CompletionRequestor requestor,
		WorkingCopyOwner owner,
		IProgressMonitor monitor)
		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>
	 * 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 <i>all</i> 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;

}