org.eclipse.jdt.core.eval.ICodeSnippetRequestor Maven / Gradle / Ivy

/*******************************************************************************
 * Copyright (c) 2000, 2009 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.resources.IMarker;
import org.eclipse.jdt.internal.eval.EvaluationConstants;

/**
 * A code snippet requestor implements a callback interface for installing
 * the class files for a code snippet on the target and running it.
 * In addition, it receives compilation problems detected during code snippet
 * compilation.
 * 
 * Clients may implement this interface to provide a bridge a running Java VM.
 * 
 *
 * @see IEvaluationContext#evaluateCodeSnippet(String, ICodeSnippetRequestor, org.eclipse.core.runtime.IProgressMonitor)
 * @see IEvaluationContext#evaluateCodeSnippet(String, String[], String[], int[], org.eclipse.jdt.core.IType, boolean, boolean, ICodeSnippetRequestor, org.eclipse.core.runtime.IProgressMonitor)
 */
public interface ICodeSnippetRequestor {

	/**
	 * The prefix of fields that represent the local variables in a snippet
	 * class.
	 */
	public static final String LOCAL_VAR_PREFIX = new String(EvaluationConstants.LOCAL_VAR_PREFIX);

	/**
	 * The name of the field that represent 'this' in a snippet class
	 * instance.
	 */
	public static final String DELEGATE_THIS = new String(EvaluationConstants.DELEGATE_THIS);

	/**
	 * The name of the instance method in the snippet class that runs the code
	 * snippet.
	 */
	public static final String RUN_METHOD = EvaluationConstants.RUN_METHOD;

	/**
	 * The name of the field (of type java.lang.Object) on the code
	 * snippet instance that contains the returned value.
	 */
	public static final String RESULT_VALUE_FIELD = EvaluationConstants.RESULT_VALUE_FIELD;

	/**
	 * The field of type java.lang.Class on the code snippet instance that contains the type of the returned value.
	 * The name of the field (of type java.lang.Class) on the code
	 * snippet instance that contains the runtime type of the returned value.
	 */
	public static final String RESULT_TYPE_FIELD = EvaluationConstants.RESULT_TYPE_FIELD;

	/*
	 * REPORTING A PROBLEM OF COMPILATION IN THE CODE SNIPPET
	 */

	/**
	 * Indicates a compilation problem related to a global variable.
	 * 
	 * Note: if the problem is on the type of the variable, the marker
	 * source line number is -1; if the name of the variable, line number is 0;
	 * otherwise, the marker source line number is relative to the initializer
	 * code.
	 * 
	 *
	 * @see #acceptProblem(IMarker, String, int)
	 */
	public static final int VARIABLE = 1;

	/**
	 * Indicates a compilation problem related to a code snippet.
	 *
	 * @see #acceptProblem(IMarker, String, int)
	 */
	public static final int CODE_SNIPPET = 2;

	/**
	 * Indicates a compilation problem related to an import declaration.
	 *
	 * @see #acceptProblem(IMarker, String, int)
	 */
	public static final int IMPORT = 3;

	/**
	 * Indicates a compilation problem related to a package declaration.
	 *
	 * @see #acceptProblem(IMarker, String, int)
	 */
	public static final int PACKAGE = 4;

	/**
	 * Indicates an internal problem.
	 *
	 * @see #acceptProblem(IMarker, String, int)
	 */
	public static final int INTERNAL = 5;
/**
 * Sends the given class files to the target and loads them. If the given
 * class name is not null, run the code snippet with this class
 * name. Returns whether the code snippet could be deployed. Note it must
 * return true even if running the code snippet threw an exception.
 * 
 * The details of sending and loading the class files are left up to
 * implementations.
 * 
 * 
 * To run a code snippet, an implementation should create a new instance of
 * the given code snippet class and call (directly or using another means) its
 * RUN_METHOD.
 * 
 * 
 * Also before the call, the implementation should copy the values of the local
 * variables (if any) into the corresponding fields of the code snippet instance.
 * A field name is formed of LOCAL_VAR_PREFIX
 * preceded the name of the local variable. For example, the field name for
 * local variable "myLocal" is "val$myLocal" (assuming the
 * value of LOCAL_VAR_PREFIX is "val$"). In the
 * same way, the implementation should copy the value of the 'this' object into the
 * field called DELEGATE_THIS.
 * 
 * 
 * After calling the RUN_METHOD, the values of the local
 * variables may have been modified. The implementation must copy the
 * values of the fields back into the local variables.
 * 
 * 
 * Finally, the overall value returned by the code snippet can be retrieved
 * from the special field RESULT_VALUE_FIELD
 * on the code snippet instance.
 * The Class that is the runtime type of the returned value can be
 * retrieved from the special field RESULT_TYPE_FIELD.
 * 
 *
 * @param classFileBytes the list of class file bytes
 * @param classFileCompoundNames the corresponding list of class file type
 *   compound names (example of a compound name: {"java", "lang", "Object"})
 * @param codeSnippetClassName name of the actual class to instantiate and run,
 *   or null if none
 * @return true if the code snippet was successfully deployed
 */
public boolean acceptClassFiles(byte[][] classFileBytes, String[][] classFileCompoundNames, String codeSnippetClassName);
/**
 * Notifies of an evaluation problem.
 * Problems can arise for source of the following kinds:
 * 
 * 

 *   global variable (VARIABLE) - fragment source is name of
 *     variable
 *   code snippet (CODE_SNIPPET) - fragment source is code
 *     snippet
 *   import declaration (IMPORT) - fragment source is
 *     import
 *   package declaration (PACKAGE) - fragment source is
 *     package declaration
 *   other (INTERNAL) - no fragment source is involved, internal error occurred.
 * 
 * 
 * @param problemMarker the problem marker (cannot be null)
 * @param fragmentSource the fragment source
 * @param fragmentKind the kind of source fragment; one of:
 *   VARIABLE, CODE_SNIPPET, IMPORT,
 *   PACKAGE, or INTERNAL
 */
public void acceptProblem(IMarker problemMarker, String fragmentSource, int fragmentKind);
}