/******************************************************************************* | |
* Copyright (c) 2000, 2010 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.debug.core; | |
import java.util.List; | |
import java.util.Map; | |
import java.util.Set; | |
import org.eclipse.core.filesystem.EFS; | |
import org.eclipse.core.resources.IFile; | |
import org.eclipse.core.resources.IResource; | |
import org.eclipse.core.runtime.CoreException; | |
import org.eclipse.core.runtime.IAdaptable; | |
import org.eclipse.core.runtime.IPath; | |
import org.eclipse.core.runtime.IProgressMonitor; | |
/** | |
* A launch configuration describes how to launch an application. | |
* Each launch configuration is an instance of a type of launch | |
* configuration as described by a launch configuration type | |
* extension. Each launch configuration has a launch configuration | |
* delegate which performs the actual launching of a | |
* configuration. | |
* <p> | |
* A launch configuration may be shared in a repository via | |
* standard VCM mechanisms, or may be stored locally, essentially | |
* making the launch configuration private for a single user. | |
* Thus, a launch configuration may stored as a file in the | |
* workspace (shared), or as a file in the debug plug-in's state | |
* location. | |
* </p> | |
* A launch configuration is a handle to its underlying storage. | |
* Methods annotated as "handle-only" do not require a configuration | |
* to exist. Methods that require an underlying configuration to exist | |
* throw a <code>CoreException</code> when an underlying configuration | |
* is missing. | |
* </p> | |
* <p> | |
* A launch configuration is modified by obtaining a working copy | |
* of a launch configuration, modifying the working copy, and then | |
* saving the working copy. | |
* </p> | |
* <p> | |
* Clients that define a launch configuration delegate extension implement the | |
* <code>ILaunchConfigurationDelegate</code> interface. | |
* </p> | |
* @see ILaunchConfigurationType | |
* @see org.eclipse.debug.core.model.ILaunchConfigurationDelegate | |
* @see ILaunchConfigurationWorkingCopy | |
* @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 ILaunchConfiguration extends IAdaptable { | |
/** | |
* The file extension for launch configuration files | |
* (value <code>"launch"</code>). | |
*/ | |
public static final String LAUNCH_CONFIGURATION_FILE_EXTENSION = "launch"; //$NON-NLS-1$ | |
/** | |
* Launch configuration attribute storing an identifier of | |
* a persistable source locator extension. When this attribute is | |
* specified, a new source locator will be created automatically and | |
* associated with the launch for this configuration. | |
* | |
* @see org.eclipse.debug.core.model.IPersistableSourceLocator | |
*/ | |
public static final String ATTR_SOURCE_LOCATOR_ID = DebugPlugin.getUniqueIdentifier() + ".source_locator_id"; //$NON-NLS-1$ | |
/** | |
* Launch configuration attribute storing a memento of a | |
* source locator. When this attribute is specified in | |
* conjunction with a source locator id, the source locator | |
* created for a launch will be initialized with this memento. | |
* When not specified, but a source locator id is specified, | |
* the source locator will be initialized to default values. | |
* | |
* @see org.eclipse.debug.core.model.IPersistableSourceLocator | |
*/ | |
public static final String ATTR_SOURCE_LOCATOR_MEMENTO = DebugPlugin.getUniqueIdentifier() + ".source_locator_memento"; //$NON-NLS-1$ | |
/** | |
* Returns whether the contents of this launch configuration are | |
* equal to the contents of the given launch configuration. | |
* | |
* @param configuration launch configuration | |
* @return whether the contents of this launch configuration are equal to the contents | |
* of the specified launch configuration. | |
*/ | |
public boolean contentsEqual(ILaunchConfiguration configuration); | |
/** | |
* Returns a copy of this launch configuration, as a | |
* working copy, with the specified name. The new | |
* working copy does not refer back to this configuration | |
* as its original launch configuration (the working copy | |
* will return <code>null</code> for <code>getOriginal()</code>). | |
* When the working copy is saved it will not affect this | |
* launch configuration. | |
* | |
* @param name the name of the copy | |
* @return a copy of this launch configuration | |
* @exception CoreException if this method fails. Reasons include: | |
* <ul> | |
* <li>An exception occurs while initializing the contents of the | |
* working copy from this configuration's underlying storage.</li> | |
* </ul> | |
* @see ILaunchConfigurationWorkingCopy#getOriginal() | |
*/ | |
public ILaunchConfigurationWorkingCopy copy(String name) throws CoreException; | |
/** | |
* Deletes this launch configuration. This configuration's underlying | |
* storage is deleted. Has no effect if this configuration | |
* does not exist. | |
* | |
* @exception CoreException if this method fails. Reasons include: | |
* <ul> | |
* <li>An exception occurs while deleting this configuration's | |
* underlying storage.</li> | |
* </ul> | |
*/ | |
public void delete() throws CoreException; | |
/** | |
* Returns whether this launch configuration's underlying | |
* storage exists. This is a handle-only method. | |
* | |
* @return whether this launch configuration's underlying | |
* storage exists | |
*/ | |
public boolean exists(); | |
/** | |
* Returns the boolean-valued attribute with the given name. | |
* Returns the given default value if the attribute is undefined. | |
* | |
* @param attributeName the name of the attribute | |
* @param defaultValue the value to use if no value is found | |
* @return the value or the default value if no value was found. | |
* @exception CoreException if this method fails. Reasons include: | |
* <ul> | |
* <li>An exception occurs while retrieving the attribute from | |
* underlying storage.</li> | |
* <li>An attribute with the given name exists, but does not | |
* have a boolean value</li> | |
* </ul> | |
*/ | |
public boolean getAttribute(String attributeName, boolean defaultValue) throws CoreException; | |
/** | |
* Returns the integer-valued attribute with the given name. | |
* Returns the given default value if the attribute is undefined. | |
* | |
* @param attributeName the name of the attribute | |
* @param defaultValue the value to use if no value is found | |
* @return the value or the default value if no value was found. | |
* @exception CoreException if this method fails. Reasons include: | |
* <ul> | |
* <li>An exception occurs while retrieving the attribute from | |
* underlying storage.</li> | |
* <li>An attribute with the given name exists, but does not | |
* have an integer value</li> | |
* </ul> | |
*/ | |
public int getAttribute(String attributeName, int defaultValue) throws CoreException; | |
/** | |
* Returns the <code>java.util.List</code>-valued attribute with the given name. | |
* Returns the given default value if the attribute is undefined. | |
* | |
* @param attributeName the name of the attribute | |
* @param defaultValue the value to use if no value is found | |
* @return the value or the default value if no value was found. | |
* @exception CoreException if this method fails. Reasons include: | |
* <ul> | |
* <li>An exception occurs while retrieving the attribute from | |
* underlying storage.</li> | |
* <li>An attribute with the given name exists, but does not | |
* have a List value</li> | |
* </ul> | |
*/ | |
public List getAttribute(String attributeName, List defaultValue) throws CoreException; | |
/** | |
* Returns the <code>java.util.Set</code>-valued attribute with the given name. | |
* Returns the given default value if the attribute is undefined. | |
* | |
* @param attributeName the name of the attribute | |
* @param defaultValue the value to use if no value is found | |
* @return the value or the default value if no value was found. | |
* @exception CoreException if this method fails. Reasons include: | |
* <ul> | |
* <li>An exception occurs while retrieving the attribute from | |
* underlying storage.</li> | |
* <li>An attribute with the given name exists, but does not | |
* have a List value</li> | |
* </ul> | |
* | |
* @since 3.3 | |
*/ | |
public Set getAttribute(String attributeName, Set defaultValue) throws CoreException; | |
/** | |
* Returns the <code>java.util.Map</code>-valued attribute with the given name. | |
* Returns the given default value if the attribute is undefined. | |
* | |
* @param attributeName the name of the attribute | |
* @param defaultValue the value to use if no value is found | |
* @return the value or the default value if no value was found. | |
* @exception CoreException if this method fails. Reasons include: | |
* <ul> | |
* <li>An exception occurs while retrieving the attribute from | |
* underlying storage.</li> | |
* <li>An attribute with the given name exists, but does not | |
* have a Map value</li> | |
* </ul> | |
*/ | |
public Map getAttribute(String attributeName, Map defaultValue) throws CoreException; | |
/** | |
* Returns the string-valued attribute with the given name. | |
* Returns the given default value if the attribute is undefined. | |
* | |
* @param attributeName the name of the attribute | |
* @param defaultValue the value to use if no value is found | |
* @return the value or the default value if no value was found. | |
* @exception CoreException if this method fails. Reasons include: | |
* <ul> | |
* <li>An exception occurs while retrieving the attribute from | |
* underlying storage.</li> | |
* <li>An attribute with the given name exists, but does not | |
* have a String value</li> | |
* </ul> | |
*/ | |
public String getAttribute(String attributeName, String defaultValue) throws CoreException; | |
/** | |
* Returns a map containing the attributes in this launch configuration. | |
* Returns an empty map if this configuration has no attributes. | |
* <p> | |
* Modifying the map does not affect this launch configuration's attributes. | |
* A launch configuration is modified by obtaining a working copy of that | |
* launch configuration, modifying the working copy, and then saving the working | |
* copy. | |
* </p> | |
* @return a map of attribute keys and values | |
* @exception CoreException unable to generate/retrieve an attribute map | |
* @since 2.1 | |
*/ | |
public Map getAttributes() throws CoreException; | |
/** | |
* Returns this launch configuration's type's category, or <code>null</code> | |
* if unspecified. This is a handle-only method. | |
* | |
* @return this launch configuration's type's category, or <code>null</code> | |
* @exception CoreException if this method fails. Reasons include: | |
* <ul> | |
* <li>Unable to retrieve or instantiate this launch configuration's type.</li> | |
* </ul> | |
* @since 2.1 | |
*/ | |
public String getCategory() throws CoreException; | |
/** | |
* Returns the file this launch configuration is stored | |
* in, or <code>null</code> if this configuration is stored | |
* locally with the workspace. This is a handle-only method. | |
* | |
* @return the file this launch configuration is stored | |
* in, or <code>null</code> if this configuration is stored | |
* locally with the workspace | |
*/ | |
public IFile getFile(); | |
/** | |
* Returns the location of this launch configuration as a | |
* path in the local file system or <code>null</code> if it cannot | |
* be mapped to a location in the local file system. This is a handle-only method. | |
* <p> | |
* Since 3.5, this method can return <code>null</code>. For example, when a | |
* launch configuration is stored in the workspace as an {@link IFile} in | |
* an external file system ({@link EFS}). | |
* </p> | |
* | |
* @return the location of this launch configuration as a | |
* path file system or <code>null</code> if it cannot be mapped | |
* to a location in the local file system. Since 3.5, this method | |
* can return <code>null</code>. | |
* @deprecated Since a launch configuration does not need to be stored in the local | |
* file system, this attribute should no longer be used to identify a launch configuration. | |
*/ | |
public IPath getLocation(); | |
/** | |
* Returns the resources this launch configuration is associated with or <code>null</code> | |
* if none. Clients contributing launch configuration types are responsible for maintaining | |
* resource mappings as appropriate. | |
* | |
* @return the resources this launch configuration is associated with or <code>null</code> | |
* @throws CoreException unable to get the mapped resource | |
* @since 3.2 | |
*/ | |
public IResource[] getMappedResources() throws CoreException; | |
/** | |
* Returns a memento for this launch configuration, or <code>null</code> | |
* if unable to generate a memento for this configuration. A memento | |
* can be used to re-create a launch configuration, via the | |
* launch manager. | |
* | |
* @return a memento for this configuration | |
* @see ILaunchManager#getLaunchConfiguration(String) | |
* @exception CoreException if an exception occurs generating this | |
* launch configuration's memento | |
*/ | |
public String getMemento() throws CoreException; | |
/** | |
* Returns the name of this launch configuration. This is | |
* a handle-only method. | |
* | |
* @return the name of this launch configuration | |
*/ | |
public String getName(); | |
/** | |
* Returns the launch modes that have been set on this configuration. | |
* An empty set is returned if no specific launch modes have been set | |
* on a launch configuration. | |
* <p> | |
* Setting launch modes on a configuration allows a launch to be | |
* performed in mixed mode - for example, debug and profile at the | |
* same time. | |
* </p> | |
* @return this configuration's launch modes, possibly an empty set | |
* @exception CoreException if an exception occurs retrieving modes | |
* @since 3.3 | |
*/ | |
public Set getModes() throws CoreException; | |
/** | |
* Returns the preferred launch delegate that has been set on this | |
* configuration or <code>null</code> if one is not specified. | |
* | |
* @param modes mode set for which a preferred delegate has been requested | |
* @return this configuration's preferred launch delegate for the specified mode set, or | |
* <code>null</code> if one is not specified | |
* @exception CoreException if an exception occurs retrieving preferred delegate | |
* @since 3.3 | |
*/ | |
public ILaunchDelegate getPreferredDelegate(Set modes) throws CoreException; | |
/** | |
* Returns the type of this launch configuration. This is a | |
* handle-only method. | |
* | |
* @return the type of this launch configuration | |
* @exception CoreException if this method fails. Reasons include: | |
* <ul> | |
* <li>Unable to retrieve or instantiate this launch configuration's type.</li> | |
* </ul> | |
* @see ILaunchConfigurationType | |
*/ | |
public ILaunchConfigurationType getType() throws CoreException; | |
/** | |
* Returns a working copy of this launch configuration. | |
* Since 3.3, if this method is called on a working copy, a nested working | |
* copy is created (a working copy of a working copy). | |
* Changes to the working copy will be applied to this | |
* launch configuration when saved, or to the parent working copy. | |
* The working copy will refer to this launch configuration as its original | |
* launch configuration, or the working copy it was created from. | |
* <p> | |
* When a working copy (B) is created from a working copy (A), the newly | |
* created working copy (B) is initialized with the attributes from | |
* the first working copy (A). Whenever a working copy is saved, it is written | |
* back to the working copy from which it was created: in this example working | |
* copy B will write back to working copy A, and A will write back to the | |
* original launch configuration. | |
* </p> | |
* @return a working copy of this launch configuration, or a nested working copy if called | |
* on an instance of <code>ILaunchConfigurationWorkingCopy</code> | |
* @exception CoreException if this method fails. Reasons include: | |
* <ul> | |
* <li>An exception occurs while initializing the contents of the | |
* working copy from this configuration's underlying storage.</li> | |
* </ul> | |
* @see ILaunchConfigurationWorkingCopy#getOriginal() | |
*/ | |
public ILaunchConfigurationWorkingCopy getWorkingCopy() throws CoreException; | |
/** | |
* Returns whether this configuration contains an attribute with the given name. | |
* | |
* @param attributeName the name of the attribute | |
* @return true if this configuration has the specified attribute false otherwise | |
* @throws CoreException if unable to retrieve attributes | |
* | |
* @since 3.4 | |
*/ | |
public boolean hasAttribute(String attributeName) throws CoreException; | |
/** | |
* Returns whether this launch configuration is stored | |
* locally within the workspace. This is a handle-only method. | |
* | |
* @return whether this launch configuration is stored | |
* locally with the workspace | |
*/ | |
public boolean isLocal(); | |
/** | |
* Returns whether this launch configuration is a candidate for migration. | |
* | |
* @return whether this launch configuration is a candidate for migration | |
* @throws CoreException | |
* @see ILaunchConfigurationMigrationDelegate | |
* @since 3.2 | |
*/ | |
public boolean isMigrationCandidate() throws CoreException ; | |
/** | |
* Returns whether this launch configuration is a working | |
* copy. Launch configurations which return <code>true</code> | |
* to this method can be safely cast to | |
* <code>org.eclipse.debug.core.ILaunchConfigurationWorkingCopy</code>. | |
* This is a handle-only method. | |
* | |
* @return whether this launch configuration is a working | |
* copy | |
*/ | |
public boolean isWorkingCopy(); | |
/** | |
* Launches this configuration in the specified mode by delegating to | |
* this configuration's launch configuration delegate, and returns the | |
* resulting launch. | |
* <p> | |
* Equivalent to calling <code>launch(String, IProgressMontitor, boolean)</code> | |
* with a <code>build</code> flag of <code>false</code>. | |
* </p> | |
* @param mode the mode in which to launch, one of the mode constants | |
* defined by <code>ILaunchManager</code> - <code>RUN_MODE</code> or <code>DEBUG_MODE</code>. | |
* @param monitor progress monitor, or <code>null</code>. A cancelable progress monitor is provided by the Job | |
* framework. It should be noted that the setCanceled(boolean) method should never be called on the provided | |
* monitor or the monitor passed to any delegates from this method; due to a limitation in the progress monitor | |
* framework using the setCanceled method can cause entire workspace batch jobs to be canceled, as the canceled flag | |
* is propagated up the top-level parent monitor. The provided monitor is not guaranteed to have been started. | |
* @return the resulting launch | |
* @exception CoreException if this method fails. Reasons include:<ul> | |
* <li>unable to instantiate the underlying launch configuration delegate</li> | |
* <li>the launch fails (in the delegate)</code> | |
* </ul> | |
*/ | |
public ILaunch launch(String mode, IProgressMonitor monitor) throws CoreException; | |
/** | |
* Launches this configuration in the specified mode by delegating to | |
* this configuration's launch configuration delegate, and returns the | |
* resulting launch. | |
* <p> | |
* If this configuration's launch delegate implements | |
* <code>ILaunchConfigurationDelegate2</code>, the launch delegate will | |
* be consulted to provide a launch object for the launch, | |
* perform pre-launch checks, and build before the launch. | |
* If <code>build</code> is <code>true</code> and the associated launch | |
* delegate does not implement <code>ILaunchConfigurationDelegate2</code> | |
* an incremental workspace build will be performed before the launch | |
* by the debug platform. | |
* </p> | |
* <p> | |
* The resulting launch object is registered with the launch manager | |
* before passing it to this configuration's delegate launch method, for | |
* contributions (debug targets and processes). | |
* </p> | |
* <p> | |
* If the delegate contributes a source locator to the launch, that | |
* source locator is used. Otherwise an appropriate source locator is | |
* contributed to the launch based on the values of | |
* <code>ATTR_SOURCE_LOCATOR_ID</code> and | |
* <code>ATTR_SOURCE_LOCATOR_MEMENTO</code>. If the launch is canceled (via | |
* the given progress monitor), the launch is removed from the launch | |
* manager. The launch is returned whether canceled or not. Invoking this | |
* method causes the underlying launch configuration delegate to be | |
* instantiated (if not already). | |
* </p> | |
* @param mode the mode in which to launch, one of the mode constants | |
* defined by <code>ILaunchManager</code> - <code>RUN_MODE</code> or <code>DEBUG_MODE</code>. | |
* @param monitor progress monitor, or <code>null</code>. A cancelable progress monitor is provided by the Job | |
* framework. It should be noted that the setCanceled(boolean) method should never be called on the provided | |
* monitor or the monitor passed to any delegates from this method; due to a limitation in the progress monitor | |
* framework using the setCanceled method can cause entire workspace batch jobs to be canceled, as the canceled flag | |
* is propagated up the top-level parent monitor. The provided monitor is not guaranteed to have been started. | |
* @param build whether the workspace should be built before the launch | |
* @return resulting launch | |
* @throws CoreException if an exception occurs during the launch sequence | |
* @since 3.0 | |
*/ | |
public ILaunch launch(String mode, IProgressMonitor monitor, boolean build) throws CoreException; | |
/** | |
* Launches this configuration in the specified mode by delegating to | |
* this configuration's launch configuration delegate, and returns the | |
* resulting launch. | |
* <p> | |
* If this configuration's launch delegate implements | |
* <code>ILaunchConfigurationDelegate2</code>, the launch delegate will | |
* be consulted to provide a launch object for the launch, | |
* perform pre-launch checks, and build before the launch. | |
* If <code>build</code> is <code>true</code> and the associated launch | |
* delegate does not implement <code>ILaunchConfigurationDelegate2</code> | |
* an incremental workspace build will be performed before the launch | |
* by the debug platform. | |
* </p> | |
* <p> | |
* When <code>register</code> is <code>true</code>, the resulting launch object | |
* is registered with the launch manager before passing it to this configuration's delegate | |
* launch method, for contributions (debug targets and processes). When | |
* <code>register</code> is <code>false</code>, the launch is not registered with | |
* the launch manager. Clients that launch configurations without registering | |
* a launch should register appropriate debug event filters to intercept events | |
* from unregistered launches. | |
* </p> | |
* <p> | |
* If the delegate contributes a source locator to the launch, that | |
* source locator is used. Otherwise an appropriate source locator is | |
* contributed to the launch based on the values of | |
* <code>ATTR_SOURCE_LOCATOR_ID</code> and | |
* <code>ATTR_SOURCE_LOCATOR_MEMENTO</code>. If the launch is canceled (via | |
* the given progress monitor), the launch is removed from the launch | |
* manager. The launch is returned whether canceled or not. Invoking this | |
* method causes the underlying launch configuration delegate to be | |
* instantiated (if not already). | |
* </p> | |
* @param mode the mode in which to launch, one of the mode constants | |
* defined by <code>ILaunchManager</code> - <code>RUN_MODE</code> or <code>DEBUG_MODE</code>. | |
* @param monitor progress monitor, or <code>null</code>. A cancelable progress monitor is provided by the Job | |
* framework. It should be noted that the setCanceled(boolean) method should never be called on the provided | |
* monitor or the monitor passed to any delegates from this method; due to a limitation in the progress monitor | |
* framework using the setCanceled method can cause entire workspace batch jobs to be canceled, as the canceled flag | |
* is propagated up the top-level parent monitor. The provided monitor is not guaranteed to have been started. | |
* @param build whether the workspace should be built before the launch | |
* @param register whether to register the resulting launch with the launch manager | |
* @return resulting launch | |
* @throws CoreException if an exception occurs during the launch sequence | |
* @since 3.1 | |
*/ | |
public ILaunch launch(String mode, IProgressMonitor monitor, boolean build, boolean register) throws CoreException; | |
/** | |
* Migrates this launch configuration to be compatible with current tooling. | |
* Has no effect if this configuration is not a candidate for migration. | |
* Migration is performed by a launch configuration migration delegate. | |
* @throws CoreException if migration fails | |
* @since 3.2 | |
* @see ILaunchConfigurationMigrationDelegate | |
*/ | |
public void migrate() throws CoreException; | |
/** | |
* Returns whether this launch configuration supports the | |
* specified mode. This is a handle-only method. | |
* | |
* @param mode a mode in which a configuration can be launched, one of | |
* the mode constants defined by <code>ILaunchManager</code> - <code>RUN_MODE</code> or | |
* <code>DEBUG_MODE</code>. | |
* @return whether this launch configuration supports the | |
* specified mode | |
* @exception CoreException if this method fails. Reasons include: | |
* <ul> | |
* <li>Unable to retrieve this launch configuration's type.</li> | |
* </ul> | |
*/ | |
public boolean supportsMode(String mode) throws CoreException; | |
/** | |
* Returns whether this launch configuration is read-only. | |
* A read-only configuration cannot be modified. | |
* | |
* @return whether this configuration is read-only | |
* | |
* @since 3.3 | |
*/ | |
public boolean isReadOnly(); | |
} |