Eclipse Plug-in Developer Guide (Galileo) - ILaunchConfiguration (Eclipse Platform API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.debug.core
Interface ILaunchConfiguration

All Superinterfaces:: IAdaptable

All Known Subinterfaces:: ILaunchConfigurationWorkingCopy

public interface ILaunchConfiguration
extends IAdaptable
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. Methods annotated as "handle-only" do not require a configuration to exist. Methods that require an underlying configuration to exist throw a CoreException 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.

Since:: 2.0
See Also:: ILaunchConfigurationType, ILaunchConfigurationDelegate, ILaunchConfigurationWorkingCopy
Restriction:: This interface is not intended to be implemented by clients.
Restriction:: This interface is not intended to be extended by clients.

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.

Set getAttribute ( String attributeName, Set 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 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 getModes ()
          Returns the launch modes that have been set on this configuration.

String getName ()
          Returns the name of this launch configuration.

ILaunchDelegate getPreferredDelegate ( Set 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.

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

getAdapter

Field Detail

LAUNCH_CONFIGURATION_FILE_EXTENSION

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

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

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

contentsEqual

boolean contentsEqual(
ILaunchConfiguration configuration)

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

Parameters:: configuration - launch configuration
Returns:: whether the contents of this launch configuration are equal to the contents of the specified launch configuration.

copy


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.

delete

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.

exists

boolean exists()

Returns whether this launch configuration's underlying storage exists. This is a handle-only method.

Returns:: whether this launch configuration's underlying storage exists

getAttribute

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

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


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


Set getAttribute(
String attributeName,
                 
Set defaultValue)
                 throws 
CoreException

Returns the java.util.Set-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

Since:

3.3

getAttribute


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

getAttribute


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

getAttributes


Map getAttributes()
                  throws 
CoreException

Returns a map containing the attributes in this launch configuration. Returns an empty map if this configuration has no attributes.

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.

Returns:: a map of attribute keys and values
Throws:: CoreException - unable to generate/retrieve an attribute map
Since:: 2.1

getCategory


String getCategory()
                   throws 
CoreException

Returns this launch configuration's type's category, or null if unspecified. This is a handle-only method.

Returns:

this launch configuration's type's category, or null

Throws:


CoreException

- if this method fails. Reasons include:

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

Since:

2.1

getFile


IFile getFile()

Returns the file this launch configuration is stored in, or null if this configuration is stored locally with the workspace. This is a handle-only method.

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

getLocation


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.

Returns the location of this launch configuration as a path in the local file system or 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).

Returns:: the location of this launch configuration as a path file system or null if it cannot be mapped to a location in the local file system. Since 3.5, this method can return null.

getMappedResources


IResource[] getMappedResources()
                               throws 
CoreException

Returns the resources this launch configuration is associated with or null if none. Clients contributing launch configuration types are responsible for maintaining resource mappings as appropriate.

Returns:: the resources this launch configuration is associated with or null
Throws:: CoreException - unable to get the mapped resource
Since:: 3.2

getMemento


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)

getName


String getName()

Returns the name of this launch configuration. This is a handle-only method.

Returns:: the name of this launch configuration

getModes


Set getModes()
             throws 
CoreException

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.

Setting launch modes on a configuration allows a launch to be performed in mixed mode - for example, debug and profile at the same time.

Returns:: this configuration's launch modes, possibly an empty set
Throws:: CoreException - if an exception occurs retrieving modes
Since:: 3.3

getPreferredDelegate


ILaunchDelegate getPreferredDelegate(
Set modes)
                                     throws 
CoreException

Returns the preferred launch delegate that has been set on this configuration or null if one is not specified.

Parameters:: modes - mode set for which a preferred delegate has been requested
Returns:: this configuration's preferred launch delegate for the specified mode set, or null if one is not specified
Throws:: CoreException - if an exception occurs retrieving preferred delegate
Since:: 3.3

getType


ILaunchConfigurationType getType()
                                 throws 
CoreException

Returns the type of this launch configuration. This is a handle-only method.

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

getWorkingCopy


ILaunchConfigurationWorkingCopy getWorkingCopy()
                                               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.

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.

Returns:

a working copy of this launch configuration, or a nested working copy if called on an instance of ILaunchConfigurationWorkingCopy

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.

hasAttribute

boolean hasAttribute(
String attributeName)
                     throws 
CoreException

Returns whether this configuration contains an attribute with the given name.

Parameters:: attributeName - the name of the attribute
Returns:: true if this configuration has the specified attribute false otherwise
Throws:: CoreException - if unable to retrieve attributes
Since:: 3.4

isLocal

boolean isLocal()

Returns whether this launch configuration is stored locally within the workspace. This is a handle-only method.

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

isMigrationCandidate

boolean isMigrationCandidate()
                             throws 
CoreException

Returns whether this launch configuration is a candidate for migration.

Returns:: whether this launch configuration is a candidate for migration
Throws:: CoreException
Since:: 3.2
See Also:: ILaunchConfigurationMigrationDelegate

isWorkingCopy

boolean isWorkingCopy()

Returns whether this launch configuration is a working copy. Launch configurations which return true to this method can be safely cast to org.eclipse.debug.core.ILaunchConfigurationWorkingCopy. This is a handle-only method.

Returns:: whether this launch configuration is a working copy

launch


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.

Equivalent to calling launch(String, IProgressMontitor, boolean) with a build flag of false.

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. 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.

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)

launch


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.

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).

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. 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 launch
Returns:: resulting launch
Throws:: CoreException - if an exception occurs during the launch sequence
Since:: 3.0

launch


ILaunch launch(
String mode,
               
IProgressMonitor monitor,
               boolean build,
               boolean register)
               throws 
CoreException

Launches this configuration in the specified mode by delegating to this configuration's launch configuration delegate, and returns the resulting launch.

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.

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. 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 launch; register - whether to register the resulting launch with the launch manager
Returns:: resulting launch
Throws:: CoreException - if an exception occurs during the launch sequence
Since:: 3.1

migrate

void migrate()
             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 Also:: ILaunchConfigurationMigrationDelegate

supportsMode

boolean supportsMode(
String mode)
                     throws 
CoreException

Returns whether this launch configuration supports the specified mode. This is a handle-only method.

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.

isReadOnly

boolean isReadOnly()

Returns whether this launch configuration is read-only. A read-only configuration cannot be modified.

Returns:: whether this configuration is read-only
Since:: 3.3

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

org.eclipse.debug.core Interface ILaunchConfiguration

LAUNCH_CONFIGURATION_FILE_EXTENSION

ATTR_SOURCE_LOCATOR_ID

ATTR_SOURCE_LOCATOR_MEMENTO

contentsEqual

copy

delete

exists

getAttribute

getAttribute

getAttribute

getAttribute

getAttribute

getAttribute

getAttributes

getCategory

getFile

getLocation

getMappedResources

getMemento

getName

getModes

getPreferredDelegate

getType

getWorkingCopy

hasAttribute

isLocal

isMigrationCandidate

isWorkingCopy

launch

launch

launch

migrate

supportsMode

isReadOnly

org.eclipse.debug.core
Interface ILaunchConfiguration