org.eclipse.debug.core

## Interface ILaunchManager

    public interface ILaunchManager

The launch manager manages the set of registered launches, maintaining a collection of active processes and debug targets. Clients interested in launch notification may register with the launch manager.

See Also:
  `ILaunch`, `ILaunchListener`
Restriction:
  This interface is not intended to be implemented by clients.
Restriction:
  This interface is not intended to be extended by clients.

### Field Summary

Fields
`static String` `ATTR_APPEND_ENVIRONMENT_VARIABLES` Launch configuration attribute name.
`static String` `ATTR_ENVIRONMENT_VARIABLES` Launch configuration attribute name.
`static String` `ATTR_PRIVATE` Launch configuration attribute - a boolean value that indicates if the launch configuration is 'private'.
`static String` `DEBUG_MODE` A launch in a special debug mode (value `"debug"`).
`static String` `PROFILE_MODE` A launch in a special profile mode (value `"profile"`).
`static String` `RUN_MODE` A launch in a normal, non-debug mode(value `"run"`).

### Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
`void` `addLaunch(ILaunch launch)` Adds the specified launch and notifies listeners.
`void` `addLaunchConfigurationListener(ILaunchConfigurationListener listener)` Adds the given launch configuration listener to the list of listeners notified when a launch configuration is added, removed, or changed.
`void` `addLaunches(ILaunch[] launches)` Adds the specified launch objects and notifies listeners.
`void` `addLaunchListener(ILaunchesListener listener)` Adds the given listener to the collection of registered launch listeners.
`void` `addLaunchListener(ILaunchListener listener)` Adds the given listener to the collection of registered launch listeners.
`String` `generateLaunchConfigurationName(String namePrefix)` Returns a string that can be used as the name of a launch configuration.
`String` `generateUniqueLaunchConfigurationNameFrom(String namePrefix)` Deprecated. since 3.6 clients should use the `generateLaunchConfigurationName(String)` method which will perform validation of the name and correct unsupported name parts.
`IDebugTarget[]` `getDebugTargets()` Returns the collection of debug targets currently registered with this launch manager.
`String` `getEncoding(ILaunchConfiguration configuration)` This method returns the character encoding to use when launching the specified `ILaunchConfiguration`.
`String[]` `getEnvironment(ILaunchConfiguration configuration)` Returns an array of environment variables to be used when launching the given configuration or `null` if unspecified.
`ILaunchConfiguration` `getLaunchConfiguration(IFile file)` Returns a handle to the launch configuration contained in the specified file.
`ILaunchConfiguration` `getLaunchConfiguration(String memento)` Returns a handle to the launch configuration specified by the given memento.
`ILaunchConfiguration[]` `getLaunchConfigurations()` Returns all launch configurations defined in the workspace.
`ILaunchConfiguration[]` `getLaunchConfigurations(ILaunchConfigurationType type)` Returns all launch configurations of the specified type defined in the workspace
`ILaunchConfigurationType` `getLaunchConfigurationType(String id)` Returns the launch configuration type extension with the specified id, or `null` if it does not exist.
`ILaunchConfigurationType[]` `getLaunchConfigurationTypes()` Returns all defined launch configuration type extensions
`ILaunch[]` `getLaunches()` Returns the collection of launches currently registered with this launch manager.
`ILaunchMode` `getLaunchMode(String mode)` Returns the launch mode registered with the given mode identifier, or `null` if none.
`ILaunchMode[]` `getLaunchModes()` Returns all registered launch modes.
`ILaunchConfiguration[]` `getMigrationCandidates()` Returns a collection of launch configurations that required migration to be compatible with current tooling.
`ILaunchConfiguration` `getMovedFrom(ILaunchConfiguration addedConfiguration)` When a launch configuration is created or moved, registered launch configuration listeners (see `ILaunchConfigurationListener`) are notified of an add notification for the new configuration.
`ILaunchConfiguration` `getMovedTo(ILaunchConfiguration removedConfiguration)` When a launch configuration is deleted or moved, registered launch configuration listeners (see `ILaunchConfigurationListener`) are notified of a remove notification for launch configuration that has been deleted.
`Map<String,String>` `getNativeEnvironment()` Returns the native system environment variables as a map of variable names and values (Strings).
`Map<String,String>` `getNativeEnvironmentCasePreserved()` Returns the native system environment variables as a map of variable names and values (Strings).
`IProcess[]` `getProcesses()` Returns the collection of processes currently registered with this launch manager.
`ISourceContainerType` `getSourceContainerType(String id)` Returns the source container type extension registered with the given unique identifier, or `null` if none.
`ISourceContainerType[]` `getSourceContainerTypes()` Returns all registered source container type extensions.
`ISourcePathComputer` `getSourcePathComputer(ILaunchConfiguration configuration)` Returns a source path computer to compute a default source lookup path for the given launch configuration, or `null` if a source path computer has not been registered for the associated launch configuration type.
`ISourcePathComputer` `getSourcePathComputer(String id)` Returns the source path computer extension registered with the given unique identifier, or `null` if none.
`boolean` `isExistingLaunchConfigurationName(String name)` Return `true` if there is a launch configuration with the specified name, `false` otherwise.
`boolean` `isRegistered(ILaunch launch)` Returns whether the given launch is currently registered.
`boolean` `isValidLaunchConfigurationName(String configname)` Returns if the given name is valid or not.
`IPersistableSourceLocator` `newSourceLocator(String identifier)` Creates and returns a new source locator of the specified type.
`void` `removeLaunch(ILaunch launch)` Removes the specified launch and notifies listeners.
`void` `removeLaunchConfigurationListener(ILaunchConfigurationListener listener)` Removes the given launch configuration listener from the list of listeners notified when a launch configuration is added, removed, or changed.
`void` `removeLaunches(ILaunch[] launches)` Removes the specified launch objects and notifies listeners.
`void` `removeLaunchListener(ILaunchesListener listener)` Removes the given listener from the collection of registered launch listeners.
`void` `removeLaunchListener(ILaunchListener listener)` Removes the given listener from the collection of registered launch listeners.

