IAstEvaluationEngine


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.debug.eval;
12  
13   
14  import org.eclipse.debug.core.DebugException;
15  import org.eclipse.jdt.debug.core.IJavaObject;
16  import org.eclipse.jdt.debug.core.IJavaReferenceType;
17  import org.eclipse.jdt.debug.core.IJavaStackFrame;
18  import org.eclipse.jdt.debug.core.IJavaThread;
19  
20  /**
21   * An evaluation engine that performs evaluations by
22   * interpreting abstract syntax trees. An AST evaluation engine
23   * is capable of creating compiled expressions that can be
24   * evaluated multiple times in a given runtime context.
25   * <p>
26   * Clients are not intended to implement this interface.
27   * </p>
28   * @since 2.0
29   */ 
30  public interface IAstEvaluationEngine extends IEvaluationEngine {
31  
32      /**
33       * Asynchronously evaluates the given expression in the context of
34       * the specified stack frame, reporting the result back to the given listener.
35       * The thread is resumed from the location at which it
36       * is currently suspended to perform the evaluation. When the evaluation
37       * completes, the thread will be suspended at this original location.
38       * The thread runs the evaluation with the given evaluation detail
39       * (@see IJavaThread#runEvaluation(IEvaluationRunnable, IProgressMonitor, int)).
40       * Compilation and runtime errors are reported in the evaluation result.
41       * 
42       * @param expression expression to evaluate
43       * @param frame the stack frame context in which to run the
44       *   evaluation.
45       * @param listener the listener that will receive notification
46       *   when/if the evaluation completes
47       * @param evaluationDetail one of <code>DebugEvent.EVALUATION</code> or
48       *  <code>DebugEvent.EVALUATION_IMPLICIT</code>
49       * @param hitBreakpoints whether or not breakpoints should be honored
50       *  in the evaluation thread during the evaluation. If <code>false</code>,
51       *  breakpoints hit in the evaluation thread will be ignored.
52       * @exception DebugException if this method fails.  Reasons include:<ul>
53       * <li>Failure communicating with the VM.  The DebugException's
54       * status code contains the underlying exception responsible for
55       * the failure.</li>
56       * <li>The associated thread is not currently suspended</li>
57       * <li>The stack frame is not contained in the debug target
58       *   associated with this evaluation engine</li>
59       * <li>The associated thread is suspended in the middle of
60       *  an evaluation that has not completed. It is not possible
61       *  to perform nested evaluations</li>
62       * </ul>
63       */
64      public void evaluateExpression(ICompiledExpression expression, IJavaStackFrame frame, IEvaluationListener listener, int evaluationDetail, boolean hitBreakpoints) throws DebugException;
65  
66      /**
67       * Asynchronously evaluates the given expression in the context of
68       * the specified type, reporting the result back to the given listener.
69       * The expression is evaluated in the context of the Java
70       * project this evaluation engine was created on.  If the
71       * expression is determined to have no errors, the expression
72       * is evaluated in the thread associated with the given
73       * stack frame. When the evaluation completes, the thread
74       * will be suspended at this original location.
75       * The thread runs the evaluation with the given evaluation detail
76       * (@see IJavaThread#runEvaluation(IEvaluationRunnable, IProgressMonitor, int)).
77       * Compilation and runtime errors are reported in the evaluation result.
78       * 
79       * @param expression the expression to evaluate
80       * @param object the 'this' context for the evaluation
81       * @param thread the thread in which to run the evaluation,
82       *   which must be suspended
83       * @param listener the listener that will receive notification
84       *   when/if the evaluation completes
85       * @param evaluationDetail one of <code>DebugEvent.EVALUATION</code> or
86       *  <code>DebugEvent.EVALUATION_IMPLICIT</code>
87       * @param hitBreakpoints whether or not breakpoints should be honored
88       *  in the evaluation thread during the evaluation. If <code>false</code>,
89       *  breakpoints hit in the evaluation thread will be ignored.
90       * @exception DebugException if this method fails.  Reasons include:<ul>
91       * <li>Failure communicating with the VM.  The DebugException's
92       * status code contains the underlying exception responsible for
93       * the failure.</li>
94       * <li>The associated thread is not currently suspended</li>
95       * <li>The stack frame is not contained in the debug target
96       *   associated with this evaluation engine</li>
97       * <li>The associated thread is suspended in the middle of
98       *  an evaluation that has not completed. It is not possible
99       *  to perform nested evaluations</li>
100      * </ul>
101      */
102     public void evaluateExpression(ICompiledExpression expression, IJavaObject object, IJavaThread thread, IEvaluationListener listener, int evaluationDetail, boolean hitBreakpoints) throws DebugException;
103 
104     /**
105      * Synchronously generates a compiled expression from the given expression
106      * in the context of the specified stack frame. The generated expression
107      * can be stored and evaluated later in a valid runtime context.
108      * Compilation errors are reported in the returned compiled expression.
109      * 
110      * @param expression expression to compile
111      * @param frame the context in which to compile the expression
112      * @exception DebugException if this method fails. Reasons include:<ul>
113      * <li>Failure communicating with the VM.  The DebugException's
114      * status code contains the underlying exception responsible for
115      * the failure.</li>
116      * <li>The associated thread is not currently suspended</li>
117      * <li>The stack frame is not contained in the debug target
118      *   associated with this evaluation engine</li>
119      * </ul>
120      */
121     public ICompiledExpression getCompiledExpression(String   expression, IJavaStackFrame frame) throws DebugException;
122     
123     /**
124      * Synchronously generates a compiled expression from the given expression
125      * in the context of the specified object. The generated expression
126      * can be stored and evaluated later in a valid runtime context.
127      * Compilation errors are reported in the returned compiled expression.
128      * 
129      * @param expression expression to compile
130      * @param object the context in which to compile the expression
131      * @exception DebugException if this method fails. Reasons include:<ul>
132      * <li>Failure communicating with the VM.  The DebugException's
133      * status code contains the underlying exception responsible for
134      * the failure.</li>
135      * <li>The associated thread is not currently suspended</li>
136      * <li>The stack frame is not contained in the debug target
137      *   associated with this evaluation engine</li>
138      * </ul>
139      */
140     public ICompiledExpression getCompiledExpression(String   expression, IJavaObject object) throws DebugException;
141 
142     /**
143      * Synchronously generates a compiled expression from the given expression
144      * in the context of the specified type. The generated expression
145      * can be stored and evaluated later in a valid runtime context.
146      * Compilation errors are reported in the returned compiled expression.
147      * 
148      * @param expression expression to compile
149      * @param type the context in which to compile the expression
150      * @exception DebugException if this method fails. Reasons include:<ul>
151      * <li>Failure communicating with the VM.  The DebugException's
152      * status code contains the underlying exception responsible for
153      * the failure.</li>
154      * <li>The associated thread is not currently suspended</li>
155      * <li>The stack frame is not contained in the debug target
156      *   associated with this evaluation engine</li>
157      * </ul>
158      * @since 3.1
159      */
160     public ICompiledExpression getCompiledExpression(String   expression, IJavaReferenceType type) throws DebugException;
161 
162     
163 }
164 
165
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags