org.eclipse.debug.core
Interface ILaunchConfiguration

All Superinterfaces:

IAdaptable

All Known Subinterfaces:

ILaunchConfigurationWorkingCopy

public interface ILaunchConfiguration

extends IAdaptable

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.

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.

A launch configuration is a handle to its underlying storage.

A launch configuration is modified by obtaining a working copy of a launch configuration, modifying the working copy, and then saving the working copy.

This interface is not intended to be implemented by clients. Clients that define a launch configuration delegate extension implement the ILaunchConfigurationDelegate interface.

Since:

2.0

See Also:

ILaunchConfigurationType, ILaunchConfigurationDelegate, ILaunchConfigurationWorkingCopy

Field Summary

static String	ATTR_SOURCE_LOCATOR_ID Launch configuration attribute storing an identifier of a persistable source locator extension.
static String	ATTR_SOURCE_LOCATOR_MEMENTO Launch configuration attribute storing a memento of a source locator.
static String	LAUNCH_CONFIGURATION_FILE_EXTENSION The file extension for launch configuration files (value "launch").

Method Summary

boolean	contentsEqual(ILaunchConfiguration configuration) Returns whether the contents of this launch configuration are equal to the contents of the given launch configuration.
ILaunchConfigurationWorkingCopy	copy(String name) Returns a copy of this launch configuration, as a working copy, with the specified name.
void	delete() Deletes this launch configuration.
boolean	exists() Returns whether this launch configuration's underlying storage exists.
boolean	getAttribute(String attributeName, boolean defaultValue) Returns the boolean-valued attribute with the given name.
int	getAttribute(String attributeName, int defaultValue) Returns the integer-valued attribute with the given name.
List	getAttribute(String attributeName, List defaultValue) Returns the java.util.List-valued attribute with the given name.
Map	getAttribute(String attributeName, Map defaultValue) Returns the java.util.Map-valued attribute with the given name.
String	getAttribute(String attributeName, String defaultValue) Returns the string-valued attribute with the given name.
IFile	getFile() Returns the file this launch configuration is stored in, or null if this configuration is stored locally with the workspace.
IPath	getLocation() Returns the location of this launch configuration as a path.
String	getMemento() Returns a memento for this launch configuration, or null if unable to generate a memento for this configuration.
String	getName() Returns the name of this launch configuration.
ILaunchConfigurationType	getType() Returns the type of this launch configuration.
ILaunchConfigurationWorkingCopy	getWorkingCopy() Returns a working copy of this launch configuration.
boolean	isLocal() Returns whether this launch configuration is stored locally with the workspace.
boolean	isWorkingCopy() Returns whether this launch configuration is a working copy.
ILaunch	launch(String mode, IProgressMonitor monitor) Launches this configuration in the specified mode by delegating to this configuration's launch configuration delegate, and returns the resulting launch.
boolean	supportsMode(String mode) Returns whether this launch configuration supports the specified mode.

Methods inherited from interface org.eclipse.core.runtime.IAdaptable

getAdapter

Field Detail

LAUNCH_CONFIGURATION_FILE_EXTENSION

public static final String LAUNCH_CONFIGURATION_FILE_EXTENSION

The file extension for launch configuration files (value "launch").

See Also:

Constant Field Values

ATTR_SOURCE_LOCATOR_ID

public static final String ATTR_SOURCE_LOCATOR_ID

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 Also:

IPersistableSourceLocator

ATTR_SOURCE_LOCATOR_MEMENTO

public static final String ATTR_SOURCE_LOCATOR_MEMENTO

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 Also:

IPersistableSourceLocator

Method Detail

launch

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. A new launch object is created and registered with the launch manager before passing it to this configuration's delegate for contributions (debug targets and processes). 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 ATTR_SOURCE_LOCAOTOR_ID and ATTR_SOURCE_LOCATOR_MEMENTO. If the launch is cancelled (via the given progress monitor), the launch is removed from the launch manager. The launch is returned whether cancelled or not. Invoking this method causes the underlying launch configuration delegate to be instantiated (if not already).

Parameters:

mode - the mode in which to launch, one of the mode constants defined by ILaunchManager - RUN_MODE or DEBUG_MODE.

monitor - progress monitor, or null

Returns:

the resulting launch.

Throws:

CoreException - if this method fails. Reasons include:

• unable to instantiate the underlying launch configuration delegate
• the launch fails (in the delegate)

supportsMode

public boolean supportsMode(String mode)
                     throws CoreException

Returns whether this launch configuration supports the specified mode.

Parameters:

mode - a mode in which a configuration can be launched, one of the mode constants defined by ILaunchManager - RUN_MODE or DEBUG_MODE.

Returns:

whether this launch configuration supports the specified mode

Throws:

CoreException - if this method fails. Reasons include:

• Unable to retrieve this launch configuration's type.

getName

public String getName()

Returns the name of this launch configuration.

Returns:

the name of this launch configuration

getLocation

public IPath getLocation()

Returns the location of this launch configuration as a path.

Returns:

the location of this launch configuration as a path

exists

public boolean exists()

Returns whether this launch configuration's underlying storage exists.

Returns:

whether this launch configuration's underlying storage exists

getAttribute

