public interface ILaunchConfiguration extends IAdaptable
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. Methods annotated as "handle-only" do not require a configuration to exist. Methods that require an underlying configuration to exist throw aCoreException
when an underlying configuration
is missing.
A launch configuration is modified by obtaining a working copy of a launch configuration, modifying the working copy, and then saving the working copy.
Clients that define a launch configuration delegate extension implement the
ILaunchConfigurationDelegate
interface.
ILaunchConfigurationType
,
ILaunchConfigurationDelegate
,
ILaunchConfigurationWorkingCopy
Modifier and Type | Field and Description |
---|---|
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" ). |
Modifier and Type | Method and Description |
---|---|
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<String> |
getAttribute(String attributeName,
List<String> defaultValue)
Returns the
java.util.List -valued attribute with the given name. |
Map<String,String> |
getAttribute(String attributeName,
Map<String,String> defaultValue)
Returns the
java.util.Map -valued attribute with the given name. |
Set<String> |
getAttribute(String attributeName,
Set<String> defaultValue)
Returns the
java.util.Set -valued attribute with the given name. |
String |
getAttribute(String attributeName,
String defaultValue)
Returns the string-valued attribute with the given name.
|
Map<String,Object> |
getAttributes()
Returns a map containing the attributes in this launch configuration.
|
String |
getCategory()
Returns this launch configuration's type's category, or
null
if unspecified. |
IFile |
getFile()
Returns the file this launch configuration is stored
in, or
null if this configuration is stored
locally with the workspace. |
IPath |
getLocation()
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.
|
IResource[] |
getMappedResources()
Returns the resources this launch configuration is associated with or
null
if none. |
String |
getMemento()
Returns a memento for this launch configuration, or
null
if unable to generate a memento for this configuration. |
Set<String> |
getModes()
Returns the launch modes that have been set on this configuration.
|
String |
getName()
Returns the name of this launch configuration.
|
ILaunchDelegate |
getPreferredDelegate(Set<String> modes)
Returns the preferred launch delegate that has been set on this
configuration or
null if one is not specified. |
ILaunchConfigurationType |
getType()
Returns the type of this launch configuration.
|
ILaunchConfigurationWorkingCopy |
getWorkingCopy()
Returns a working copy of this launch configuration.
|
boolean |
hasAttribute(String attributeName)
Returns whether this configuration contains an attribute with the given name.
|
boolean |
isLocal()
Returns whether this launch configuration is stored
locally within the workspace.
|
boolean |
isMigrationCandidate()
Returns whether this launch configuration is a candidate for migration.
|
boolean |
isReadOnly()
Returns whether this launch configuration is read-only.
|
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.
|
ILaunch |
launch(String mode,
IProgressMonitor monitor,
boolean build)
Launches this configuration in the specified mode by delegating to
this configuration's launch configuration delegate, and returns the
resulting launch.
|
ILaunch |
launch(String mode,
IProgressMonitor monitor,
boolean build,
boolean register)
Launches this configuration in the specified mode by delegating to
this configuration's launch configuration delegate, and returns the
resulting launch.
|
void |
migrate()
Migrates this launch configuration to be compatible with current tooling.
|
boolean |
supportsMode(String mode)
Returns whether this launch configuration supports the
specified mode.
|
getAdapter
static final String LAUNCH_CONFIGURATION_FILE_EXTENSION
"launch"
).static final String ATTR_SOURCE_LOCATOR_ID
IPersistableSourceLocator
static final String ATTR_SOURCE_LOCATOR_MEMENTO
IPersistableSourceLocator
boolean contentsEqual(ILaunchConfiguration configuration)
configuration
- launch configurationILaunchConfigurationWorkingCopy copy(String name) throws CoreException
null
for getOriginal()
).
When the working copy is saved it will not affect this
launch configuration.name
- the name of the copyCoreException
- if this method fails. Reasons include:
ILaunchConfigurationWorkingCopy.getOriginal()
void delete() throws CoreException
CoreException
- if this method fails. Reasons include:
boolean exists()
boolean getAttribute(String attributeName, boolean defaultValue) throws CoreException
attributeName
- the name of the attributedefaultValue
- the value to use if no value is foundCoreException
- if this method fails. Reasons include:
int getAttribute(String attributeName, int defaultValue) throws CoreException
attributeName
- the name of the attributedefaultValue
- the value to use if no value is foundCoreException
- if this method fails. Reasons include:
List<String> getAttribute(String attributeName, List<String> defaultValue) throws CoreException
java.util.List
-valued attribute with the given name.
Returns the given default value if the attribute is undefined.attributeName
- the name of the attributedefaultValue
- the value to use if no value is foundCoreException
- if this method fails. Reasons include:
Set<String> getAttribute(String attributeName, Set<String> defaultValue) throws CoreException
java.util.Set
-valued attribute with the given name.
Returns the given default value if the attribute is undefined.attributeName
- the name of the attributedefaultValue
- the value to use if no value is foundCoreException
- if this method fails. Reasons include:
Map<String,String> getAttribute(String attributeName, Map<String,String> defaultValue) throws CoreException
java.util.Map
-valued attribute with the given name.
Returns the given default value if the attribute is undefined.attributeName
- the name of the attributedefaultValue
- the value to use if no value is foundCoreException
- if this method fails. Reasons include:
String getAttribute(String attributeName, String defaultValue) throws CoreException
attributeName
- the name of the attributedefaultValue
- the value to use if no value is foundCoreException
- if this method fails. Reasons include:
Map<String,Object> getAttributes() throws CoreException
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.
CoreException
- unable to generate/retrieve an attribute mapString getCategory() throws CoreException
null
if unspecified. This is a handle-only method.null
CoreException
- if this method fails. Reasons include:
IFile getFile()
null
if this configuration is stored
locally with the workspace. This is a handle-only method.null
if this configuration is stored
locally with the workspace@Deprecated IPath getLocation()
null
if it cannot
be mapped to a location in the local file system. This is a handle-only method.
Since 3.5, this method can return null
. For example, when a
launch configuration is stored in the workspace as an IFile
in
an external file system (EFS
).
null
if it cannot be mapped
to a location in the local file system. Since 3.5, this method
can return null
.IResource[] getMappedResources() throws CoreException
null
if none. Clients contributing launch configuration types are responsible for maintaining
resource mappings as appropriate.null
CoreException
- unable to get the mapped resourceString getMemento() throws CoreException
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.CoreException
- if an exception occurs generating this
launch configuration's mementoILaunchManager.getLaunchConfiguration(String)
String getName()
Set<String> getModes() throws CoreException
Setting launch modes on a configuration allows a launch to be performed in mixed mode - for example, debug and profile at the same time.
CoreException
- if an exception occurs retrieving modesILaunchDelegate getPreferredDelegate(Set<String> modes) throws CoreException
null
if one is not specified.modes
- mode set for which a preferred delegate has been requestednull
if one is not specifiedCoreException
- if an exception occurs retrieving preferred delegateILaunchConfigurationType getType() throws CoreException
CoreException
- if this method fails. Reasons include:
ILaunchConfigurationType
ILaunchConfigurationWorkingCopy getWorkingCopy() throws CoreException
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.
ILaunchConfigurationWorkingCopy
CoreException
- if this method fails. Reasons include:
ILaunchConfigurationWorkingCopy.getOriginal()
boolean hasAttribute(String attributeName) throws CoreException
attributeName
- the name of the attributeCoreException
- if unable to retrieve attributesboolean isLocal()
boolean isMigrationCandidate() throws CoreException
CoreException
- if a problem is encounteredILaunchConfigurationMigrationDelegate
boolean isWorkingCopy()
true
to this method can be safely cast to
org.eclipse.debug.core.ILaunchConfigurationWorkingCopy
.
This is a handle-only method.ILaunch launch(String mode, IProgressMonitor monitor) throws CoreException
Equivalent to calling launch(String, IProgressMontitor, boolean)
with a build
flag of false
.
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
. 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.CoreException
- if this method fails. Reasons include:ILaunch launch(String mode, IProgressMonitor monitor, boolean build) throws CoreException
If this configuration's launch delegate implements
ILaunchConfigurationDelegate2
, the launch delegate will
be consulted to provide a launch object for the launch,
perform pre-launch checks, and build before the launch.
If build
is true
and the associated launch
delegate does not implement ILaunchConfigurationDelegate2
an incremental workspace build will be performed before the launch
by the debug platform.
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).
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_LOCATOR_ID
and
ATTR_SOURCE_LOCATOR_MEMENTO
. 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).
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
. 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.build
- whether the workspace should be built before the launchCoreException
- if an exception occurs during the launch sequenceILaunch launch(String mode, IProgressMonitor monitor, boolean build, boolean register) throws CoreException
If this configuration's launch delegate implements
ILaunchConfigurationDelegate2
, the launch delegate will
be consulted to provide a launch object for the launch,
perform pre-launch checks, and build before the launch.
If build
is true
and the associated launch
delegate does not implement ILaunchConfigurationDelegate2
an incremental workspace build will be performed before the launch
by the debug platform.
When register
is true
, 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
register
is false
, 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.
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_LOCATOR_ID
and
ATTR_SOURCE_LOCATOR_MEMENTO
. 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).
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
. 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.build
- whether the workspace should be built before the launchregister
- whether to register the resulting launch with the launch managerCoreException
- if an exception occurs during the launch sequencevoid migrate() throws CoreException
CoreException
- if migration failsILaunchConfigurationMigrationDelegate
boolean supportsMode(String mode) throws CoreException
mode
- a mode in which a configuration can be launched, one of
the mode constants defined by ILaunchManager
- RUN_MODE
or
DEBUG_MODE
.CoreException
- if this method fails. Reasons include:
boolean isReadOnly()
Copyright (c) 2000, 2014 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.