Package 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. Methods annotated as "handle-only" do not require a configuration to exist. Methods that require an underlying configuration to exist throw a CoreException 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.

    Clients that define a launch configuration delegate extension implement the ILaunchConfigurationDelegate interface.

    Since:
    2.0
    See Also:
    ILaunchConfigurationType, ILaunchConfigurationDelegate, ILaunchConfigurationWorkingCopy
    Restriction:
    This interface is not intended to be implemented by clients.
    Restriction:
    This interface is not intended to be extended by clients.

    • Field Detail

      • LAUNCH_CONFIGURATION_FILE_EXTENSION

        static final String LAUNCH_CONFIGURATION_FILE_EXTENSION
        The file extension for launch configuration files (value "launch").
        See Also:
        Constant Field Values

      • LAUNCH_CONFIGURATION_PROTOTYPE_FILE_EXTENSION

        static final String LAUNCH_CONFIGURATION_PROTOTYPE_FILE_EXTENSION
        The file extension for launch configuration prototype files (value "prototype").
        Since:
        3.12
        See Also:
        Constant Field Values

      • ATTR_SOURCE_LOCATOR_ID

        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

        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

      • UPDATE_NONE

        static final int UPDATE_NONE
        Flag indicating that only this configuration is to be modified by an operation. Any prototype children referring to this configuration will not be modified.
        Since:
        3.12
        See Also:
        Constant Field Values

      • UPDATE_PROTOTYPE_CHILDREN

        static final int UPDATE_PROTOTYPE_CHILDREN
        Flag indicating that this prototype and any effected prototype children of this prototype should be updated when this prototype is modified.
        Since:
        3.12
        See Also:
        Constant Field Values

      • CONFIGURATION

        static final int CONFIGURATION
        Type constant (bit mask value 1) which identifies a launch configuration.
        Since:
        3.12
        See Also:
        getKind(), Constant Field Values

      • PROTOTYPE

        static final int PROTOTYPE
        Type constant (bit mask value 2) which identifies a launch configuration prototype.
        Since:
        3.12
        See Also:
        getKind(), Constant Field Values

    • Method Detail

      • contentsEqual

        boolean contentsEqual​(ILaunchConfiguration configuration)
        Returns whether the contents of this launch configuration are equal to the contents of the given launch configuration.
        Parameters:
        configuration - launch configuration
        Returns:
        whether the contents of this launch configuration are equal to the contents of the specified launch configuration.

      • copy

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

      • delete

        void delete()
     throws CoreException
        Deletes this launch configuration. This configuration's underlying storage is deleted. Has no effect if this configuration does not exist.

        Equivalent to #delete(UPDATE_NONE)

        Throws:
        CoreException - if this method fails. Reasons include:
        • An exception occurs while deleting this configuration's underlying storage.

      • delete

        void delete​(int flag)
     throws CoreException
        Deletes this launch configuration. This configuration's underlying storage is deleted. Has no effect if this configuration does not exist.

        When UPDATE_PROTOTYPE_CHILDREN is specified, back pointers to this prototype are cleared in any prototype children.

        Parameters:
        flag - one of UPDATE_NONE or UPDATE_PROTOTYPE_CHILDREN
        Throws:
        CoreException - if this method fails. Reasons include:
        • An exception occurs while deleting this configuration's underlying storage or updating any prototype children.
        Since:
        3.12

      • exists

        boolean exists()
        Returns whether this launch configuration's underlying storage exists. This is a handle-only method.
        Returns:
        whether this launch configuration's underlying storage exists

      • getAttribute

        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

        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

        List<String> getAttribute​(String attributeName,
                          List<String> 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

        Set<String> getAttribute​(String attributeName,
                         Set<String> defaultValue)
                  throws CoreException
        Returns the java.util.Set-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
        Since:
        3.3

      • getAttribute

        Map<String,​String> getAttribute​(String attributeName,
                                      Map<String,​String> 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

      • getAttribute

        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

      • getAttributes

        Map<String,​Object> getAttributes()
                                throws CoreException
        Returns a map containing the attributes in this launch configuration. Returns an empty map if this configuration has no attributes.

        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.

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

      • getCategory

        String getCategory()
            throws CoreException
        Returns this launch configuration's type's category, or null if unspecified. This is a handle-only method.
        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

      • getFile

        IFile getFile()
        Returns the file this launch configuration is stored in, or null if this configuration is stored locally with the workspace. This is a handle-only method.
        Returns:
        the file this launch configuration is stored in, or null if this configuration is stored locally with the workspace

      • getLocation

        @Deprecated
IPath getLocation()
        Deprecated.
        Since a launch configuration does not need to be stored in the local file system, this attribute should no longer be used to identify a launch configuration.
        Returns the location of this launch configuration as a path in the local file system or null if it cannot be mapped to a location in the local file system. This is a handle-only method.

        Since 3.5, this method can return null. For example, when a launch configuration is stored in the workspace as an IFile in an external file system (EFS).

        Returns:
        the location of this launch configuration as a path file system or null if it cannot be mapped to a location in the local file system. Since 3.5, this method can return null.

      • getMappedResources

        IResource[] getMappedResources()
                        throws CoreException
        Returns the resources this launch configuration is associated with or null if none. Clients contributing launch configuration types are responsible for maintaining resource mappings as appropriate.
        Returns:
        the resources this launch configuration is associated with or null
        Throws:
        CoreException - unable to get the mapped resource
        Since:
        3.2

      • getMemento

        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)

      • getName

        String getName()
        Returns the name of this launch configuration. This is a handle-only method.
        Returns:
        the name of this launch configuration

      • getModes

        Set<String> getModes()
              throws CoreException
        Returns the launch modes that have been set on this configuration. An empty set is returned if no specific launch modes have been set on a launch configuration.

        Setting launch modes on a configuration allows a launch to be performed in mixed mode - for example, debug and profile at the same time.

        Returns:
        this configuration's launch modes, possibly an empty set
        Throws:
        CoreException - if an exception occurs retrieving modes
        Since:
        3.3

      • getPreferredDelegate

        ILaunchDelegate getPreferredDelegate​(Set<String> modes)
                              throws CoreException
        Returns the preferred launch delegate that has been set on this configuration or null if one is not specified.
        Parameters:
        modes - mode set for which a preferred delegate has been requested
        Returns:
        this configuration's preferred launch delegate for the specified mode set, or null if one is not specified
        Throws:
        CoreException - if an exception occurs retrieving preferred delegate
        Since:
        3.3

      • getWorkingCopy

        ILaunchConfigurationWorkingCopy getWorkingCopy()
                                        throws CoreException
        Returns a working copy of this launch configuration. Since 3.3, if this method is called on a working copy, a nested working copy is created (a working copy of a working copy). Changes to the working copy will be applied to this launch configuration when saved, or to the parent working copy. The working copy will refer to this launch configuration as its original launch configuration, or the working copy it was created from.

        When a working copy (B) is created from a working copy (A), the newly created working copy (B) is initialized with the attributes from the first working copy (A). Whenever a working copy is saved, it is written back to the working copy from which it was created: in this example working copy B will write back to working copy A, and A will write back to the original launch configuration.

        Returns:
        a working copy of this launch configuration, or a nested working copy if called on an instance of ILaunchConfigurationWorkingCopy
        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()

      • hasAttribute

        boolean hasAttribute​(String attributeName)
              throws CoreException
        Returns whether this configuration contains an attribute with the given name.
        Parameters:
        attributeName - the name of the attribute
        Returns:
        true if this configuration has the specified attribute false otherwise
        Throws:
        CoreException - if unable to retrieve attributes
        Since:
        3.4

      • isLocal

        boolean isLocal()
        Returns whether this launch configuration is stored locally within the workspace. This is a handle-only method.
        Returns:
        whether this launch configuration is stored locally with the workspace

      • isMigrationCandidate

        boolean isMigrationCandidate()
                      throws CoreException
        Returns whether this launch configuration is a candidate for migration.
        Returns:
        whether this launch configuration is a candidate for migration
        Throws:
        CoreException - if a problem is encountered
        Since:
        3.2
        See Also:
        ILaunchConfigurationMigrationDelegate

      • isWorkingCopy

        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. This is a handle-only method.
        Returns:
        whether this launch configuration is a working copy

      • launch

        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. A cancelable progress monitor is provided by the Job framework. It should be noted that the setCanceled(boolean) method should never be called on the provided monitor or the monitor passed to any delegates from this method; due to a limitation in the progress monitor framework using the setCanceled method can cause entire workspace batch jobs to be canceled, as the canceled flag is propagated up the top-level parent monitor. The provided monitor is not guaranteed to have been started.
        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

        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 canceled (via the given progress monitor), the launch is removed from the launch manager. The launch is returned whether canceled 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. A cancelable progress monitor is provided by the Job framework. It should be noted that the setCanceled(boolean) method should never be called on the provided monitor or the monitor passed to any delegates from this method; due to a limitation in the progress monitor framework using the setCanceled method can cause entire workspace batch jobs to be canceled, as the canceled flag is propagated up the top-level parent monitor. The provided monitor is not guaranteed to have been started.
        build - whether the workspace should be built before the launch
        Returns:
        resulting launch
        Throws:
        CoreException - if an exception occurs during the launch sequence
        Since:
        3.0

      • launch

        ILaunch launch​(String mode,
               IProgressMonitor monitor,
               boolean build,
               boolean register)
        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.

        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 appropriate 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 canceled (via the given progress monitor), the launch is removed from the launch manager. The launch is returned whether canceled 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. A cancelable progress monitor is provided by the Job framework. It should be noted that the setCanceled(boolean) method should never be called on the provided monitor or the monitor passed to any delegates from this method; due to a limitation in the progress monitor framework using the setCanceled method can cause entire workspace batch jobs to be canceled, as the canceled flag is propagated up the top-level parent monitor. The provided monitor is not guaranteed to have been started.
        build - whether the workspace should be built before the launch
        register - whether to register the resulting launch with the launch manager
        Returns:
        resulting launch
        Throws:
        CoreException - if an exception occurs during the launch sequence
        Since:
        3.1

      • migrate

        void migrate()
      throws CoreException
        Migrates this launch configuration to be compatible with current tooling. Has no effect if this configuration is not a candidate for migration. Migration is performed by a launch configuration migration delegate.
        Throws:
        CoreException - if migration fails
        Since:
        3.2
        See Also:
        ILaunchConfigurationMigrationDelegate

      • supportsMode

        boolean supportsMode​(String mode)
              throws CoreException
        Returns whether this launch configuration supports the specified mode. This is a handle-only method.
        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.

      • isReadOnly

        boolean isReadOnly()
        Returns whether this launch configuration is read-only. A read-only configuration cannot be modified.
        Returns:
        whether this configuration is read-only
        Since:
        3.3

      • getPrototype

        ILaunchConfiguration getPrototype()
                           throws CoreException
        Returns the prototype this launch configuration was created from or null if none.
        Returns:
        the prototype this launch configuration was created from or null if none
        Throws:
        CoreException - if the prototype could not be retrieved or no longer exists
        Since:
        3.12

      • isAttributeModified

        boolean isAttributeModified​(String attribute)
                     throws CoreException
        Check if the given attribute has the same value than the one from its prototype.
        Parameters:
        attribute - the attribute to check
        Returns:
        true if the attribute is modified, false otherwise.
        Throws:
        CoreException - if an exception occurs while checking
        Since:
        3.12

      • isPrototype

        boolean isPrototype()
        Returns whether this configuration is a prototype.
        Returns:
        whether this configuration is a prototype
        Since:
        3.12

      • getPrototypeChildren

        Collection<ILaunchConfiguration> getPrototypeChildren()
                                               throws CoreException
        Returns all configurations made from this prototype, possibly an empty collection.
        Returns:
        all configurations made from this prototype
        Throws:
        CoreException - if unable to retrieve this prototype's children
        Since:
        3.12

      • getKind

        int getKind()
     throws CoreException
        Returns this configuration's kind. One of CONFIGURATION or PROTOTYPE.
        Returns:
        this configuration's kind
        Throws:
        CoreException - if unable to retrieve this configuration's kind
        Since:
        3.12
        See Also:
        CONFIGURATION, PROTOTYPE

      • getPrototypeVisibleAttributes

        Set<String> getPrototypeVisibleAttributes()
                                   throws CoreException
        Get the visible attributes of this prototype (return null if the launch configuration is not a prototype).
        Returns:
        the visible attributes of this prototype (return null if the launch configuration is not a prototype).
        Throws:
        CoreException - if unable to retrieve this prototype's visible attribute set.
        Since:
        3.12

      • setPrototypeAttributeVisibility

        void setPrototypeAttributeVisibility​(String attribute,
                                     boolean visible)
                              throws CoreException
        Set the visibility of the given prototype's attribute.
        Parameters:
        attribute - the attribute to set
        visible - the visibility
        Throws:
        CoreException - if unable to set this prototype's attribute visibility
        Since:
        3.12