Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES 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

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.

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.

Since:
  2.0
See Also:
  `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.
`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

    public 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

    public 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

    public 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

### launch

    public 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`. Since 3.0, this parameter is ignored. A cancellable progress monitor is provided by the Job framework.
  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

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

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

### supportsMode

    public boolean supportsMode(String mode)
                         throws CoreException

  Returns whether this launch configuration supports the specified mode.

  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.

### getName

    public String getName()

  Returns the name of this launch configuration.

  Returns:
    the name of this launch configuration

### getLocation

    public IPath getLocation()

  Returns the location of this launch configuration as a path.

  Returns:
    the location of this launch configuration as a path

### exists

    public boolean exists()

  Returns whether this launch configuration's underlying storage exists.

  Returns:
    whether this launch configuration's underlying storage exists

### getAttribute

    public 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

    public 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

### getAttribute

    public 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

    public 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

    public 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

### getFile

    public IFile getFile()

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

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

### getType

    public ILaunchConfigurationType getType()
                                     throws CoreException

  Returns the type of this launch configuration.

  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`

### isLocal

    public boolean isLocal()

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

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

### getWorkingCopy

    public ILaunchConfigurationWorkingCopy getWorkingCopy()
                                                   throws CoreException

  Returns a working copy of this launch configuration. Changes to the working copy will be applied to this launch configuration when saved. The working copy will refer to this launch configuration as its original launch configuration.

  Returns:
    a working 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.
  See Also:
    `ILaunchConfigurationWorkingCopy.getOriginal()`

### copy

    public 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.
  See Also:
    `ILaunchConfigurationWorkingCopy.getOriginal()`

### isWorkingCopy

    public 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`

  Returns:
    whether this launch configuration is a working copy

### delete

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

### getMemento

    public 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)`

### contentsEqual

    public boolean contentsEqual(ILaunchConfiguration configuration)

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

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

### getCategory

    public String getCategory()
                       throws CoreException

  Returns this launch configuration's type's category, or `null` if unspecified.

  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

### getAttributes

    public Map getAttributes()
                      throws CoreException

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

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
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, 2004. All rights reserved.