IEvaluationContext


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jdt.core.eval;
12  
13  import org.eclipse.core.runtime.IProgressMonitor;
14  import org.eclipse.jdt.core.*;
15  import org.eclipse.jdt.core.IJavaElement;
16  import org.eclipse.jdt.core.IJavaProject;
17  import org.eclipse.jdt.core.IType;
18  import org.eclipse.jdt.core.JavaModelException;
19  
20  /**
21   * An evaluation context supports evaluating code snippets.
22   * <p>
23   * A code snippet is pretty much any valid piece of Java code that could be
24   * pasted into the body of a method and compiled. However, there are two 
25   * areas where the rules are slightly more liberal.
26   * <p>
27   * First, a code snippet can return heterogeneous types. Inside the same code
28   * snippet an <code>int</code> could be returned on one line, and a 
29   * <code>String</code> on the next, etc. For example, the following would be
30   * considered a valid code snippet:
31   * <pre>
32   * <code>
33   * char c = '3';
34   * switch (c) {
35   *   case '1': return 1;
36   *   case '2': return '2';
37   *   case '3': return "3";
38   *   default: return null;
39   * }
40   * </code>
41   * </pre>
42   * </p>
43   * <p>
44   * Second, if the last statement is only an expression, the <code>return</code> 
45   * keyword is implied. For example, the following returns <code>false</code>: 
46   * <pre>
47   * <code>
48   * int i = 1;
49   * i == 2
50   * </code>
51   * </pre>
52   * </p>
53   * <p>
54   * Global variables are an additional feature of evaluation contexts. Within an
55   * evaluation context, global variables maintain their value across evaluations.
56   * These variables are particularly useful for storing the result of an
57   * evaluation for use in subsequent evaluations.
58   * </p>
59   * <p>
60   * The evaluation context remembers the name of the package in which code
61   * snippets are run. The user can set this to any package, thereby gaining
62   * access to types that are normally only visible within that package.
63   * </p>
64   * <p>
65   * Finally, the evaluation context remembers a list of import declarations. The
66   * user can import any packages and types so that the code snippets may refer
67   * to types by their shorter simple names.
68   * </p>
69   * <p>
70   * Example of use:
71   * <pre>
72   * <code>
73   * IJavaProject project = getJavaProject();
74   * IEvaluationContext context = project.newEvaluationContext();
75   * String codeSnippet = "int i= 0; i++";
76   * ICodeSnippetRequestor requestor = ...;
77   * context.evaluateCodeSnippet(codeSnippet, requestor, progressMonitor);
78   * </code>
79   * </pre>
80   * </p>
81   * <p>
82   * This interface is not intended to be implemented by clients. 
83   * <code>IJavaProject.newEvaluationContext</code> can be used to obtain an
84   * instance.
85   * </p>
86   *
87   * @see IJavaProject#newEvaluationContext()
88   */
89  public interface IEvaluationContext {
90      /**
91       * Returns the global variables declared in this evaluation context.
92       * The variables are maintained in the order they are created in.
93       *
94       * @return the list of global variables
95       */
96      public IGlobalVariable[] allVariables();
97      /**
98       * Performs a code completion at the given position in the given code snippet,
99       * reporting results to the given completion requestor.
100      * <p>
101      * Note that code completion does not involve evaluation.
102      * <p>
103      *
104      * @param codeSnippet the code snippet to complete in
105      * @param position the character position in the code snippet to complete at,
106      *   or -1 indicating the beginning of the snippet
107      * @param requestor the code completion requestor capable of accepting all
108      *    possible types of completions
109      * @exception JavaModelException if code completion could not be performed. Reasons include:
110      *  <ul>
111      *    <li>The position specified is less than -1 or is greater than the snippet's
112      *      length (INDEX_OUT_OF_BOUNDS)</li>
113      *  </ul>
114      * @since 2.0
115      * @deprecated Use {@link #codeComplete(String,int,CompletionRequestor)} instead.
116      */
117     public void codeComplete(
118         String   codeSnippet,
119         int position,
120         ICompletionRequestor requestor)
121         throws JavaModelException;
122     /**
123      * Performs a code completion at the given position in the given code snippet,
124      * reporting results to the given completion requestor.
125      * It considers types in the working copies with the given owner first. In other words, 
126      * the owner's working copies will take precedence over their original compilation units
127      * in the workspace.
128      * <p>
129      * Note that if a working copy is empty, it will be as if the original compilation
130      * unit had been deleted.
131      * </p>
132      * <p>
133      * Note that code completion does not involve evaluation.
134      * <p>
135      *
136      * @param codeSnippet the code snippet to complete in
137      * @param position the character position in the code snippet to complete at,
138      *   or -1 indicating the beginning of the snippet
139      * @param requestor the code completion requestor capable of accepting all
140      *    possible types of completions
141      * @param owner the owner of working copies that take precedence over their original compilation units
142      * @exception JavaModelException if code completion could not be performed. Reasons include:
143      *  <ul>
144      *    <li>The position specified is less than -1 or is greater than the snippet's
145      *      length (INDEX_OUT_OF_BOUNDS)</li>
146      *  </ul>
147      * @since 3.0
148      * @deprecated Use {@link #codeComplete(String,int,CompletionRequestor,WorkingCopyOwner)} instead.
149      */
150     public void codeComplete(
151         String   codeSnippet,
152         int position,
153         ICompletionRequestor requestor,
154         WorkingCopyOwner owner)
155         throws JavaModelException;
156     /**
157      * Performs a code completion at the given position in the given code snippet,
158      * reporting results to the given completion requestor.
159      * <p>
160      * Note that code completion does not involve evaluation.
161      * <p>
162      *
163      * @param codeSnippet the code snippet to complete in
164      * @param position the character position in the code snippet to complete at,
165      *   or -1 indicating the beginning of the snippet
166      * @param requestor the code completion requestor capable of accepting all
167      *    possible types of completions
168      * @exception JavaModelException if code completion could not be performed. Reasons include:
169      *  <ul>
170      *    <li>The position specified is less than -1 or is greater than the snippet's
171      *      length (INDEX_OUT_OF_BOUNDS)</li>
172      *  </ul>
173      * @since 3.1
174      */
175     public void codeComplete(
176         String   codeSnippet,
177         int position,
178         CompletionRequestor requestor)
179         throws JavaModelException;
180     /**
181      * Performs a code completion at the given position in the given code snippet,
182      * reporting results to the given completion requestor.
183      * It considers types in the working copies with the given owner first. In other words, 
184      * the owner's working copies will take precedence over their original compilation units
185      * in the workspace.
186      * <p>
187      * Note that if a working copy is empty, it will be as if the original compilation
188      * unit had been deleted.
189      * </p>
190      * <p>
191      * Note that code completion does not involve evaluation.
192      * <p>
193      *
194      * @param codeSnippet the code snippet to complete in
195      * @param position the character position in the code snippet to complete at,
196      *   or -1 indicating the beginning of the snippet
197      * @param requestor the code completion requestor capable of accepting all
198      *    possible types of completions
199      * @param owner the owner of working copies that take precedence over their original compilation units
200      * @exception JavaModelException if code completion could not be performed. Reasons include:
201      *  <ul>
202      *    <li>The position specified is less than -1 or is greater than the snippet's
203      *      length (INDEX_OUT_OF_BOUNDS)</li>
204      *  </ul>
205      * @since 3.1
206      */
207     public void codeComplete(
208         String   codeSnippet,
209         int position,
210         CompletionRequestor requestor,
211         WorkingCopyOwner owner)
212         throws JavaModelException;
213     /**
214      * Resolves and returns a collection of Java elements corresponding to the source
215      * code at the given positions in the given code snippet.
216      * <p>
217      * Note that code select does not involve evaluation, and problems are never
218      * reported.
219      * <p>
220      *
221      * @param codeSnippet the code snippet to resolve in
222      * @param offset the position in the code snippet of the first character
223      *   of the code to resolve
224      * @param length the length of the selected code to resolve
225      * @return the (possibly empty) list of selection Java elements
226      * @exception JavaModelException if code resolve could not be performed.
227      *   Reasons include:
228      *   <ul>
229      *     <li>The position specified is less than -1 or is greater than the snippet's
230      *       length (INDEX_OUT_OF_BOUNDS)</li>
231      *   </ul>
232      */
233     public IJavaElement[] codeSelect(String   codeSnippet, int offset, int length)
234         throws JavaModelException;
235     /**
236      * Resolves and returns a collection of Java elements corresponding to the source
237      * code at the given positions in the given code snippet.
238      * It considers types in the working copies with the given owner first. In other words, 
239      * the owner's working copies will take precedence over their original compilation units
240      * in the workspace.
241      * <p>
242      * Note that if a working copy is empty, it will be as if the original compilation
243      * unit had been deleted.
244      * </p>
245      * <p>
246      * Note that code select does not involve evaluation, and problems are never
247      * reported.
248      * <p>
249      *
250      * @param codeSnippet the code snippet to resolve in
251      * @param offset the position in the code snippet of the first character
252      *   of the code to resolve
253      * @param length the length of the selected code to resolve
254      * @param owner the owner of working copies that take precedence over their original compilation units
255      * @return the (possibly empty) list of selection Java elements
256      * @exception JavaModelException if code resolve could not be performed.
257      *   Reasons include:
258      *   <ul>
259      *     <li>The position specified is less than -1 or is greater than the snippet's
260      *       length (INDEX_OUT_OF_BOUNDS)</li>
261      *   </ul>
262      * @since 3.0
263      */
264     public IJavaElement[] codeSelect(String   codeSnippet, int offset, int length, WorkingCopyOwner owner)
265         throws JavaModelException;
266     /**
267      * Deletes the given variable from this evaluation context. Does nothing if
268      * the given variable has already been deleted.
269      *
270      * @param variable the global variable
271      */
272     public void deleteVariable(IGlobalVariable variable);
273     /**
274      * Evaluates the given code snippet in the context of a suspended thread.
275      * The code snippet is compiled along with this context's package declaration,
276      * imports, and global variables. The given requestor's 
277      * <code>acceptProblem</code> method is called for each compilation problem that
278      * is detected. Then the resulting class files are handed to the given 
279      * requestor's <code>acceptClassFiles</code> method to deploy and run.
280      * <p>
281      * The requestor is expected to:
282      * <ol>
283      *   <li>send the class files to the target VM, 
284      *   <li>load them (starting with the code snippet class),
285      *   <li>create a new instance of the code snippet class,
286      *   <li>run the method <code>run()</code> of the code snippet,
287      *   <li>retrieve the values of the local variables,
288      *   <li>retrieve the returned value of the code snippet
289      * </ol>
290      * </p>
291      * <p>
292      * This method is long-running; progress and cancellation are provided
293      * by the given progress monitor.
294      * </p>
295      *
296      * @param codeSnippet the code snippet
297      * @param localVariableTypeNames the dot-separated fully qualified names of the types of the local variables.
298      * @param localVariableNames the names of the local variables as they are declared in the user's code.
299      * @param localVariableModifiers the modifiers of the local variables (default modifier or final modifier).
300      * @param declaringType the type in which the code snippet is evaluated.
301      * @param isStatic whether the code snippet is evaluated in a static member of the declaring type.
302      * @param isConstructorCall whether the code snippet is evaluated in a constructor of the declaring type.
303      * @param requestor the code snippet requestor
304      * @param progressMonitor a progress monitor
305      * @exception JavaModelException if a runtime problem occurred or if this
306      *   context's project has no build state
307      */
308     public void evaluateCodeSnippet(
309         String   codeSnippet,
310         String  [] localVariableTypeNames,
311         String  [] localVariableNames,
312         int[] localVariableModifiers,
313         IType declaringType,
314         boolean isStatic,
315         boolean isConstructorCall,
316         ICodeSnippetRequestor requestor,
317         IProgressMonitor progressMonitor)
318         throws JavaModelException;
319     /**
320      * Evaluates the given code snippet. The code snippet is
321      * compiled along with this context's package declaration, imports, and
322      * global variables. The given requestor's <code>acceptProblem</code> method
323      * is called for each compilation problem that is detected. Then the resulting
324      * class files are handed to the given requestor's <code>acceptClassFiles</code>
325      * method to deploy and run. The requestor is also responsible for getting the
326      * result back. 
327      * <p>
328      * This method is long-running; progress and cancellation are provided
329      * by the given progress monitor.
330      * </p>
331      *
332      * @param codeSnippet the code snippet
333      * @param requestor the code snippet requestor
334      * @param progressMonitor a progress monitor
335      * @exception JavaModelException if a runtime problem occurred or if this
336      *   context's project has no build state
337      */
338     public void evaluateCodeSnippet(
339         String   codeSnippet,
340         ICodeSnippetRequestor requestor,
341         IProgressMonitor progressMonitor)
342         throws JavaModelException;
343     /**
344      * Evaluates the given global variable. During this operation, 
345      * this context's package declaration, imports, and <i>all</i> its declared 
346      * variables are verified. The given requestor's <code>acceptProblem</code>
347      * method will be called for each problem that is detected.
348      * <p>
349      * This method is long-running; progress and cancellation are provided
350      * by the given progress monitor.
351      * </p>
352      *
353      * @param variable the global variable
354      * @param requestor the code snippet requestor
355      * @param progressMonitor a progress monitor
356      * @exception JavaModelException if a runtime problem occurred or if this
357      *   context's project has no build state
358      */
359     public void evaluateVariable(
360         IGlobalVariable variable,
361         ICodeSnippetRequestor requestor,
362         IProgressMonitor progressMonitor)
363         throws JavaModelException;
364     /**
365      * Returns the import declarations for this evaluation context. Returns and empty
366      * list if there are no imports (the default if the imports have never been set).
367      * The syntax for the import corresponds to a fully qualified type name, or to
368      * an on-demand package name as defined by ImportDeclaration (JLS2 7.5). For
369      * example, <code>"java.util.Hashtable"</code> or <code>"java.util.*"</code>.
370      *
371      * @return the list of import names
372      */
373     public String  [] getImports();
374     /**
375      * Returns the name of the package in which code snippets are to be compiled and
376      * run. Returns an empty string for the default package (the default if the
377      * package name has never been set). For example, <code>"com.example.myapp"</code>.
378      *
379      * @return the dot-separated package name, or the empty string indicating the
380      *   default package
381      */
382     public String   getPackageName();
383     /**
384      * Returns the Java project this evaluation context was created for.
385      *
386      * @return the Java project
387      */
388     public IJavaProject getProject();
389     /**
390      * Creates a new global variable with the given name, type, and initializer.
391      * <p>
392      * The <code>typeName</code> and <code>initializer</code> are interpreted in 
393      * the context of this context's package and import declarations.
394      * </p>
395     * <p>
396      * The syntax for a type name corresponds to Type in Field Declaration (JLS2 8.3).
397      * </p>
398      *
399      * @param typeName the type name
400      * @param name the name of the global variable
401      * @param initializer the initializer expression, or <code>null</code> if the
402      *   variable is not initialized
403      * @return a new global variable with the given name, type, and initializer
404      */
405     public IGlobalVariable newVariable(
406         String   typeName,
407         String   name,
408         String   initializer);
409     /**
410      * Sets the import declarations for this evaluation context. An empty
411      * list indicates there are no imports. The syntax for the import corresponds to a 
412      * fully qualified type name, or to an on-demand package name as defined by
413      * ImportDeclaration (JLS2 7.5). For example, <code>"java.util.Hashtable"</code>
414      * or <code>"java.util.*"</code>.
415      *
416      * @param imports the list of import names
417      */
418     public void setImports(String  [] imports);
419     /**
420      * Sets the dot-separated name of the package in which code snippets are 
421      * to be compiled and run. For example, <code>"com.example.myapp"</code>.
422      *
423      * @param packageName the dot-separated package name, or the empty string 
424      *   indicating the default package
425      */
426     public void setPackageName(String   packageName);
427     /**
428      * Validates this evaluation context's import declarations. The given requestor's
429      * <code>acceptProblem</code> method is called for each problem that is detected.
430      *
431      * @param requestor the code snippet requestor
432      * @exception JavaModelException if this context's project has no build state
433      */
434     public void validateImports(ICodeSnippetRequestor requestor)
435         throws JavaModelException;
436 
437     /**
438      * Performs a code completion at the given position in the given code snippet,
439      * reporting results to the given completion requestor.
440      * <p>
441      * Note that code completion does not involve evaluation.
442      * <p>
443      *
444      * @param codeSnippet the code snippet to complete in
445      * @param position the character position in the code snippet to complete at,
446      *   or -1 indicating the beginning of the snippet
447      * @param requestor the code completion requestor capable of accepting all
448      *    possible types of completions
449      * @exception JavaModelException if code completion could not be performed. Reasons include:
450      *  <ul>
451      *    <li>The position specified is less than -1 or is greater than the snippet's
452      *      length (INDEX_OUT_OF_BOUNDS)</li>
453      *  </ul>
454      * @deprecated - use codeComplete(String, int, ICompletionRequestor) instead
455      */
456     public void codeComplete(
457         String   codeSnippet,
458         int position,
459         org.eclipse.jdt.core.ICodeCompletionRequestor requestor)
460         throws JavaModelException;
461 
462 }
463
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags