Eclipse Platform
Release 3.0

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.

Clients are not intended to implement this interface.

See Also:
ILaunch, ILaunchListener

Field Summary
static String ATTR_APPEND_ENVIRONMENT_VARIABLES
          Launch configuration attribute name.
static String ATTR_ENVIRONMENT_VARIABLES
          Launch configuration attribute name.
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
 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 generateUniqueLaunchConfigurationNameFrom(String namePrefix)
          Return a String that can be used as the name of a launch configuration.
 IDebugTarget[] getDebugTargets()
          Returns the collection of debug targets currently registered with this launch manager.
 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 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 getNativeEnvironment()
          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.
 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

public static final String RUN_MODE
A launch in a normal, non-debug mode(value "run").

See Also:
Constant Field Values

DEBUG_MODE

public static final String DEBUG_MODE
A launch in a special debug mode (value "debug").

See Also:
Constant Field Values

PROFILE_MODE

public static final String PROFILE_MODE
A launch in a special profile mode (value "profile").

Since:
3.0
See Also:
Constant Field Values

ATTR_ENVIRONMENT_VARIABLES

public 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

public 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

addLaunchListener

public void addLaunchListener(ILaunchListener listener)
Adds the given listener to the collection of registered launch listeners. Has no effect if an identical listener is already registerd.

Parameters:
listener - the listener to register

addLaunchListener

public void addLaunchListener(ILaunchesListener listener)
Adds the given listener to the collection of registered launch listeners. Has no effect if an identical listener is already registerd.

Parameters:
listener - the listener to register
Since:
2.1

removeLaunch

public 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

removeLaunches

public 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

getDebugTargets

public IDebugTarget[] getDebugTargets()
Returns the collection of debug targets currently registered with this launch manager.

Returns:
an array of debug targets

getLaunches

public ILaunch[] getLaunches()
Returns the collection of launches currently registered with this launch manager.

Returns:
an array of launches

getProcesses

public IProcess[] getProcesses()
Returns the collection of processes currently registered with this launch manager.

Returns:
an array of processes

addLaunch

public 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

addLaunches

public 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

removeLaunchListener

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

Parameters:
listener - the listener to deregister

removeLaunchListener

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

Parameters:
listener - the listener to deregister
Since:
2.1

getLaunchConfigurations

public 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

public 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 retreiving a launch configuration
Since:
2.0

getLaunchConfiguration

public ILaunchConfiguration getLaunchConfiguration(IFile file)
Returns a handle to the launch configuration contained in the specified file. The file is not verified to exist or contain a launch configuration.

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

getLaunchConfiguration

public ILaunchConfiguration getLaunchConfiguration(String memento)
                                            throws CoreException
Returns a handle to the launch configuration specified by the given memento. The configuration may not exist.

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

getLaunchConfigurationTypes

public ILaunchConfigurationType[] getLaunchConfigurationTypes()
Returns all defined launch configuration type extensions

Returns:
all defined launch configuration type extensions
Since:
2.0

getLaunchConfigurationType

public 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

addLaunchConfigurationListener

public 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

removeLaunchConfigurationListener

public 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

isExistingLaunchConfigurationName

public 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
Throws:
CoreException - if unable to retrieve existing launch configuration names
Since:
2.0

generateUniqueLaunchConfigurationNameFrom

public String generateUniqueLaunchConfigurationNameFrom(String namePrefix)
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
Since:
2.0

newSourceLocator

public 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

getMovedFrom

public 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

public 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

getLaunchModes

public ILaunchMode[] getLaunchModes()
Returns all registered launch modes.

Returns:
all registered launch modes
Since:
3.0

getLaunchMode

public 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

getEnvironment

public String[] getEnvironment(ILaunchConfiguration configuration)
                        throws CoreException
Returns an array of environment variables to be used when launching the given configuration or null if unspecified.

Parameters:
configuration - launch configuration
Throws:
CoreException - if unable to access associated attribute or if unable to resolve a variable in an environment variable's value
Since:
3.0

getSourcePathComputer

public 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

public 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

getNativeEnvironment

public Map getNativeEnvironment()
Returns the native system environment variables as a map of variable names and values (Strings). On WIN32, all keys (variable names) are returned in uppercase. Note that WIN32's environment is not case sensitive.

Returns:
the native system environment variables
Since:
3.0

getSourceContainerTypes

public ISourceContainerType[] getSourceContainerTypes()
Returns all registered source container type extensions.

Returns:
all registered source container type extensions
Since:
3.0

getSourceContainerType

public 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

Eclipse Platform
Release 3.0

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.