org.eclipse.jdt/org.eclipse.jdt.core/3.20.0 : org/eclipse/jdt/core/eval/ICodeSnippetRequestor.java

ICodeSnippetRequestor
http://www.eclipse.org/jdt: Java Development Tools Core (Eclipse Foundation)
Eclipse Public License - v 2.0
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
/*******************************************************************************
 * 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.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 Also: evaluateCodeSnippet.evaluateCodeSnippet(String, ICodeSnippetRequestor, IProgressMonitor)
IEvaluationContext.evaluateCodeSnippet(String, String[], String[], int[], IType, boolean, boolean, ICodeSnippetRequestor, IProgressMonitor)/**
 * 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.
 * <p>
 * Clients may implement this interface to provide a bridge a running Java VM.
 * </p>
 *
 * @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.
/**
	 * 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.
/**
	 * 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.
/**
	 * 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.
/**
	 * The name of the field (of type <code>java.lang.Object</code>) 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.
/**
	 * 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 <code>java.lang.Class</code>) 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 Also: acceptProblem(IMarker, String, int)/**
	 * Indicates a compilation problem related to a global variable.
	 * <p>
	 * 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.
	 * </p>
	 *
	 * @see #acceptProblem(IMarker, String, int)
	 */
	public static final int VARIABLE = 1;

	Indicates a compilation problem related to a code snippet.
See Also: acceptProblem(IMarker, String, int)/**
	 * 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 Also: acceptProblem(IMarker, String, int)/**
	 * 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 Also: acceptProblem(IMarker, String, int)/**
	 * 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 Also: acceptProblem(IMarker, String, int)/**
	 * 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.

Params: classFileBytes – the list of class file bytes
classFileCompoundNames – the corresponding list of class file type
  compound names (example of a compound name: {"java", "lang", "Object"})
codeSnippetClassName – name of the actual class to instantiate and run,
  or null if none
Returns: true if the code snippet was successfully deployed/**
 * Sends the given class files to the target and loads them. If the given
 * class name is not <code>null</code>, run the code snippet with this class
 * name. Returns whether the code snippet could be deployed. Note it must
 * return <code>true</code> even if running the code snippet threw an exception.
 * <p>
 * The details of sending and loading the class files are left up to
 * implementations.
 * </p>
 * <p>
 * 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
 * <code>RUN_METHOD</code>.
 * </p>
 * <p>
 * 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 <code>LOCAL_VAR_PREFIX</code>
 * preceded the name of the local variable. For example, the field name for
 * local variable <code>"myLocal"</code> is <code>"val$myLocal"</code> (assuming the
 * value of <code>LOCAL_VAR_PREFIX</code> is "val$"). In the
 * same way, the implementation should copy the value of the 'this' object into the
 * field called <code>DELEGATE_THIS</code>.
 * </p>
 * <p>
 * After calling the <code>RUN_METHOD</code>, the values of the local
 * variables may have been modified. The implementation must copy the
 * values of the fields back into the local variables.
 * </p>
 * <p>
 * Finally, the overall value returned by the code snippet can be retrieved
 * from the special field <code>RESULT_VALUE_FIELD</code>
 * on the code snippet instance.
 * The <code>Class</code> that is the runtime type of the returned value can be
 * retrieved from the special field <code>RESULT_TYPE_FIELD</code>.
 * </p>
 *
 * @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 <code>null</code> if none
 * @return <code>true</code> 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.

Params: problemMarker – the problem marker (cannot be null)
fragmentSource – the fragment source
fragmentKind – the kind of source fragment; one of:
  VARIABLE, CODE_SNIPPET, IMPORT,
  PACKAGE, or INTERNAL/**
 * Notifies of an evaluation problem.
 * Problems can arise for source of the following kinds:
 * <ul>
 *   <li>global variable (<code>VARIABLE</code>) - fragment source is name of
 *     variable</li>
 *   <li>code snippet (<code>CODE_SNIPPET</code>) - fragment source is code
 *     snippet</li>
 *   <li>import declaration (<code>IMPORT</code>) - fragment source is
 *     import</li>
 *   <li>package declaration (<code>PACKAGE</code>) - fragment source is
 *     package declaration</li>
 *   <li>other (<code>INTERNAL</code>) - no fragment source is involved, internal error occurred.</li>
 * </ul>
 * @param problemMarker the problem marker (cannot be null)
 * @param fragmentSource the fragment source
 * @param fragmentKind the kind of source fragment; one of:
 *   <code>VARIABLE</code>, <code>CODE_SNIPPET</code>, <code>IMPORT</code>,
 *   <code>PACKAGE</code>, or <code>INTERNAL</code>
 */
public void acceptProblem(IMarker problemMarker, String fragmentSource, int fragmentKind);
}
Params:	classFileBytes – the list of class file bytes classFileCompoundNames – the corresponding list of class file type compound names (example of a compound name: {"java", "lang", "Object"}) codeSnippetClassName – name of the actual class to instantiate and run, or `null` if none
Returns:	`true` if the code snippet was successfully deployed
/

org.eclipse.jdt/ org.eclipse.jdt.core/ 3.20.0/ org/eclipse/jdt/core/eval/ICodeSnippetRequestor.java