### Field Detail

#### RUN_MODE

    static final String RUN_MODE

A launch in a normal, non-debug mode(value `"run"`).

See Also:
  Constant Field Values

#### DEBUG_MODE

    static final String DEBUG_MODE

A launch in a special debug mode (value `"debug"`).

See Also:
  Constant Field Values

#### PROFILE_MODE

    static final String PROFILE_MODE

A launch in a special profile mode (value `"profile"`).

Since:
  3.0
See Also:
  Constant Field Values

#### ATTR_PRIVATE

    static final String ATTR_PRIVATE

Launch configuration attribute - a boolean value that indicates if the launch configuration is 'private'. A private configuration is one that does not appear in the user interface (launch history or the launch configuration dialog).

Since:
  3.6
See Also:
  Constant Field Values

#### ATTR_ENVIRONMENT_VARIABLES

    static final String ATTR_ENVIRONMENT_VARIABLES

Launch configuration attribute name. The value is a map of environment variables passed into Runtime.exec(...) when a launch configuration is launched. Default value is `null` which indicates the default environment should be used.

Since:
  3.0

#### ATTR_APPEND_ENVIRONMENT_VARIABLES

    static final String ATTR_APPEND_ENVIRONMENT_VARIABLES

Launch configuration attribute name. The value is a boolean value specifying whether the environment variables in a launch configuration should be appended to the native environment (i.e. when `true`), or if they should replace the environment (i.e. `false`). The default value is `true`.

Since:
  3.0

### Method Detail

#### addLaunch

    void addLaunch(ILaunch launch)

Adds the specified launch and notifies listeners. Has no effect if an identical launch is already registered.

Parameters:
  `launch` - the launch to add
Since:
  2.0

#### addLaunchConfigurationListener

    void addLaunchConfigurationListener(ILaunchConfigurationListener listener)

Adds the given launch configuration listener to the list of listeners notified when a launch configuration is added, removed, or changed. Has no effect if the given listener is already registered.

Parameters:
  `listener` - launch configuration listener
Since:
  2.0

#### addLaunches

    void addLaunches(ILaunch[] launches)

Adds the specified launch objects and notifies listeners. Has no effect on identical launch objects already registered.

Parameters:
  `launches` - the launch objects to add
Since:
  2.1

#### addLaunchListener

    void addLaunchListener(ILaunchesListener listener)

Adds the given listener to the collection of registered launch listeners. Has no effect if an identical listener is already registered.

Parameters:
  `listener` - the listener to register
Since:
  2.1

#### addLaunchListener

    void addLaunchListener(ILaunchListener listener)

Adds the given listener to the collection of registered launch listeners. Has no effect if an identical listener is already registered.

Parameters:
  `listener` - the listener to register

