/*******************************************************************************
 * 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
 *     Jesper Steen Moller - enhancement 254677 - filter getters/setters
 *     Codenza Software Development Inc. - Darin Wright - bug 330987
 *******************************************************************************/
package org.eclipse.jdt.debug.core;

import org.eclipse.debug.core.DebugException;
import org.eclipse.debug.core.model.IDebugTarget;
import org.eclipse.debug.core.model.IStepFilters;

/**
 * A Java virtual machine.
 * 
 * @see IDebugTarget
 * @see org.eclipse.core.runtime.IAdaptable
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */

public interface IJavaDebugTarget extends IDebugTarget, IStepFilters {
	/**
	 * Searches for and returns a variable with the given name, or
	 * <code>null</code> if unable to resolve a variable with the name.
	 * <p>
	 * Variable lookup works only when a debug target has one or more threads
	 * suspended. Lookup is performed in each suspended thread, returning the
	 * first successful match, or <code>null</code> if no match if found. If
	 * this debug target has no suspended threads, <code>null</code> is
	 * returned.
	 * </p>
	 * 
	 * @param variableName
	 *            name of the variable
	 * @return a variable with the given name, or <code>null</code> if none
	 * @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>
	 *                </ul>
	 */
	public abstract IJavaVariable findVariable(String variableName)
			throws DebugException;

	/**
	 * Returns the types loaded in this debug target with the given fully
	 * qualified name, or <code>null</code> of no type with the given name is
	 * loaded.
	 * 
	 * @param name
	 *            fully qualified name of type, for example
	 *            <code>java.lang.String</code>
	 * @return the types with the given name, or <code>null</code>
	 * @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>
	 *                </ul>
	 */
	public abstract IJavaType[] getJavaTypes(String name) throws DebugException;

	/**
	 * Returns a value from this target that corresponds to the given boolean.
	 * The returned value can be used for setting and comparing against a value
	 * retrieved from this debug target.
	 * 
	 * @param value
	 *            a boolean from which to create a value
	 * @return a corresponding value from this target
	 */
	public abstract IJavaValue newValue(boolean value);

	/**
	 * Returns a value from this target that corresponds to the given byte. The
	 * returned value can be used for setting and comparing against a value
	 * retrieved from this debug target.
	 * 
	 * @param value
	 *            a byte from which to create a value
	 * @return a corresponding value from this target
	 */
	public abstract IJavaValue newValue(byte value);

	/**
	 * Returns a value from this target that corresponds to the given char. The
	 * returned value can be used for setting and comparing against a value
	 * retrieved from this debug target.
	 * 
	 * @param value
	 *            a char from which to create a value
	 * @return a corresponding value from this target
	 */
	public abstract IJavaValue newValue(char value);

	/**
	 * Returns a value from this target that corresponds to the given double.
	 * The returned value can be used for setting and comparing against a value
	 * retrieved from this debug target.
	 * 
	 * @param value
	 *            a double from which to create a value
	 * @return a corresponding value from this target
	 */
	public abstract IJavaValue newValue(double value);

	/**
	 * Returns a value from this target that corresponds to the given float. The
	 * returned value can be used for setting and comparing against a value
	 * retrieved from this debug target.
	 * 
	 * @param value
	 *            a float from which to create a value
	 * @return a corresponding value from this target
	 */
	public abstract IJavaValue newValue(float value);

	/**
	 * Returns a value from this target that corresponds to the given int. The
	 * returned value can be used for setting and comparing against a value
	 * retrieved from this debug target.
	 * 
	 * @param value
	 *            an int from which to create a value
	 * @return a corresponding value from this target
	 */
	public abstract IJavaValue newValue(int value);

	/**
	 * Returns a value from this target that corresponds to the given long. The
	 * returned value can be used for setting and comparing against a value
	 * retrieved from this debug target.
	 * 
	 * @param value
	 *            a long from which to create a value
	 * @return a corresponding value from this target
	 */
	public abstract IJavaValue newValue(long value);