public int getAttribute(String attributeName,
                        int defaultValue)
                 throws CoreException

Returns the integer-valued attribute with the given name. Returns the given default value if the attribute is undefined.

Parameters:

attributeName - the name of the attribute

defaultValue - the value to use if no value is found

Returns:

the value or the default value if no value was found.

Throws:

CoreException - if this method fails. Reasons include:

• An exception occurs while retrieving the attribute from underlying storage.
• An attribute with the given name exists, but does not have an integer value

getAttribute

public String getAttribute(String attributeName,
                           String defaultValue)
                    throws CoreException

Returns the string-valued attribute with the given name. Returns the given default value if the attribute is undefined.

Parameters:

attributeName - the name of the attribute

defaultValue - the value to use if no value is found

Returns:

the value or the default value if no value was found.

Throws:

CoreException - if this method fails. Reasons include:

• An exception occurs while retrieving the attribute from underlying storage.
• An attribute with the given name exists, but does not have a String value

getAttribute

public boolean getAttribute(String attributeName,
                            boolean defaultValue)
                     throws CoreException

Returns the boolean-valued attribute with the given name. Returns the given default value if the attribute is undefined.

Parameters:

attributeName - the name of the attribute

defaultValue - the value to use if no value is found

Returns:

the value or the default value if no value was found.

Throws:

CoreException - if this method fails. Reasons include:

• An exception occurs while retrieving the attribute from underlying storage.
• An attribute with the given name exists, but does not have a boolean value

getAttribute

public List getAttribute(String attributeName,
                         List defaultValue)
                  throws CoreException

Returns the java.util.List-valued attribute with the given name. Returns the given default value if the attribute is undefined.

Parameters:

attributeName - the name of the attribute

defaultValue - the value to use if no value is found

Returns:

the value or the default value if no value was found.

Throws:

CoreException - if this method fails. Reasons include:

• An exception occurs while retrieving the attribute from underlying storage.
• An attribute with the given name exists, but does not have a List value

getAttribute

public Map getAttribute(String attributeName,
                        Map defaultValue)
                 throws CoreException

Returns the java.util.Map-valued attribute with the given name. Returns the given default value if the attribute is undefined.

Parameters:

attributeName - the name of the attribute

defaultValue - the value to use if no value is found

Returns:

the value or the default value if no value was found.

Throws:

CoreException - if this method fails. Reasons include:

• An exception occurs while retrieving the attribute from underlying storage.
• An attribute with the given name exists, but does not have a Map value

getFile

public IFile getFile()

Returns the file this launch configuration is stored in, or null if this configuration is stored locally with the workspace.

Returns:

the file this launch configuration is stored in, or null if this configuration is stored locally with the workspace

getType

public ILaunchConfigurationType getType()
                                 throws CoreException

Returns the type of this launch configuration.

Returns:

the type of this launch configuration

Throws:

CoreException - if this method fails. Reasons include:

• Unable to retrieve or instantiate this launch configuration's type.

See Also:

ILaunchConfigurationType

isLocal

public boolean isLocal()

Returns whether this launch configuration is stored locally with the workspace.

Returns:

whether this launch configuration is stored locally with the workspace

getWorkingCopy

public ILaunchConfigurationWorkingCopy getWorkingCopy()
                                               throws CoreException

Returns a working copy of this launch configuration. Changes to the working copy will be applied to this launch configuration when saved. The working copy will refer to this launch configuration as its original launch configuration.

Returns:

a working copy of this launch configuration

Throws:

CoreException - if this method fails. Reasons include:

• An exception occurs while initializing the contents of the working copy from this configuration's underlying storage.

See Also:

ILaunchConfigurationWorkingCopy.getOriginal()

copy

public ILaunchConfigurationWorkingCopy copy(String name)
                                     throws CoreException

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 null for getOriginal()). When the working copy is saved it will not effect this launch configuration.

Parameters:

name - the name of the copy

Returns:

a copy of this launch configuration

Throws:

CoreException - if this method fails. Reasons include:

• An exception occurs while initializing the contents of the working copy from this configuration's underlying storage.

See Also:

ILaunchConfigurationWorkingCopy.getOriginal()

isWorkingCopy

public boolean isWorkingCopy()

Returns whether this launch configuration is a working copy.

Returns:

whether this launch configuration is a working copy

delete

public void delete()
            throws CoreException

Deletes this launch configuration. This configuration's underlying storage is deleted. Has no effect if this configuration does not exist.

Throws:

CoreException - if this method fails. Reasons include:

• An exception occurs while deleting this configuration's underlying storage.

getMemento

public String getMemento()
                  throws CoreException

Returns a memento for this launch configuration, or null if unable to generate a memento for this configuration. A memento can be used to re-create a launch configuration, via the launch manager.

Returns:

a memento for this configuration

Throws:

CoreException - if an exception occurs generating this launch configuration's memento

See Also:

ILaunchManager.getLaunchConfiguration(String)

contentsEqual

public boolean contentsEqual(ILaunchConfiguration configuration)

Returns whether the contents of this launch configuration are equal to the contents of the given launch configuration.

Returns:

whether the contents of this launch configuration are equal to the contents of the specified launch configuration.