#### generateUniqueLaunchConfigurationNameFrom

    @Deprecated
    String generateUniqueLaunchConfigurationNameFrom(String namePrefix)

Deprecated. since 3.6 clients should use the `generateLaunchConfigurationName(String)` method which will perform validation of the name and correct unsupported name parts.
Return a String that can be used as the name of a launch configuration. The name is guaranteed to be unique (no existing launch configurations will have this name). The name that is returned uses the `namePrefix` as a starting point. If there is no existing launch configuration with this name, then `namePrefix` is returned. Otherwise, the value returned consists of the specified prefix plus some suffix that guarantees uniqueness.

Parameters:
  `namePrefix` - the String that the returned name must begin with
Returns:
  launch configuration name
Since:
  2.0

#### generateLaunchConfigurationName

    String generateLaunchConfigurationName(String namePrefix)

Returns a string that can be used as the name of a launch configuration. The name is guaranteed to be unique (no existing launch configurations will have this name). The name that is returned uses the `namePrefix` as a starting point. If there is no existing launch configuration with this name, then `namePrefix` is returned. Otherwise, the value returned consists of the specified prefix plus some suffix that guarantees uniqueness.

If the name prefix does not pass name validation any illegal parts of the name will be removed during the name generation. Illegal characters will be replaced with '_' and illegal names will be replaced with "_reserved_".

Parameters:
  `namePrefix` - the string that the returned name should begin with
Returns:
  launch configuration name
Since:
  3.6

#### isValidLaunchConfigurationName

    boolean isValidLaunchConfigurationName(String configname)
                                    throws IllegalArgumentException

Returns if the given name is valid or not. If an invalid name part is located an `IllegalArgumentException` is thrown.

Parameters:
  `configname` - the name to check
Returns:
  true if the given name is valid or throws an exception if not, where an invalid name is either a reserved system name (like 'aux' on Win 32) or the name contains invalid characters (like ':' or '/').
Throws:
  `IllegalArgumentException` - if the name is invalid, where an invalid is either a reserved system name (like 'aux' on Win 32) or the name contains invalid characters (like ':' or '/').
Since:
  3.6

#### getDebugTargets

    IDebugTarget[] getDebugTargets()

Returns the collection of debug targets currently registered with this launch manager.

Returns:
  an array of debug targets

#### getEnvironment

    String[] getEnvironment(ILaunchConfiguration configuration)
                     throws CoreException

Returns an array of environment variables to be used when launching the given configuration or `null` if unspecified. Each entry is of the form "`var_name=value`".

Parameters:
  `configuration` - launch configuration
Returns:
  an array of environment variables to use when launching the given configuration or `null` if unspecified
Throws:
  `CoreException` - if unable to access associated attribute or if unable to resolve a variable in an environment variable's value
Since:
  3.0

#### getEncoding

    String getEncoding(ILaunchConfiguration configuration)
                throws CoreException

This method returns the character encoding to use when launching the specified `ILaunchConfiguration`. The returned encoding can be derived from one of three places in the following order:

1. An attribute saved on the configuration itself (where no attribute means use the default encoding).
2. The mapped resources for the configuration, in the event one of them has a specific encoding that is not the workspace default. If there are more than one mapped resource we optimistically ask only the first resource for its encoding.
3. We ask the `ResourcesPlugin` for the workspace preference (which resolves back to the system property `file.encoding` if the user has made no changes to the workspace encoding preference).

Parameters:
  `configuration` - the `ILaunchConfiguration` to get the encoding for
Returns:
  the encoding to use when launching the specified `ILaunchConfiguration`
Throws:
  `CoreException` - if a problem is encountered
Since:
  3.4

#### getLaunchConfiguration

    ILaunchConfiguration getLaunchConfiguration(IFile file)

Returns a handle to the launch configuration contained in the specified file. This method does not check if the specified `IFile` is a launch configuration file or that it exists in the local or remote file system.

Parameters:
  `file` - launch configuration file
Returns:
  a handle to the launch configuration contained in the specified file
Since:
  2.0

#### getLaunchConfiguration

    ILaunchConfiguration getLaunchConfiguration(String memento)
                                         throws CoreException

Returns a handle to the launch configuration specified by the given memento. The configuration may not exist.

Parameters:
  `memento` - launch configuration memento
Returns:
  a handle to the launch configuration specified by the given memento
Throws:
  `CoreException` - if the given memento is invalid or an exception occurs parsing the memento
Since:
  2.0
