Package org.eclipse.debug.core

## Interface ILaunchConfigurationWorkingCopy

All Superinterfaces:
  `IAdaptable`, `ILaunchConfiguration`

    public interface ILaunchConfigurationWorkingCopy
    extends ILaunchConfiguration, IAdaptable

An editable copy of a launch configuration. Attributes of a launch configuration are modified by modifying the attributes of a working copy, and then saving the working copy.

Since 3.3, working copies can be nested. For example a working copy B can be created from the original launch configuration A. Then a nested working copy C can be created from working copy B. When the `doSave()` method is called on C, changes are written back to its parent working copy B without effecting the original launch configuration A. When `doSave()` is called on B, the changes are persisted back to the original A.

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

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

### Field Summary

### Fields inherited from interface org.eclipse.debug.core.ILaunchConfiguration

`ATTR_SOURCE_LOCATOR_ID, ATTR_SOURCE_LOCATOR_MEMENTO, CONFIGURATION, LAUNCH_CONFIGURATION_FILE_EXTENSION, LAUNCH_CONFIGURATION_PROTOTYPE_FILE_EXTENSION, PROTOTYPE, UPDATE_NONE, UPDATE_PROTOTYPE_CHILDREN`

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `addModes​(Set<String> modes)` Adds the specified launch modes to this configuration's settings.
`void` `copyAttributes​(ILaunchConfiguration prototype)` Copies all attributes from the given prototype to this working.
`ILaunchConfiguration` `doSave()` Saves this working copy to its underlying file and returns a handle to the resulting launch configuration.
`ILaunchConfiguration` `doSave​(int flag)` Saves this working copy to its underlying file and returns a handle to the resulting launch configuration.
`ILaunchConfiguration` `getOriginal()` Returns the original launch configuration this working copy was created from or `null` if this is a new working copy created from a launch configuration type.
`ILaunchConfigurationWorkingCopy` `getParent()` Returns the parent of this working copy or `null` if this working copy is not a nested copy of another working copy.
`boolean` `isDirty()` Returns whether this configuration has been modified since it was last saved or created.
`Object` `removeAttribute​(String attributeName)` Removes the specified attribute from the this configuration and returns the previous value associated with the specified attribute name, or `null` if there was no mapping for the attribute.
`void` `removeModes​(Set<String> modes)` Removes the specified launch modes from this configuration's settings.
`void` `rename​(String name)` Renames this launch configuration to the specified name.
`void` `setAttribute​(String attributeName, boolean value)` Sets the boolean-valued attribute with the given name.
`void` `setAttribute​(String attributeName, int value)` Sets the integer-valued attribute with the given name.
`void` `setAttribute​(String attributeName, Object value)` Sets the valued attribute with the given name.
`void` `setAttribute​(String attributeName, String value)` Sets the String-valued attribute with the given name.
`void` `setAttribute​(String attributeName, List<String> value)` Sets the `java.util.List`-valued attribute with the given name.
`void` `setAttribute​(String attributeName, Map<String,​String> value)` Sets the `java.util.Map`-valued attribute with the given name.
`void` `setAttribute​(String attributeName, Set<String> value)` Sets the `java.util.Set`-valued attribute with the given name.
`void` `setAttributes​(Map<String,​? extends Object> attributes)` Sets the attributes of this launch configuration to be the ones contained in the given map.
`void` `setContainer​(IContainer container)` Sets the container this launch configuration will be stored in when saved.
`void` `setMappedResources​(IResource[] resources)` Sets the resources associated with this launch configuration, possibly `null`.
`void` `setModes​(Set<String> modes)` Set the launch modes for this configuration.
`void` `setPreferredLaunchDelegate​(Set<String> modes, String delegateId)` Set the preferred launch delegates' id for the given mode set.
`void` `setPrototype​(ILaunchConfiguration prototype, boolean copy)` Sets the prototype that this configuration is based on, possibly `null`, and optionally copies attributes from the prototype to this working copy.

### Methods inherited from interface org.eclipse.core.runtime.IAdaptable

`getAdapter`

### Methods inherited from interface org.eclipse.debug.core.ILaunchConfiguration

`contentsEqual, copy, delete, delete, exists, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttribute, getAttributes, getCategory, getFile, getKind, getLocation, getMappedResources, getMemento, getModes, getName, getPreferredDelegate, getPrototype, getPrototypeChildren, getPrototypeVisibleAttributes, getType, getWorkingCopy, hasAttribute, isAttributeModified, isLocal, isMigrationCandidate, isPrototype, isReadOnly, isWorkingCopy, launch, launch, launch, migrate, setPrototypeAttributeVisibility, supportsMode`

