001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.debug.eval;
011:
012: import org.eclipse.debug.core.DebugException;
013: import org.eclipse.jdt.core.IJavaProject;
014: import org.eclipse.jdt.debug.core.IJavaDebugTarget;
015: import org.eclipse.jdt.debug.core.IJavaObject;
016: import org.eclipse.jdt.debug.core.IJavaStackFrame;
017: import org.eclipse.jdt.debug.core.IJavaThread;
018:
019: /**
020: * An evaluation engine performs an evaluation of a
021: * code snippet or expression in a specified thread of a debug target.
022: * An evaluation engine is associated with a specific
023: * debug target and Java project on creation.
024: * <p>
025: * Clients are not intended to implement this interface.
026: * </p>
027: * @see IEvaluationResult
028: * @see IEvaluationListener
029: * @since 2.0
030: */
031:
032: public interface IEvaluationEngine {
033: /**
034: * Asynchronously evaluates the given snippet in the context of
035: * the specified stack frame, reporting the result back to the given listener.
036: * The snippet is evaluated in the context of the Java
037: * project this evaluation engine was created on. If the
038: * snippet is determined to be a valid expression, the expression
039: * is evaluated in the thread associated with the given
040: * stack frame. The thread is resumed from the location at which it
041: * is currently suspended to perform the evaluation. When the evaluation
042: * completes, the thread will be suspended at this original location.
043: * The thread runs the evaluation with the given evaluation detail
044: * (@see IJavaThread#runEvaluation(IEvaluationRunnable, IProgressMonitor, int)).
045: * Compilation and runtime errors are reported in the evaluation result.
046: *
047: * @param snippet code snippet to evaluate
048: * @param frame the stack frame context in which to run the
049: * evaluation.
050: * @param listener the listener that will receive notification
051: * when/if the evaluation completes
052: * @param evaluationDetail one of <code>DebugEvent.EVALUATION</code> or
053: * <code>DebugEvent.EVALUATION_IMPLICIT</code>
054: * @param hitBreakpoints whether or not breakpoints should be honored
055: * in the evaluation thread during the evaluation. If <code>false</code>,
056: * breakpoints hit in the evaluation thread will be ignored.
057: * @exception DebugException if this method fails. Reasons include:<ul>
058: * <li>Failure communicating with the VM. The DebugException's
059: * status code contains the underlying exception responsible for
060: * the failure.</li>
061: * <li>The associated thread is not currently suspended</li>
062: * <li>The stack frame is not contained in the debug target
063: * associated with this evaluation engine</li>
064: * <li>The associated thread is suspended in the middle of
065: * an evaluation that has not completed. It is not possible
066: * to perform nested evaluations</li>
067: * </ul>
068: */
069: public void evaluate(String snippet, IJavaStackFrame frame,
070: IEvaluationListener listener, int evaluationDetail,
071: boolean hitBreakpoints) throws DebugException;
072:
073: /**
074: * Asynchronously evaluates the given snippet in the context of
075: * the specified type, reporting the result back to the given listener.
076: * The snippet is evaluated in the context of the Java
077: * project this evaluation engine was created on. If the
078: * snippet is determined to be a valid expression, the expression
079: * is evaluated in the thread associated with the given
080: * stack frame. The thread is resumed from the location at which it
081: * is currently suspended to perform the evaluation. When the evaluation
082: * completes, the thread will be suspended at this original location.
083: * The thread runs the evaluation with the given evaluation detail
084: * (@see IJavaThread#runEvaluation(IEvaluationRunnable, IProgressMonitor, int)).
085: * Compilation and runtime errors are reported in the evaluation result.
086: *
087: * @param snippet code snippet to evaluate
088: * @param thisContext the 'this' context for the evaluation
089: * @param thread the thread in which to run the evaluation,
090: * which must be suspended
091: * @param listener the listener that will receive notification
092: * when/if the evaluation completes
093: * @param evaluationDetail one of <code>DebugEvent.EVALUATION</code> or
094: * <code>DebugEvent.EVALUATION_IMPLICIT</code>
095: * @param hitBreakpoints whether or not breakpoints should be honored
096: * in the evaluation thread during the evaluation. If <code>false</code>,
097: * breakpoints hit in the evaluation thread will be ignored.
098: * @exception DebugException if this method fails. Reasons include:<ul>
099: * <li>Failure communicating with the VM. The DebugException's
100: * status code contains the underlying exception responsible for
101: * the failure.</li>
102: * <li>The associated thread is not currently suspended</li>
103: * <li>The specified thread is not contained in the debug target
104: * associated with this evaluation engine</li>
105: * <li>The associated thread is suspended in the middle of
106: * an evaluation that has not completed. It is not possible
107: * to perform nested evaluations</li>
108: * </ul>
109: */
110: public void evaluate(String snippet, IJavaObject this Context,
111: IJavaThread thread, IEvaluationListener listener,
112: int evaluationDetail, boolean hitBreakpoints)
113: throws DebugException;
114:
115: /**
116: * Returns the Java project in which expressions are
117: * compiled.
118: *
119: * @return Java project context
120: */
121: public IJavaProject getJavaProject();
122:
123: /**
124: * Returns the debug target for which evaluations
125: * are executed.
126: *
127: * @return Java debug target
128: */
129: public IJavaDebugTarget getDebugTarget();
130:
131: /**
132: * Disposes this evaluation engine. This causes the evaluation engine
133: * to cleanup any resources (such as threads) that it maintains. Clients
134: * should call this method when they are finished performing evaluations
135: * with this engine.
136: *
137: * This engine must not be used to perform evaluations after it has been disposed.
138: */
139: public void dispose();
140:
141: }
|