	/**
	 * Returns a value from this target that corresponds to the given short. The
	 * returned value can be used for setting and comparing against a value
	 * retrieved from this debug target.
	 * 
	 * @param value
	 *            a short from which to create a value
	 * @return a corresponding value from this target
	 */
	public abstract IJavaValue newValue(short value);

	/**
	 * Returns a value from this target that corresponds to the given string.
	 * The returned value can be used for setting and comparing against a value
	 * retrieved from this debug target.
	 * 
	 * @param value
	 *            a string from which to create a value
	 * @return a corresponding value from this target
	 */
	public abstract IJavaValue newValue(String value);

	/**
	 * Returns a value from this target that corresponds to <code>null</code>.
	 * The returned value can be used for setting and comparing against a value
	 * retrieved from this debug target.
	 * 
	 * @return a value corresponding to <code>null</code>
	 */
	public abstract IJavaValue nullValue();

	/**
	 * Returns a value from this target that corresponds to <code>void</code>.
	 * The returned value can be used for setting and comparing against a value
	 * retrieved from this debug target.
	 * 
	 * @return a value corresponding to <code>void</code>
	 */
	public abstract IJavaValue voidValue();

	/**
	 * Returns whether any of the threads associated with this debug target are
	 * running code in the VM that is out of synch with the code in the
	 * workspace.
	 * 
	 * @return whether this debug target is out of synch with the workspace.
	 * @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>
	 */
	public abstract boolean isOutOfSynch() throws DebugException;

	/**
	 * Returns whether any of the threads associated with this debug target may
	 * be running code in the VM that is out of synch with the code in the
	 * workspace.
	 * 
	 * @return whether this debug target may be out of synch with the workspace.
	 * @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>
	 */
	public abstract boolean mayBeOutOfSynch() throws DebugException;

	/**
	 * Returns whether this target supports hot code replace.
	 * 
	 * @return whether this target supports hot code replace
	 */
	public boolean supportsHotCodeReplace();

	/**
	 * Returns whether this target is currently performing a hot code replace.
	 * 
	 * @return whether this target is currently performing a hot code replace
	 * @since 2.1
	 */
	public boolean isPerformingHotCodeReplace();

	/**
	 * Returns whether this target supports instance breakpoints.
	 * 
	 * @return whether this target supports instance breakpoints
	 * @since 2.1
	 */
	public boolean supportsInstanceBreakpoints();

	/**
	 * Returns whether synthetic methods are filtered when stepping, if step
	 * filters are enabled.
	 * 
	 * @return whether synthetic methods are filtered when stepping
	 */
	public abstract boolean isFilterSynthetics();

	/**
	 * Sets whether synthetic methods are filtered when stepping.
	 * 
	 * @param filter
	 *            whether to synthetic methods are filtered when stepping
	 */
	public abstract void setFilterSynthetics(boolean filter);

	/**
	 * Returns whether simple getters are filtered when stepping.
	 * 
	 * @return true, if simple getters should be filtered when stepping
	 * @since 3.7
	 */
	public abstract boolean isFilterGetters();

	/**
	 * Sets whether simple getters are filtered when stepping.
	 * 
	 * @param filter
	 *            whether to filter simple getters when stepping
	 * @since 3.7
	 */
	public abstract void setFilterGetters(boolean filter);

	/**
	 * Returns whether simple setters are filtered when stepping.
	 * 
	 * @return true, if simple setters should be filtered when stepping
	 * @since 3.7
	 */
	public abstract boolean isFilterSetters();

	/**
	 * Sets whether simple setters are filtered when stepping.
	 * 
	 * @param filter
	 *            whether to filter simple setters when stepping
	 * @since 3.7
	 */
	public abstract void setFilterSetters(boolean filter);

	/**
	 * Returns whether static initializers are filtered when stepping, if step
	 * filters are enabled.
	 * 
	 * @return whether static initializers are filtered when stepping
	 */
	public abstract boolean isFilterStaticInitializers();

	/**
	 * Sets whether to filter static initializers when stepping.
	 * 
	 * @param filter
	 *            whether to filter static initializers when stepping
	 */
	public abstract void setFilterStaticInitializers(boolean filter);

