/*******************************************************************************
 * 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.IJavaThread;

/**
 * An evaluation engine that performs evaluations by deploying and executing
 * class files locally.
 *
 * @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 IClassFileEvaluationEngine extends IEvaluationEngine {
	/**
	 * Returns the import declarations for this evaluation context. An empty
	 * list indicates there are no imports. The syntax for the import
	 * corresponds to a fully qualified type name, or to an on-demand package
	 * name as defined by ImportDeclaration (JLS2 7.5). For example,
	 * <code>"java.util.Hashtable"</code> or <code>"java.util.*"</code>.
	 *
	 * @return the list of import names
	 */
	public String[] getImports();

	/**
	 * Sets the import declarations for this evaluation context. An empty list
	 * indicates there are no imports. The syntax for the import corresponds to
	 * a fully qualified type name, or to an on-demand package name as defined
	 * by ImportDeclaration (JLS2 7.5). For example,
	 * <code>"java.util.Hashtable"</code> or <code>"java.util.*"</code>.
	 *
	 * @param imports
	 *            the list of import names
	 */
	public void setImports(String[] imports);

	/**
	 * Asynchronously evaluates the given snippet in the specified target
	 * thread, reporting the result back to the given listener. The snippet is
	 * evaluated in the context of the Java project this evaluation engine was
	 * created on. If the snippet is determined to be a valid expression, the
	 * expression is evaluated in the specified thread, which resumes its
	 * execution from the location at which it is currently suspended. When the
	 * evaluation completes, the thread will be suspened at this original
	 * location. Compilation and runtime errors are reported in the evaluation
	 * result.
	 *
	 * @param snippet
	 *            code snippet to evaluate
	 * @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
	 *            evalaution completes
	 * @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 specified thread is not currently suspended</li>
	 *                <li>The specified thread is not contained in the debug
	 *                target associated with this evaluation engine</li>
	 *                <li>The specified 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 evaluate(String snippet, IJavaThread thread,
			IEvaluationListener listener, boolean hitBreakpoints)
			throws DebugException;

}