001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.core.eval;
011:
012: import org.eclipse.core.resources.IMarker;
013: import org.eclipse.jdt.internal.eval.EvaluationConstants;
014:
015: /**
016: * A code snippet requestor implements a callback interface for installing
017: * the class files for a code snippet on the target and running it.
018: * In addition, it receives compilation problems detected during code snippet
019: * compilation.
020: * <p>
021: * Clients may implement this interface to provide a bridge a running Java VM.
022: * </p>
023: *
024: * @see IEvaluationContext#evaluateCodeSnippet(String, ICodeSnippetRequestor, org.eclipse.core.runtime.IProgressMonitor)
025: * @see IEvaluationContext#evaluateCodeSnippet(String, String[], String[], int[], org.eclipse.jdt.core.IType, boolean, boolean, ICodeSnippetRequestor, org.eclipse.core.runtime.IProgressMonitor)
026: */
027: public interface ICodeSnippetRequestor {
028:
029: /**
030: * The prefix of fields that represent the local variables in a snippet
031: * class.
032: */
033: public static final String LOCAL_VAR_PREFIX = new String(
034: EvaluationConstants.LOCAL_VAR_PREFIX);
035:
036: /**
037: * The name of the field that represent 'this' in a snippet class
038: * instance.
039: */
040: public static final String DELEGATE_THIS = new String(
041: EvaluationConstants.DELEGATE_THIS);
042:
043: /**
044: * The name of the instance method in the snippet class that runs the code
045: * snippet.
046: */
047: public static final String RUN_METHOD = EvaluationConstants.RUN_METHOD;
048:
049: /**
050: * The name of the field (of type <code>java.lang.Object</code>) on the code
051: * snippet instance that contains the returned value.
052: */
053: public static final String RESULT_VALUE_FIELD = EvaluationConstants.RESULT_VALUE_FIELD;
054:
055: /**
056: * The field of type java.lang.Class on the code snippet instance that contains the type of the returned value.
057: * The name of the field (of type <code>java.lang.Class</code>) on the code
058: * snippet instance that contains the runtime type of the returned value.
059: */
060: public static final String RESULT_TYPE_FIELD = EvaluationConstants.RESULT_TYPE_FIELD;
061:
062: /*
063: * REPORTING A PROBLEM OF COMPILATION IN THE CODE SNIPPET
064: */
065:
066: /**
067: * Indicates a compilation problem related to a global variable.
068: * <p>
069: * Note: if the problem is on the type of the variable, the marker
070: * source line number is -1; if the name of the variable, line number is 0;
071: * otherwise, the marker source line number is relative to the initializer
072: * code.
073: * </p>
074: *
075: * @see #acceptProblem(IMarker, String, int)
076: */
077: public static final int VARIABLE = 1;
078:
079: /**
080: * Indicates a compilation problem related to a code snippet.
081: *
082: * @see #acceptProblem(IMarker, String, int)
083: */
084: public static final int CODE_SNIPPET = 2;
085:
086: /**
087: * Indicates a compilation problem related to an import declaration.
088: *
089: * @see #acceptProblem(IMarker, String, int)
090: */
091: public static final int IMPORT = 3;
092:
093: /**
094: * Indicates a compilation problem related to a package declaration.
095: *
096: * @see #acceptProblem(IMarker, String, int)
097: */
098: public static final int PACKAGE = 4;
099:
100: /**
101: * Indicates an internal problem.
102: *
103: * @see #acceptProblem(IMarker, String, int)
104: */
105: public static final int INTERNAL = 5;
106:
107: /**
108: * Sends the given class files to the target and loads them. If the given
109: * class name is not <code>null</code>, run the code snippet with this class
110: * name. Returns whether the code snippet could be deployed. Note it must
111: * return <code>true</code> even if running the code snippet threw an exception.
112: * <p>
113: * The details of sending and loading the class files are left up to
114: * implementations.
115: * </p>
116: * <p>
117: * To run a code snippet, an implementation should create a new instance of
118: * the given code snippet class and call (directly or using another means) its
119: * <code>RUN_METHOD</code>.
120: * </p>
121: * <p>
122: * Also before the call, the implementation should copy the values of the local
123: * variables (if any) into the corresponding fields of the code snippet instance.
124: * A field name is formed of <code>LOCAL_VAR_PREFIX</code>
125: * preceded the name of the local variable. For example, the field name for
126: * local variable <code>"myLocal"</code> is <code>"val$myLocal"</code> (assuming the
127: * value of <code>LOCAL_VAR_PREFIX</code> is "val$"). In the
128: * same way, the implementation should copy the value of the 'this' object into the
129: * field called <code>DELEGATE_THIS</code>.
130: * </p>
131: * <p>
132: * After calling the <code>RUN_METHOD</code>, the values of the local
133: * variables may have been modified. The implementation must copy the
134: * values of the fields back into the local variables.
135: * </p>
136: * <p>
137: * Finally, the overall value returned by the code snippet can be retrieved
138: * from the special field <code>RESULT_VALUE_FIELD</code>
139: * on the code snippet instance.
140: * The <code>Class</code> that is the runtime type of the returned value can be
141: * retrieved from the special field <code>RESULT_TYPE_FIELD</code>.
142: * </p>
143: *
144: * @param classFileBytes the list of class file bytes
145: * @param classFileCompoundNames the corresponding list of class file type
146: * compound names (example of a compound name: {"java", "lang", "Object"})
147: * @param codeSnippetClassName name of the actual class to instantiate and run,
148: * or <code>null</code> if none
149: * @return <code>true</code> if the code snippet was successfully deployed
150: */
151: public boolean acceptClassFiles(byte[][] classFileBytes,
152: String[][] classFileCompoundNames,
153: String codeSnippetClassName);
154:
155: /**
156: * Notifies of an evaluation problem.
157: * Problems can arise for source of the following kinds:
158: * <p>
159: * <ul>
160: * <li>global variable (<code>VARIABLE</code>) - fragment source is name of
161: * variable</li>
162: * <li>code snippet (<code>CODE_SNIPPET</code>) - fragment source is code
163: * snippet</li>
164: * <li>import declaration (<code>IMPORT</code>) - fragment source is
165: * import</li>
166: * <li>package declaration (<code>PACKAGE</code>) - fragment source is
167: * package declaration</li>
168: * <li>other (<code>INTERNAL</code>) - no fragment source is involved, internal error occurred.</li>
169: * </ul>
170: * </p>
171: * @param problemMarker the problem marker (cannot be null)
172: * @param fragmentSource the fragment source
173: * @param fragmentKind the kind of source fragment; one of:
174: * <code>VARIABLE</code>, <code>CODE_SNIPPET</code>, <code>IMPORT</code>,
175: * <code>PACKAGE</code>, or <code>INTERNAL</code>
176: */
177: public void acceptProblem(IMarker problemMarker,
178: String fragmentSource, int fragmentKind);
179: }
|