See Also:
  `ILaunchConfiguration.getMemento()`

#### getLaunchConfigurations

    ILaunchConfiguration[] getLaunchConfigurations()
                                            throws CoreException

Returns all launch configurations defined in the workspace.

Returns:
  all launch configurations defined in the workspace
Throws:
  `CoreException` - if an exception occurs retrieving configurations
Since:
  2.0

#### getLaunchConfigurations

    ILaunchConfiguration[] getLaunchConfigurations(ILaunchConfigurationType type)
                                            throws CoreException

Returns all launch configurations of the specified type defined in the workspace

Parameters:
  `type` - a launch configuration type
Returns:
  all launch configurations of the specified type defined in the workspace
Throws:
  `CoreException` - if an error occurs while retrieving a launch configuration
Since:
  2.0

#### getLaunchConfigurationType

    ILaunchConfigurationType getLaunchConfigurationType(String id)

Returns the launch configuration type extension with the specified id, or `null` if it does not exist.

Parameters:
  `id` - unique identifier for a launch configuration type extension
Returns:
  the launch configuration type extension with the specified id, or `null` if it does not exist
Since:
  2.0

#### getLaunchConfigurationTypes

    ILaunchConfigurationType[] getLaunchConfigurationTypes()

Returns all defined launch configuration type extensions

Returns:
  all defined launch configuration type extensions
Since:
  2.0

#### getLaunches

    ILaunch[] getLaunches()

Returns the collection of launches currently registered with this launch manager.

Returns:
  an array of launches

#### getLaunchMode

    ILaunchMode getLaunchMode(String mode)

Returns the launch mode registered with the given mode identifier, or `null` if none.

Parameters:
  `mode` - mode identifier
Returns:
  launch mode or `null`
Since:
  3.0

#### getLaunchModes

    ILaunchMode[] getLaunchModes()

Returns all registered launch modes.

Returns:
  all registered launch modes
Since:
  3.0

#### getMigrationCandidates

    ILaunchConfiguration[] getMigrationCandidates()
                                           throws CoreException

Returns a collection of launch configurations that required migration to be compatible with current tooling.

Returns:
  a collection of launch configurations that required migration
Throws:
  `CoreException` - if an exception occurs determining migration candidates
Since:
  3.2

#### getMovedFrom

    ILaunchConfiguration getMovedFrom(ILaunchConfiguration addedConfiguration)

When a launch configuration is created or moved, registered launch configuration listeners (see `ILaunchConfigurationListener`) are notified of an add notification for the new configuration. If the notification is the result of a move this method will return a handle to the launch configuration that the added launch configuration was moved from. This method returns `null` if the added launch configuration was not the result of a rename or move. This information is only available during the add notification call back `launchConfigurationAdded`.

Renaming a configuration is considered the same as moving a configuration.

Parameters:
  `addedConfiguration` - a launch configuration for which an add notification is being broadcast
Returns:
  the launch configuration that the added launch configuration was moved from, or `null` if the add notification is not the result of a move
Since:
  2.1

#### getMovedTo

    ILaunchConfiguration getMovedTo(ILaunchConfiguration removedConfiguration)

When a launch configuration is deleted or moved, registered launch configuration listeners (see `ILaunchConfigurationListener`) are notified of a remove notification for launch configuration that has been deleted. If the notification is the result of a move this method will return a handle to the launch configuration that the removed launch configuration was moved to. This method returns `null` if the removed launch configuration was not the result of a rename or move. This information is only available during the add notification call back `launchConfigurationRemoved`.

Renaming a configuration is considered the same as moving a configuration.

Parameters:
  `removedConfiguration` - a launch configuration for which a remove notification is being broadcast
Returns:
  the launch configuration that the removed launch configuration was moved to, or `null` if the add notification is not the result of a move
Since:
  2.1

#### getNativeEnvironment

    Map<String,String> getNativeEnvironment()

Returns the native system environment variables as a map of variable names and values (Strings).

Note that WIN32 system environment preserves the case of variable names but is otherwise case insensitive. Depending on what you intend to do with the environment, the lack of normalization may or may not be create problems. On WIN32, this method normalizes mixed-case keys variable names to upper case. Use `getNativeEnvironmentCasePreserved()` instead to get a WIN32 system environment where the keys are the mixed-case variable names recorded by the OS.

Returns:
  the native system environment variables; on WIN32, mixed-case variable names (keys) have been normalized to upper case (key type: `String`; value type: `String`)