### Method Detail

#### isDirty

    boolean isDirty()

Returns whether this configuration has been modified since it was last saved or created.

Returns:
  whether this configuration has been modified since it was last saved or created

#### doSave

    ILaunchConfiguration doSave()
                         throws CoreException

Saves this working copy to its underlying file and returns a handle to the resulting launch configuration. Has no effect if this configuration does not need saving. Creates the underlying file if not yet created.

Since 3.3, if this is a nested working copy, the contents of this working copy are saved to the parent working copy and the parent working copy is returned without effecting the original launch configuration.

Equivalent to #doSave(UPDATE_NONE).

Returns:
  handle to saved launch configuration
Throws:
  `CoreException` - if an exception occurs while writing this configuration to its underlying file.
See Also:
  `doSave(int)`

#### doSave

    ILaunchConfiguration doSave​(int flag)
                         throws CoreException

Saves this working copy to its underlying file and returns a handle to the resulting launch configuration. Has no effect if this configuration does not need saving. Creates the underlying file if not yet created.

Since 3.3, if this is a nested working copy, the contents of this working copy are saved to the parent working copy and the parent working copy is returned without effecting the original launch configuration.

Updates any affected prototype children based on the given flag. When a working copy is renamed or moved to a new location, prototype children's back pointers will be updated to refer the proper configuration.

Parameters:
  `flag` - one of `ILaunchConfiguration.UPDATE_NONE` or `ILaunchConfiguration.UPDATE_PROTOTYPE_CHILDREN`
Returns:
  handle to saved launch configuration
Throws:
  `CoreException` - if an exception occurs while writing this configuration or any of its affected prototype children to underlying storage
Since:
  3.12

#### setAttribute

    void setAttribute​(String attributeName,
                      int value)

Sets the integer-valued attribute with the given name.

Parameters:
  `attributeName` - the name of the attribute, cannot be `null`
  `value` - the value

#### setAttribute

    void setAttribute​(String attributeName,
                      String value)

Sets the String-valued attribute with the given name. If the value is `null`, the attribute is removed from this launch configuration.

Parameters:
  `attributeName` - the name of the attribute, cannot be `null`
  `value` - the value, or `null` if the attribute is to be undefined

#### setAttribute

    void setAttribute​(String attributeName,
                      List<String> value)

Sets the `java.util.List`-valued attribute with the given name. The specified List must contain only String-valued entries. If the value is `null`, the attribute is removed from this launch configuration.

Parameters:
  `attributeName` - the name of the attribute, cannot be `null`
  `value` - the value, or `null` if the attribute is to be undefined

#### setAttribute

    void setAttribute​(String attributeName,
                      Map<String,​String> value)

Sets the `java.util.Map`-valued attribute with the given name. The specified Map must contain only String keys and String values. If the value is `null`, the attribute is removed from this launch configuration.

Parameters:
  `attributeName` - the name of the attribute, cannot be `null`
  `value` - the value, or `null` if the attribute is to be undefined

#### setAttribute

    void setAttribute​(String attributeName,
                      Set<String> value)

Sets the `java.util.Set`-valued attribute with the given name. The specified Set must contain only String values. If the value is `null`, the attribute is removed from this launch configuration.

Parameters:
  `attributeName` - the name of the attribute, cannot be `null`
  `value` - the value, or `null` if the attribute is to be undefined
Since:
  3.6

#### setAttribute

    void setAttribute​(String attributeName,
                      boolean value)

Sets the boolean-valued attribute with the given name.

Parameters:
  `attributeName` - the name of the attribute, cannot be `null`
  `value` - the value

#### setAttribute

    void setAttribute​(String attributeName,
                      Object value)

Sets the valued attribute with the given name.

Parameters:
  `attributeName` - the name of the attribute, cannot be `null`
  `value` - the value
Since:
  3.12

#### getOriginal

    ILaunchConfiguration getOriginal()

Returns the original launch configuration this working copy was created from or `null` if this is a new working copy created from a launch configuration type.

Returns:
  the original launch configuration, or `null`

#### rename

    void rename​(String name)

Renames this launch configuration to the specified name. The new name cannot be `null`. Has no effect if the name is the same as the current name. If this working copy is based on an existing launch configuration, this will cause the underlying launch configuration file to be renamed when this working copy is saved.