	/**
	 * Returns whether constructors are filtered when stepping, if step filters
	 * are enabled.
	 * 
	 * @return whether constructors are filtered when stepping
	 */
	public abstract boolean isFilterConstructors();

	/**
	 * Sets whether to filter constructors when stepping.
	 * 
	 * @param filter
	 *            whether to filter constructors when stepping
	 */
	public abstract void setFilterConstructors(boolean filter);

	/**
	 * Returns the list of active step filters in this target. The list is a
	 * collection of Strings. Each string is the fully qualified name/pattern of
	 * a type/package to filter when stepping. For example
	 * <code>java.lang.*</code> or <code>java.lang.String</code>.
	 * 
	 * @return the list of active step filters, or <code>null</code>
	 */
	public abstract String[] getStepFilters();

	/**
	 * Sets the list of active step filters in this target. The list is a
	 * collection of Strings. Each string is the fully qualified name/pattern of
	 * a type/package to filter when stepping. For example
	 * <code>java.lang.*</code> or <code>java.lang.String</code>.
	 * 
	 * @param list
	 *            active step filters, or <code>null</code>
	 */
	public abstract void setStepFilters(String[] list);

	/**
	 * Sets whether a step that lands in a filtered location should continue
	 * through to an un-filtered location, or return to where the step
	 * originated.
	 * 
	 * @param thru
	 *            whether to step thru a filtered location or return to location
	 *            where step originated
	 * @since 3.5
	 */
	public void setStepThruFilters(boolean thru);

	/**
	 * Returns whether a step that lands in a filtered location should proceed
	 * through to an un-filtered location or return to the location where a step
	 * originated.
	 * 
	 * @return whether a step that lands in a filtered location should proceed
	 *         through to an un-filtered location or return to the location
	 *         where a step originated
	 * @since 3.5
	 */
	public boolean isStepThruFilters();

	/**
	 * Returns whether this debug target supports a request timeout - a maximum
	 * time for a JDI request to receive a response. This option is only
	 * supported by the Eclipse JDI implementation.
	 * 
	 * @return whether this debug target supports a request timeout
	 */
	public boolean supportsRequestTimeout();

	/**
	 * Sets the timeout value for JDI requests in milliseconds. Has no effect if
	 * this target does not support a request timeout.
	 * 
	 * @param timeout
	 *            the communication timeout, in milliseconds
	 */
	public void setRequestTimeout(int timeout);

	/**
	 * Returns the timeout value for JDI requests in milliseconds, or -1 if not
	 * supported.
	 * 
	 * @return timeout value, in milliseconds, or -1 if not supported
	 */
	public int getRequestTimeout();

	/**
	 * Returns whether this target supports providing monitor information.
	 * 
	 * @return whether this target supports providing monitor information.
	 * @since 2.1
	 */
	public boolean supportsMonitorInformation();

	/**
	 * Returns whether this target supports access watchpoints.
	 * 
	 * @return whether this target supports access watchpoints
	 * @since 3.0
	 */
	public boolean supportsAccessWatchpoints();

	/**
	 * Returns whether this target supports modification watchpoints.
	 * 
	 * @return whether this target supports modification watchpoints
	 * @since 3.0
	 */
	public boolean supportsModificationWatchpoints();

	/**
	 * Set the default stratum used in this debug target.
	 * 
	 * @param stratum
	 *            the new default stratum, or <code>null</code> to indicate
	 *            per-class default stratum
	 * @since 3.0
	 */
	public void setDefaultStratum(String stratum);

	/**
	 * Return the default stratum used in this the target, or <code>null</code>
	 * to indicate a per-class default stratum.
	 * 
	 * @return the default stratum, or <code>null</code> to indicate a per-class
	 *         default stratum
	 * @see #setDefaultStratum(String)
	 * @since 3.0
	 */
	public String getDefaultStratum();

	/**
	 * Returns the top level thread groups in this target. Top level thread
	 * groups do not have a parent.
	 * 
	 * @return top level thread groups
	 * @throws DebugException
	 *             if an exception occurs
	 * @since 3.2
	 */
	public IJavaThreadGroup[] getRootThreadGroups() throws DebugException;