Since:
  3.0

#### getNativeEnvironmentCasePreserved

    Map<String,String> getNativeEnvironmentCasePreserved()

Returns the native system environment variables as a map of variable names and values (Strings).

Note that WIN32 system environment preserves the case of variable names but is otherwise case insensitive. Depending on what you intend to do with the environment, the lack of normalization may or may not be create problems. This method returns mixed-case keys using the variable names recorded by the OS. Use `getNativeEnvironment()` instead to get a WIN32 system environment where all keys have been normalized to upper case.

Returns:
  the native system environment variables; on WIN32, mixed-case variable names (keys) are returned without normalization (key type: `String`; value type: `String`)
Since:
  3.1

#### getProcesses

    IProcess[] getProcesses()

Returns the collection of processes currently registered with this launch manager.

Returns:
  an array of processes

#### getSourceContainerType

    ISourceContainerType getSourceContainerType(String id)

Returns the source container type extension registered with the given unique identifier, or `null` if none.

Parameters:
  `id` - unique identifier of a source container type extension
Returns:
  the source container type extension registered with the given unique identifier, or `null` if none
Since:
  3.0

#### getSourceContainerTypes

    ISourceContainerType[] getSourceContainerTypes()

Returns all registered source container type extensions.

Returns:
  all registered source container type extensions
Since:
  3.0

#### getSourcePathComputer

    ISourcePathComputer getSourcePathComputer(ILaunchConfiguration configuration)
                                       throws CoreException

Returns a source path computer to compute a default source lookup path for the given launch configuration, or `null` if a source path computer has not been registered for the associated launch configuration type.

Parameters:
  `configuration` - a launch configuration
Returns:
  a source path computer registered for the associated launch configurations type, or `null` if unspecified
Throws:
  `CoreException` - if an exception occurs while instantiating a source path computer
Since:
  3.0

#### getSourcePathComputer

    ISourcePathComputer getSourcePathComputer(String id)

Returns the source path computer extension registered with the given unique identifier, or `null` if none.

Parameters:
  `id` - source path computer identifier
Returns:
  the source path computer extension registered with the given unique identifier, or `null` if none
Since:
  3.0

#### isExistingLaunchConfigurationName

    boolean isExistingLaunchConfigurationName(String name)
                                       throws CoreException

Return `true` if there is a launch configuration with the specified name, `false` otherwise.

Parameters:
  `name` - the name of the launch configuration whose existence is being checked
Returns:
  whether a launch configuration already exists with the given name
Throws:
  `CoreException` - if unable to retrieve existing launch configuration names
Since:
  2.0

#### isRegistered

    boolean isRegistered(ILaunch launch)

Returns whether the given launch is currently registered.

Parameters:
  `launch` - a launch
Returns:
  whether the launch is currently registered
Since:
  3.1

#### newSourceLocator

    IPersistableSourceLocator newSourceLocator(String identifier)
                                        throws CoreException

Creates and returns a new source locator of the specified type.

Parameters:
  `identifier` - the identifier associated with a persistable source locator extension
Returns:
  a source locator
Throws:
  `CoreException` - if an exception occurs creating the source locator
Since:
  2.0

#### removeLaunch

    void removeLaunch(ILaunch launch)

Removes the specified launch and notifies listeners. Has no effect if an identical launch is not already registered.

Parameters:
  `launch` - the launch to remove
Since:
  2.0

#### removeLaunchConfigurationListener

    void removeLaunchConfigurationListener(ILaunchConfigurationListener listener)

Removes the given launch configuration listener from the list of listeners notified when a launch configuration is added, removed, or changed. Has no effect if the given listener is not already registered.

Parameters:
  `listener` - launch configuration listener
Since:
  2.0

#### removeLaunches

    void removeLaunches(ILaunch[] launches)

Removes the specified launch objects and notifies listeners. Has no effect on identical launch objects that are not already registered.

Parameters:
  `launches` - the launch objects to remove
Since:
  2.1

#### removeLaunchListener

    void removeLaunchListener(ILaunchesListener listener)

Removes the given listener from the collection of registered launch listeners. Has no effect if an identical listener is not already registered.

Parameters:
  `listener` - the listener to unregister
Since:
  2.1

#### removeLaunchListener

    void removeLaunchListener(ILaunchListener listener)

Removes the given listener from the collection of registered launch listeners. Has no effect if an identical listener is not already registered.

Parameters:
  `listener` - the listener to unregister