/*******************************************************************************
 * Copyright (c) 2000, 2008 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.
 */ 
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;
	
	
}