|
Eclipse Platform Release 3.1 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 aCoreException
when an underlying configuration
is missing.
A launch configuration is modified by obtaining a working copy of a launch configuration, modifying the working copy, and then saving the working copy.
This interface is not intended to be implemented by clients. Clients
that define a launch configuration delegate extension implement the
ILaunchConfigurationDelegate
interface.
ILaunchConfigurationType
,
ILaunchConfigurationDelegate
,
ILaunchConfigurationWorkingCopy
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.
|
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()
Returns the location of this launch configuration as a path. |
String |
getMemento()
Returns a memento for this launch configuration, or null
if unable to generate a memento for this configuration. |
String |
getName()
Returns the name of this launch configuration. |
ILaunchConfigurationType |
getType()
Returns the type of this launch configuration. |
ILaunchConfigurationWorkingCopy |
getWorkingCopy()
Returns a working copy of this launch configuration. |
boolean |
isLocal()
Returns whether this launch configuration is stored locally with the workspace. |
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. |
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 |
public static final String LAUNCH_CONFIGURATION_FILE_EXTENSION
"launch"
).
public static final String ATTR_SOURCE_LOCATOR_ID
IPersistableSourceLocator
public static final String ATTR_SOURCE_LOCATOR_MEMENTO
IPersistableSourceLocator
Method Detail |
public ILaunch launch(String mode, IProgressMonitor monitor) throws CoreException
Equivalent to calling launch(String, IProgressMontitor, boolean)
with a build
flag of false
.
mode
- the mode in which to launch, one of the mode constants
defined by ILaunchManager
- RUN_MODE
or DEBUG_MODE
.monitor
- progress monitor, or null
. Since 3.0, this
parameter is ignored. A cancellable progress monitor is provided by the Job
framework.
CoreException
- if this method fails. Reasons include:public ILaunch launch(String mode, IProgressMonitor monitor, boolean build) throws CoreException
If this configuration's launch delegate implements
ILaunchConfigurationDelegate2
, the launch delegate will
be consulted to provide a launch object for the launch,
perform pre-launch checks, and build before the launch.
If build
is true
and the associated launch
delegate does not implement ILaunchConfigurationDelegate2
an incremental workspace build will be performed before the launch
by the debug platform.
The resulting launch object is registered with the launch manager before passing it to this configuration's delegate launch method, for contributions (debug targets and processes).
If the delegate contributes a source locator to the launch, that
source locator is used. Otherwise an appropriate source locator is
contributed to the launch based on the values of
ATTR_SOURCE_LOCATOR_ID
and
ATTR_SOURCE_LOCATOR_MEMENTO
. If the launch is cancelled (via
the given progress monitor), the launch is removed from the launch
manager. The launch is returned whether cancelled or not. Invoking this
method causes the underlying launch configuration delegate to be
instantiated (if not already).
mode
- the mode in which to launch, one of the mode constants
defined by ILaunchManager
- RUN_MODE
or DEBUG_MODE
.monitor
- progress monitor, or null
. Since 3.0, this
parameter is ignored. A cancellable progress monitor is provided by the Job
framework.build
- whether the workspace should be built before the launch
CoreException
- if an exception occurrs during the launch sequencepublic ILaunch launch(String mode, IProgressMonitor monitor, boolean build, boolean register) throws CoreException
If this configuration's launch delegate implements
ILaunchConfigurationDelegate2
, the launch delegate will
be consulted to provide a launch object for the launch,
perform pre-launch checks, and build before the launch.
If build
is true
and the associated launch
delegate does not implement ILaunchConfigurationDelegate2
an incremental workspace build will be performed before the launch
by the debug platform.
When register
is true
, the resulting launch object
is registered with the launch manager before passing it to this configuration's delegate
launch method, for contributions (debug targets and processes). When
register
is false
, the launch is not registered with
the launch manager. Clients that launch configurations without registering
a launch should register appropiate debug event filters to intercept events
from unregistered launches.
If the delegate contributes a source locator to the launch, that
source locator is used. Otherwise an appropriate source locator is
contributed to the launch based on the values of
ATTR_SOURCE_LOCATOR_ID
and
ATTR_SOURCE_LOCATOR_MEMENTO
. If the launch is cancelled (via
the given progress monitor), the launch is removed from the launch
manager. The launch is returned whether cancelled or not. Invoking this
method causes the underlying launch configuration delegate to be
instantiated (if not already).
mode
- the mode in which to launch, one of the mode constants
defined by ILaunchManager
- RUN_MODE
or DEBUG_MODE
.monitor
- progress monitor, or null
. Since 3.0, this
parameter is ignored. A cancellable progress monitor is provided by the Job
framework.build
- whether the workspace should be built before the launchregister
- whether to register the resulting launch with the launch manager
CoreException
- if an exception occurrs during the launch sequencepublic boolean supportsMode(String mode) throws CoreException
mode
- a mode in which a configuration can be launched, one of
the mode constants defined by ILaunchManager
- RUN_MODE
or
DEBUG_MODE
.
CoreException
- if this method fails. Reasons include:
public String getName()
public IPath getLocation()
public boolean exists()
public int getAttribute(String attributeName, int defaultValue) throws CoreException
attributeName
- the name of the attributedefaultValue
- the value to use if no value is found
CoreException
- if this method fails. Reasons include:
public String getAttribute(String attributeName, String defaultValue) throws CoreException
attributeName
- the name of the attributedefaultValue
- the value to use if no value is found
CoreException
- if this method fails. Reasons include:
public boolean getAttribute(String attributeName, boolean defaultValue) throws CoreException
attributeName
- the name of the attributedefaultValue
- the value to use if no value is found
CoreException
- if this method fails. Reasons include:
public List getAttribute(String attributeName, List defaultValue) throws CoreException
java.util.List
-valued attribute with the given name.
Returns the given default value if the attribute is undefined.
attributeName
- the name of the attributedefaultValue
- the value to use if no value is found
CoreException
- if this method fails. Reasons include:
public Map getAttribute(String attributeName, Map defaultValue) throws CoreException
java.util.Map
-valued attribute with the given name.
Returns the given default value if the attribute is undefined.
attributeName
- the name of the attributedefaultValue
- the value to use if no value is found
CoreException
- if this method fails. Reasons include:
public IFile getFile()
null
if this configuration is stored
locally with the workspace. This is a handle-only method.
null
if this configuration is stored
locally with the workspacepublic ILaunchConfigurationType getType() throws CoreException
CoreException
- if this method fails. Reasons include:
ILaunchConfigurationType
public boolean isLocal()
public ILaunchConfigurationWorkingCopy getWorkingCopy() throws CoreException
CoreException
- if this method fails. Reasons include:
ILaunchConfigurationWorkingCopy.getOriginal()
public ILaunchConfigurationWorkingCopy copy(String name) throws CoreException
null
for getOriginal()
).
When the working copy is saved it will not effect this
launch configuration.
name
- the name of the copy
CoreException
- if this method fails. Reasons include:
ILaunchConfigurationWorkingCopy.getOriginal()
public boolean isWorkingCopy()
true
to this method can be safely cast to
org.eclipse.debug.core.ILaunchConfigurationWorkingCopy
.
This is a handle-only method.
public void delete() throws CoreException
CoreException
- if this method fails. Reasons include:
public String getMemento() throws CoreException
null
if unable to generate a memento for this configuration. A memento
can be used to re-create a launch configuration, via the
launch manager.
CoreException
- if an exception occurs generating this
launch configuration's mementoILaunchManager.getLaunchConfiguration(String)
public boolean contentsEqual(ILaunchConfiguration configuration)
public String getCategory() throws CoreException
null
if unspecified. This is a handle-only method.
null
CoreException
- if this method fails. Reasons include:
public Map getAttributes() throws CoreException
Modifying the map does not affect this launch configuration's attributes. A launch configuration is modified by obtaining a working copy of that launch configuration, modifying the working copy, and then saving the working copy.
CoreException
- unable to generate/retrieve an attribute map
|
Eclipse Platform Release 3.1 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Guidelines for using Eclipse APIs.
Copyright (c) IBM Corp. and others 2000, 2005. All rights reserved.