KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdt > debug > eval > IEvaluationEngine


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.core.IJavaProject;
16 import org.eclipse.jdt.debug.core.IJavaDebugTarget;
17 import org.eclipse.jdt.debug.core.IJavaObject;
18 import org.eclipse.jdt.debug.core.IJavaStackFrame;
19 import org.eclipse.jdt.debug.core.IJavaThread;
20
21 /**
22  * An evaluation engine performs an evaluation of a
23  * code snippet or expression in a specified thread of a debug target.
24  * An evaluation engine is associated with a specific
25  * debug target and Java project on creation.
26  * <p>
27  * Clients are not intended to implement this interface.
28  * </p>
29  * @see IEvaluationResult
30  * @see IEvaluationListener
31  * @since 2.0
32  */

33
34 public interface IEvaluationEngine {
35     /**
36      * Asynchronously evaluates the given snippet in the context of
37      * the specified stack frame, reporting the result back to the given listener.
38      * The snippet is evaluated in the context of the Java
39      * project this evaluation engine was created on. If the
40      * snippet is determined to be a valid expression, the expression
41      * is evaluated in the thread associated with the given
42      * stack frame. The thread is resumed from the location at which it
43      * is currently suspended to perform the evaluation. When the evaluation
44      * completes, the thread will be suspended at this original location.
45      * The thread runs the evaluation with the given evaluation detail
46      * (@see IJavaThread#runEvaluation(IEvaluationRunnable, IProgressMonitor, int)).
47      * Compilation and runtime errors are reported in the evaluation result.
48      *
49      * @param snippet code snippet to evaluate
50      * @param frame the stack frame context in which to run the
51      * evaluation.
52      * @param listener the listener that will receive notification
53      * when/if the evaluation completes
54      * @param evaluationDetail one of <code>DebugEvent.EVALUATION</code> or
55      * <code>DebugEvent.EVALUATION_IMPLICIT</code>
56      * @param hitBreakpoints whether or not breakpoints should be honored
57      * in the evaluation thread during the evaluation. If <code>false</code>,
58      * breakpoints hit in the evaluation thread will be ignored.
59      * @exception DebugException if this method fails. Reasons include:<ul>
60      * <li>Failure communicating with the VM. The DebugException's
61      * status code contains the underlying exception responsible for
62      * the failure.</li>
63      * <li>The associated thread is not currently suspended</li>
64      * <li>The stack frame is not contained in the debug target
65      * associated with this evaluation engine</li>
66      * <li>The associated thread is suspended in the middle of
67      * an evaluation that has not completed. It is not possible
68      * to perform nested evaluations</li>
69      * </ul>
70      */

71     public void evaluate(String JavaDoc snippet, IJavaStackFrame frame, IEvaluationListener listener, int evaluationDetail, boolean hitBreakpoints) throws DebugException;
72     /**
73      * Asynchronously evaluates the given snippet in the context of
74      * the specified type, reporting the result back to the given listener.
75      * The snippet is evaluated in the context of the Java
76      * project this evaluation engine was created on. If the
77      * snippet is determined to be a valid expression, the expression
78      * is evaluated in the thread associated with the given
79      * stack frame. The thread is resumed from the location at which it
80      * is currently suspended to perform the evaluation. When the evaluation
81      * completes, the thread will be suspended at this original location.
82      * The thread runs the evaluation with the given evaluation detail
83      * (@see IJavaThread#runEvaluation(IEvaluationRunnable, IProgressMonitor, int)).
84      * Compilation and runtime errors are reported in the evaluation result.
85      *
86      * @param snippet code snippet to evaluate
87      * @param thisContext the 'this' context for the evaluation
88      * @param thread the thread in which to run the evaluation,
89      * which must be suspended
90      * @param listener the listener that will receive notification
91      * when/if the evaluation completes
92      * @param evaluationDetail one of <code>DebugEvent.EVALUATION</code> or
93      * <code>DebugEvent.EVALUATION_IMPLICIT</code>
94      * @param hitBreakpoints whether or not breakpoints should be honored
95      * in the evaluation thread during the evaluation. If <code>false</code>,
96      * breakpoints hit in the evaluation thread will be ignored.
97      * @exception DebugException if this method fails. Reasons include:<ul>
98      * <li>Failure communicating with the VM. The DebugException's
99      * status code contains the underlying exception responsible for
100      * the failure.</li>
101      * <li>The associated thread is not currently suspended</li>
102      * <li>The specified thread is not contained in the debug target
103      * associated with this evaluation engine</li>
104      * <li>The associated thread is suspended in the middle of
105      * an evaluation that has not completed. It is not possible
106      * to perform nested evaluations</li>
107      * </ul>
108      */

109     public void evaluate(String JavaDoc snippet, IJavaObject thisContext, IJavaThread thread, IEvaluationListener listener, int evaluationDetail, boolean hitBreakpoints) throws DebugException;
110
111     /**
112      * Returns the Java project in which expressions are
113      * compiled.
114      *
115      * @return Java project context
116      */

117     public IJavaProject getJavaProject();
118     
119     /**
120      * Returns the debug target for which evaluations
121      * are executed.
122      *
123      * @return Java debug target
124      */

125     public IJavaDebugTarget getDebugTarget();
126     
127     /**
128      * Disposes this evaluation engine. This causes the evaluation engine
129      * to cleanup any resources (such as threads) that it maintains. Clients
130      * should call this method when they are finished performing evaluations
131      * with this engine.
132      *
133      * This engine must not be used to perform evaluations after it has been disposed.
134      */

135     public void dispose();
136     
137 }
138
139
Popular Tags