ICodeSnippetRequestor


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.resources.IMarker;
14  import org.eclipse.jdt.internal.eval.EvaluationConstants;
15  
16  /**
17   * A code snippet requestor implements a callback interface for installing 
18   * the class files for a code snippet on the target and running it. 
19   * In addition, it receives compilation problems detected during code snippet
20   * compilation.
21   * <p>
22   * Clients may implement this interface to provide a bridge a running Java VM.
23   * </p>
24   *
25   * @see IEvaluationContext#evaluateCodeSnippet(String, ICodeSnippetRequestor, org.eclipse.core.runtime.IProgressMonitor)
26   * @see IEvaluationContext#evaluateCodeSnippet(String, String[], String[], int[], org.eclipse.jdt.core.IType, boolean, boolean, ICodeSnippetRequestor, org.eclipse.core.runtime.IProgressMonitor)
27   */
28  public interface ICodeSnippetRequestor {
29      
30      /**
31       * The prefix of fields that represent the local variables in a snippet
32       * class.
33       */
34      public static final String   LOCAL_VAR_PREFIX = new String  (EvaluationConstants.LOCAL_VAR_PREFIX);
35  
36      /**
37       * The name of the field that represent 'this' in a snippet class
38       * instance.
39       */
40      public static final String   DELEGATE_THIS = new String  (EvaluationConstants.DELEGATE_THIS);
41  
42      /** 
43       * The name of the instance method in the snippet class that runs the code 
44       * snippet.
45       */
46      public static final String   RUN_METHOD = EvaluationConstants.RUN_METHOD;
47  
48      /**
49       * The name of the field (of type <code>java.lang.Object</code>) on the code 
50       * snippet instance that contains the returned value.
51       */
52      public static final String   RESULT_VALUE_FIELD = EvaluationConstants.RESULT_VALUE_FIELD;
53  
54      /**
55       * The field of type java.lang.Class on the code snippet instance that contains the type of the returned value.
56       * The name of the field (of type <code>java.lang.Class</code>) on the code 
57       * snippet instance that contains the runtime type of the returned value.
58       */
59      public static final String   RESULT_TYPE_FIELD = EvaluationConstants.RESULT_TYPE_FIELD;
60  
61      /*
62       * REPORTING A PROBLEM OF COMPILATION IN THE CODE SNIPPET
63       */
64       
65      /**
66       * Indicates a compilation problem related to a global variable.
67       * <p>
68       * Note: if the problem is on the type of the variable, the marker
69       * source line number is -1; if the name of the variable, line number is 0;
70       * otherwise, the marker source line number is relative to the initializer 
71       * code.
72       * </p>
73       *
74       * @see #acceptProblem(IMarker, String, int)
75       */
76      public static final int VARIABLE = 1;
77  
78      /**
79       * Indicates a compilation problem related to a code snippet.
80       *
81       * @see #acceptProblem(IMarker, String, int)
82       */
83      public static final int CODE_SNIPPET = 2;
84  
85      /**
86       * Indicates a compilation problem related to an import declaration.
87       *
88       * @see #acceptProblem(IMarker, String, int)
89       */
90      public static final int IMPORT = 3;
91  
92      /**
93       * Indicates a compilation problem related to a package declaration.
94       *
95       * @see #acceptProblem(IMarker, String, int)
96       */
97      public static final int PACKAGE = 4;
98  
99      /**
100      * Indicates an internal problem.
101      *
102      * @see #acceptProblem(IMarker, String, int)
103      */
104     public static final int INTERNAL = 5;       
105 /**
106  * Sends the given class files to the target and loads them. If the given
107  * class name is not <code>null</code>, run the code snippet with this class
108  * name. Returns whether the code snippet could be deployed. Note it must 
109  * return <code>true</code> even if running the code snippet threw an exception.
110  * <p>
111  * The details of sending and loading the class files are left up to 
112  * implementations.
113  * </p>
114  * <p>
115  * To run a code snippet, an implementation should create a new instance of 
116  * the given code snippet class and call (directly or using another means) its 
117  * <code>RUN_METHOD</code>.
118  * </p>
119  * <p>
120  * Also before the call, the implementation should copy the values of the local 
121  * variables (if any) into the corresponding fields of the code snippet instance. 
122  * A field name is formed of <code>LOCAL_VAR_PREFIX</code> 
123  * preceded the name of the local variable. For example, the field name for 
124  * local variable <code>"myLocal"</code> is <code>"val$myLocal"</code> (assuming the 
125  * value of <code>LOCAL_VAR_PREFIX</code> is "val$"). In the 
126  * same way, the implementation should copy the value of the 'this' object into the 
127  * field called <code>DELEGATE_THIS</code>.
128  * </p>
129  * <p>
130  * After calling the <code>RUN_METHOD</code>, the values of the local
131  * variables may have been modified. The implementation must copy the
132  * values of the fields back into the local variables.
133  * </p>
134  * <p>
135  * Finally, the overall value returned by the code snippet can be retrieved 
136  * from the special field <code>RESULT_VALUE_FIELD</code> 
137  * on the code snippet instance. 
138  * The <code>Class</code> that is the runtime type of the returned value can be
139  * retrieved from the special field <code>RESULT_TYPE_FIELD</code>.
140  * </p>
141  *
142  * @param classFileBytes the list of class file bytes
143  * @param classFileCompoundNames the corresponding list of class file type 
144  *   compound names (example of a compound name: {"java", "lang", "Object"})
145  * @param codeSnippetClassName name of the actual class to instantiate and run,
146  *   or <code>null</code> if none
147  * @return <code>true</code> if the code snippet was successfully deployed
148  */
149 public boolean acceptClassFiles(byte[][] classFileBytes, String  [][] classFileCompoundNames, String   codeSnippetClassName);
150 /**
151  * Notifies of an evaluation problem.
152  * Problems can arise for source of the following kinds:
153  * <p>
154  * <ul>
155  *   <li>global variable (<code>VARIABLE</code>) - fragment source is name of
156  *     variable</li>
157  *   <li>code snippet (<code>CODE_SNIPPET</code>) - fragment source is code
158  *     snippet</li>
159  *   <li>import declaration (<code>IMPORT</code>) - fragment source is 
160  *     import</li>
161  *   <li>package declaration (<code>PACKAGE</code>) - fragment source is
162  *     package declaration</li>
163  *   <li>other (<code>INTERNAL</code>) - no fragment source is involved, internal error occurred.</li>
164  * </ul>
165  * </p>
166  * @param problemMarker the problem marker (cannot be null)
167  * @param fragmentSource the fragment source
168  * @param fragmentKind the kind of source fragment; one of: 
169  *   <code>VARIABLE</code>, <code>CODE_SNIPPET</code>, <code>IMPORT</code>,
170  *   <code>PACKAGE</code>, or <code>INTERNAL</code>
171  */
172 public void acceptProblem(IMarker problemMarker, String   fragmentSource, int fragmentKind);
173 }
174
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags