/*******************************************************************************
* Copyright (c) 2000, 2011 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.jdt.debug.eval;
import org.eclipse.debug.core.DebugException;
import org.eclipse.jdt.debug.core.IJavaObject;
import org.eclipse.jdt.debug.core.IJavaReferenceType;
import org.eclipse.jdt.debug.core.IJavaStackFrame;
import org.eclipse.jdt.debug.core.IJavaThread;
/**
* An evaluation engine that performs evaluations by interpreting abstract
* syntax trees. An AST evaluation engine is capable of creating compiled
* expressions that can be evaluated multiple times in a given runtime context.
*
* @since 2.0
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface IAstEvaluationEngine extends IEvaluationEngine {
/**
* Asynchronously evaluates the given expression in the context of the
* specified stack frame, reporting the result back to the given listener.
* The thread is resumed from the location at which it is currently
* suspended to perform the evaluation. When the evaluation completes, the
* thread will be suspended at this original location. The thread runs the
* evaluation with the given evaluation detail (@see
* IJavaThread#runEvaluation(IEvaluationRunnable, IProgressMonitor, int)).
* Compilation and runtime errors are reported in the evaluation result.
*
* @param expression
* expression to evaluate
* @param frame
* the stack frame context in which to run the evaluation.
* @param listener
* the listener that will receive notification when/if the
* evaluation completes
* @param evaluationDetail
* one of <code>DebugEvent.EVALUATION</code> or
* <code>DebugEvent.EVALUATION_IMPLICIT</code>
* @param hitBreakpoints
* whether or not breakpoints should be honored in the evaluation
* thread during the evaluation. If <code>false</code>,
* breakpoints hit in the evaluation thread will be ignored.
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>The associated thread is not currently suspended</li>
* <li>The stack frame is not contained in the debug target
* associated with this evaluation engine</li>
* <li>The associated thread is suspended in the middle of an
* evaluation that has not completed. It is not possible to
* perform nested evaluations</li>
* </ul>
*/
public void evaluateExpression(ICompiledExpression expression,
IJavaStackFrame frame, IEvaluationListener listener,
int evaluationDetail, boolean hitBreakpoints) throws DebugException;
/**
* Asynchronously evaluates the given expression in the context of the
* specified type, reporting the result back to the given listener. The
* expression is evaluated in the context of the Java project this
* evaluation engine was created on. If the expression is determined to have
* no errors, the expression is evaluated in the thread associated with the
* given stack frame. When the evaluation completes, the thread will be
* suspended at this original location. The thread runs the evaluation with
* the given evaluation detail (@see
* IJavaThread#runEvaluation(IEvaluationRunnable, IProgressMonitor, int)).
* Compilation and runtime errors are reported in the evaluation result.
*
* @param expression
* the expression to evaluate
* @param object
* the 'this' context for the evaluation
* @param thread
* the thread in which to run the evaluation, which must be
* suspended
* @param listener
* the listener that will receive notification when/if the
* evaluation completes
* @param evaluationDetail
* one of <code>DebugEvent.EVALUATION</code> or
* <code>DebugEvent.EVALUATION_IMPLICIT</code>
* @param hitBreakpoints
* whether or not breakpoints should be honored in the evaluation
* thread during the evaluation. If <code>false</code>,
* breakpoints hit in the evaluation thread will be ignored.
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>The associated thread is not currently suspended</li>
* <li>The stack frame is not contained in the debug target
* associated with this evaluation engine</li>
* <li>The associated thread is suspended in the middle of an
* evaluation that has not completed. It is not possible to
* perform nested evaluations</li>
* </ul>
*/
public void evaluateExpression(ICompiledExpression expression,
IJavaObject object, IJavaThread thread,
IEvaluationListener listener, int evaluationDetail,
boolean hitBreakpoints) throws DebugException;
/**
* Synchronously generates a compiled expression from the given expression
* in the context of the specified stack frame. The generated expression can
* be stored and evaluated later in a valid runtime context. Compilation
* errors are reported in the returned compiled expression.
*
* @param expression
* expression to compile
* @param frame
* the context in which to compile the expression
* @return the compiled expression
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>The associated thread is not currently suspended</li>
* <li>The stack frame is not contained in the debug target
* associated with this evaluation engine</li>
* </ul>
*/
public ICompiledExpression getCompiledExpression(String expression,
IJavaStackFrame frame) throws DebugException;
/**
* Synchronously generates a compiled expression from the given expression
* in the context of the specified object. The generated expression can be
* stored and evaluated later in a valid runtime context. Compilation errors
* are reported in the returned compiled expression.
*
* @param expression
* expression to compile
* @param object
* the context in which to compile the expression
* @return the compiled epxression
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>The associated thread is not currently suspended</li>
* <li>The stack frame is not contained in the debug target
* associated with this evaluation engine</li>
* </ul>
*/
public ICompiledExpression getCompiledExpression(String expression,
IJavaObject object) throws DebugException;
/**
* Synchronously generates a compiled expression from the given expression
* in the context of the specified type. The generated expression can be
* stored and evaluated later in a valid runtime context. Compilation errors
* are reported in the returned compiled expression.
*
* @param expression
* expression to compile
* @param type
* the context in which to compile the expression
* @return the compiled expression
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>The associated thread is not currently suspended</li>
* <li>The stack frame is not contained in the debug target
* associated with this evaluation engine</li>
* </ul>
* @since 3.1
*/
public ICompiledExpression getCompiledExpression(String expression,
IJavaReferenceType type) throws DebugException;
}