Parameters:
  `name` - the new name for this configuration

#### setContainer

    void setContainer​(IContainer container)

Sets the container this launch configuration will be stored in when saved. When set to `null`, this configuration will be stored locally with the workspace. The specified container must exist, if specified.

If this configuration is changed from local to non-local, a file will be created in the specified container when saved. The local file associated with this configuration will be deleted.

If this configuration is changed from non-local to local, a file will be created locally when saved. The original file associated with this configuration in the workspace will be deleted.

Parameters:
  `container` - the container in which to store this launch configuration, or `null` if this configuration is to be stored locally

#### setAttributes

    void setAttributes​(Map<String,​? extends Object> attributes)

Sets the attributes of this launch configuration to be the ones contained in the given map. The values must be an instance of one of the following classes: `String`, `Integer`, or `Boolean`, `List`, `Map`. Attributes previously set on this launch configuration but not included in the given map are considered to be removals. Setting the given map to be `null` is equivalent to removing all attributes.

Parameters:
  `attributes` - a map of attribute names to attribute values. Attribute names are not allowed to be `null`
Since:
  2.1

#### setMappedResources

    void setMappedResources​(IResource[] resources)

Sets the resources associated with this launch configuration, possibly `null`. Clients contributing launch configuration types are responsible for maintaining resource mappings.

Parameters:
  `resources` - the resource to map to this launch configuration or `null`
Since:
  3.2

#### setModes

    void setModes​(Set<String> modes)

Set the launch modes for this configuration. Over-writes existing launch modes.

Setting launch modes on a configuration allows the configuration to be launched in a mixed mode - for example, `debug` and `profile`.

Parameters:
  `modes` - launch mode identifiers to set on this configuration or `null` to clear mode settings
Since:
  3.3

#### setPreferredLaunchDelegate

    void setPreferredLaunchDelegate​(Set<String> modes,
                                    String delegateId)

Set the preferred launch delegates' id for the given mode set. Passing in `null` as a delegate id will cause the mapping for the specified mode set (if any) to be removed.

Parameters:
  `modes` - the set of modes to set this delegate id for
  `delegateId` - the id of the delegate to associate as preferred for the specified mode set or `null` to clear the setting
Since:
  3.3

#### addModes

    void addModes​(Set<String> modes)

Adds the specified launch modes to this configuration's settings.

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

Parameters:
  `modes` - launch mode identifiers to append to the current set of launch modes set on this configuration
Since:
  3.3

#### removeModes

    void removeModes​(Set<String> modes)

Removes the specified launch modes from this configuration's settings.

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

Parameters:
  `modes` - launch mode identifiers to remove from the current set of launch modes set on this configuration
Since:
  3.3

#### removeAttribute

    Object removeAttribute​(String attributeName)

Removes the specified attribute from the this configuration and returns the previous value associated with the specified attribute name, or `null` if there was no mapping for the attribute. Note that for int's and booleans, corresponding Integer and Boolean objects are returned.

This method allows non-object attributes to be removed.

Parameters:
  `attributeName` - the name of the attribute to remove
Returns:
  previous value of the attribute or `null`
Since:
  3.4

#### getParent

    ILaunchConfigurationWorkingCopy getParent()

Returns the parent of this working copy or `null` if this working copy is not a nested copy of another working copy.

Returns:
  parent or `null`
Since:
  3.3

#### copyAttributes

    void copyAttributes​(ILaunchConfiguration prototype)
                 throws CoreException

Copies all attributes from the given prototype to this working. Overwrites any existing attributes with the same key.

Parameters:
  `prototype` - configuration prototype
Throws:
  `CoreException` - if unable to retrieve attributes from the prototype
Since:
  3.12

#### setPrototype

    void setPrototype​(ILaunchConfiguration prototype,
                      boolean copy)
               throws CoreException

Sets the prototype that this configuration is based on, possibly `null`, and optionally copies attributes from the prototype to this working copy.

When the specified prototype is `null`, this working copy is no longer associated with any prototype.

Parameters:
  `prototype` - prototype or `null`
  `copy` - whether to copy attributes from the prototype to this working copy. Has no effect when prototype is `null`
Throws:
  `CoreException` - if
  - unable to generate a memento for the given configuration or copy its attributes
  - if attempting to set a prototype attribute on an existing prototype - prototypes cannot be nested
Since:
  3.12