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.debug.core.IJavaObject;
014: import org.eclipse.jdt.debug.core.IJavaReferenceType;
015: import org.eclipse.jdt.debug.core.IJavaStackFrame;
016: import org.eclipse.jdt.debug.core.IJavaThread;
017:
018: /**
019: * An evaluation engine that performs evaluations by
020: * interpreting abstract syntax trees. An AST evaluation engine
021: * is capable of creating compiled expressions that can be
022: * evaluated multiple times in a given runtime context.
023: * <p>
024: * Clients are not intended to implement this interface.
025: * </p>
026: * @since 2.0
027: */
028: public interface IAstEvaluationEngine extends IEvaluationEngine {
029:
030: /**
031: * Asynchronously evaluates the given expression in the context of
032: * the specified stack frame, reporting the result back to the given listener.
033: * The thread is resumed from the location at which it
034: * is currently suspended to perform the evaluation. When the evaluation
035: * completes, the thread will be suspended at this original location.
036: * The thread runs the evaluation with the given evaluation detail
037: * (@see IJavaThread#runEvaluation(IEvaluationRunnable, IProgressMonitor, int)).
038: * Compilation and runtime errors are reported in the evaluation result.
039: *
040: * @param expression expression to evaluate
041: * @param frame the stack frame context in which to run the
042: * evaluation.
043: * @param listener the listener that will receive notification
044: * when/if the evaluation completes
045: * @param evaluationDetail one of <code>DebugEvent.EVALUATION</code> or
046: * <code>DebugEvent.EVALUATION_IMPLICIT</code>
047: * @param hitBreakpoints whether or not breakpoints should be honored
048: * in the evaluation thread during the evaluation. If <code>false</code>,
049: * breakpoints hit in the evaluation thread will be ignored.
050: * @exception DebugException if this method fails. Reasons include:<ul>
051: * <li>Failure communicating with the VM. The DebugException's
052: * status code contains the underlying exception responsible for
053: * the failure.</li>
054: * <li>The associated thread is not currently suspended</li>
055: * <li>The stack frame is not contained in the debug target
056: * associated with this evaluation engine</li>
057: * <li>The associated thread is suspended in the middle of
058: * an evaluation that has not completed. It is not possible
059: * to perform nested evaluations</li>
060: * </ul>
061: */
062: public void evaluateExpression(ICompiledExpression expression,
063: IJavaStackFrame frame, IEvaluationListener listener,
064: int evaluationDetail, boolean hitBreakpoints)
065: throws DebugException;
066:
067: /**
068: * Asynchronously evaluates the given expression in the context of
069: * the specified type, reporting the result back to the given listener.
070: * The expression is evaluated in the context of the Java
071: * project this evaluation engine was created on. If the
072: * expression is determined to have no errors, the expression
073: * is evaluated in the thread associated with the given
074: * stack frame. When the evaluation completes, the thread
075: * will be suspended at this original location.
076: * The thread runs the evaluation with the given evaluation detail
077: * (@see IJavaThread#runEvaluation(IEvaluationRunnable, IProgressMonitor, int)).
078: * Compilation and runtime errors are reported in the evaluation result.
079: *
080: * @param expression the expression to evaluate
081: * @param object the 'this' context for the evaluation
082: * @param thread the thread in which to run the evaluation,
083: * which must be suspended
084: * @param listener the listener that will receive notification
085: * when/if the evaluation completes
086: * @param evaluationDetail one of <code>DebugEvent.EVALUATION</code> or
087: * <code>DebugEvent.EVALUATION_IMPLICIT</code>
088: * @param hitBreakpoints whether or not breakpoints should be honored
089: * in the evaluation thread during the evaluation. If <code>false</code>,
090: * breakpoints hit in the evaluation thread will be ignored.
091: * @exception DebugException if this method fails. Reasons include:<ul>
092: * <li>Failure communicating with the VM. The DebugException's
093: * status code contains the underlying exception responsible for
094: * the failure.</li>
095: * <li>The associated thread is not currently suspended</li>
096: * <li>The stack frame is not contained in the debug target
097: * associated with this evaluation engine</li>
098: * <li>The associated thread is suspended in the middle of
099: * an evaluation that has not completed. It is not possible
100: * to perform nested evaluations</li>
101: * </ul>
102: */
103: public void evaluateExpression(ICompiledExpression expression,
104: IJavaObject object, IJavaThread thread,
105: IEvaluationListener listener, int evaluationDetail,
106: boolean hitBreakpoints) throws DebugException;
107:
108: /**
109: * Synchronously generates a compiled expression from the given expression
110: * in the context of the specified stack frame. The generated expression
111: * can be stored and evaluated later in a valid runtime context.
112: * Compilation errors are reported in the returned compiled expression.
113: *
114: * @param expression expression to compile
115: * @param frame the context in which to compile the expression
116: * @exception DebugException if this method fails. Reasons include:<ul>
117: * <li>Failure communicating with the VM. The DebugException's
118: * status code contains the underlying exception responsible for
119: * the failure.</li>
120: * <li>The associated thread is not currently suspended</li>
121: * <li>The stack frame is not contained in the debug target
122: * associated with this evaluation engine</li>
123: * </ul>
124: */
125: public ICompiledExpression getCompiledExpression(String expression,
126: IJavaStackFrame frame) throws DebugException;
127:
128: /**
129: * Synchronously generates a compiled expression from the given expression
130: * in the context of the specified object. The generated expression
131: * can be stored and evaluated later in a valid runtime context.
132: * Compilation errors are reported in the returned compiled expression.
133: *
134: * @param expression expression to compile
135: * @param object the context in which to compile the expression
136: * @exception DebugException if this method fails. Reasons include:<ul>
137: * <li>Failure communicating with the VM. The DebugException's
138: * status code contains the underlying exception responsible for
139: * the failure.</li>
140: * <li>The associated thread is not currently suspended</li>
141: * <li>The stack frame is not contained in the debug target
142: * associated with this evaluation engine</li>
143: * </ul>
144: */
145: public ICompiledExpression getCompiledExpression(String expression,
146: IJavaObject object) throws DebugException;
147:
148: /**
149: * Synchronously generates a compiled expression from the given expression
150: * in the context of the specified type. The generated expression
151: * can be stored and evaluated later in a valid runtime context.
152: * Compilation errors are reported in the returned compiled expression.
153: *
154: * @param expression expression to compile
155: * @param type the context in which to compile the expression
156: * @exception DebugException if this method fails. Reasons include:<ul>
157: * <li>Failure communicating with the VM. The DebugException's
158: * status code contains the underlying exception responsible for
159: * the failure.</li>
160: * <li>The associated thread is not currently suspended</li>
161: * <li>The stack frame is not contained in the debug target
162: * associated with this evaluation engine</li>
163: * </ul>
164: * @since 3.1
165: */
166: public ICompiledExpression getCompiledExpression(String expression,
167: IJavaReferenceType type) throws DebugException;
168:
169: }
|