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.
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
|
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
|
getNativeEnvironment
()
Returns the native system environment variables as a map of
variable names and values (Strings). |
Map
|
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. |
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. |
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_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
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
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
-
Returns:
- launch configuration name
-
Since:
- 2.0
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:
- An attribute saved on the configuration itself (where no attribute means use the default encoding).
- 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.
- 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
-
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 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 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
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.