KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdt > debug > eval > 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 JavaDoc 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 JavaDoc 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 JavaDoc expression, IJavaReferenceType type) throws DebugException;
161
162     
163 }
164
165
Popular Tags