	/**
	 * Returns all thread groups in this target.
	 * 
	 * @return all thread groups in this target
	 * @throws DebugException
	 *             if an exception occurs
	 * @since 3.2
	 */
	public IJavaThreadGroup[] getAllThreadGroups() throws DebugException;

	/**
	 * Returns whether this VM supports instance and reference retrieval for
	 * types and objects.
	 * 
	 * @return whether this VM supports instance and reference retrieval for
	 *         types and objects
	 * @since 3.3
	 */
	public boolean supportsInstanceRetrieval();

	/**
	 * Returns whether this VM supports the ability to force an early return
	 * from methods.
	 * 
	 * @return whether this VM can force an early return from methods
	 * @since 3.3
	 * @see IJavaThread
	 */
	public boolean supportsForceReturn();

	/**
	 * Returns whether this VM supports the ability to enable and disable
	 * garbage collection of individual objects.
	 * 
	 * @return whether this VM supports the ability to enable and disable
	 *         garbage collection of individual objects
	 * @see IJavaObject
	 * @since 3.4
	 */
	public boolean supportsSelectiveGarbageCollection();

	/**
	 * Returns the name of the underlying virtual machine as defined by the
	 * system property <code>java.vm.name</code>.
	 * 
	 * @return virtual machine name
	 * @exception DebugException
	 *                if retrieving the name fails
	 * @since 3.4
	 */
	public String getVMName() throws DebugException;

	/**
	 * Returns the version of the underlying virtual machine as defined by the
	 * system property <code>java.version</code>.
	 * 
	 * @return <code>java.version</code> system property
	 * @exception DebugException
	 *                if retrieving the version property fails
	 * @since 3.4
	 */
	public String getVersion() throws DebugException;

	/**
	 * Refreshes the state of the Java debug model elements (client) with the
	 * current state of the debug target.
	 * <p>
	 * For example, a {@link IJavaThread} may currently have a suspended state,
	 * but was somehow resumed on the target. Calling this method will causes
	 * all threads to update their state based on the current state of the
	 * target. Elements will fire debug events associated with any state
	 * changes. For example, a thread would fire a resume event if it discovered
	 * it was in a running state when it thought it was suspended.
	 * </p>
	 * 
	 * @throws DebugException
	 *             if an exception occurs
	 * @since 3.6
	 */
	public void refreshState() throws DebugException;

	/**
	 * Sends a JDWP command to the back end and returns the JDWP reply packet as
	 * bytes. This method creates an appropriate command header and packet id,
	 * before sending to the back end.
	 * 
	 * @param commandSet
	 *            command set identifier as defined by JDWP
	 * @param commandId
	 *            command identifier as defined by JDWP
	 * @param data
	 *            any bytes required for the command that follow the command
	 *            header or <code>null</code> for commands that have no data
	 * @return raw reply packet as bytes defined by JDWP
	 * @exception DebugException
	 *                if an error occurs sending the packet or receiving the
	 *                reply
	 * @since 3.6
	 */
	public byte[] sendCommand(byte commandSet, byte commandId, byte[] data)
			throws DebugException;

	/**
	 * Adds the given listener to this target for hot code replace
	 * notifications. Has no effect if an identical listener is already
	 * registered.
	 * <p>
	 * When a hot code replace listener is added to a specific target, general
	 * hot code replace notifications via {@link JDIDebugModel} are not reported
	 * for that target. This allows a target to override general/default hot
	 * code replace listeners/handlers.
	 * </p>
	 * 
	 * @param listener
	 *            hot code replace listener
	 * @since 3.6
	 */
	public void addHotCodeReplaceListener(IJavaHotCodeReplaceListener listener);

	/**
	 * Removes the given listener from this target. Has no effect if an
	 * identical listener is not already registered.
	 * 
	 * @param listener
	 *            hot code replace listener
	 * @since 3.6
	 */
	public void removeHotCodeReplaceListener(
			IJavaHotCodeReplaceListener listener);

}