ILaunchConfigurationWorkingCopy


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.debug.core;
12  
13  
14  import java.util.List  ;
15  import java.util.Map  ;
16  import java.util.Set  ;
17  
18  import org.eclipse.core.resources.IContainer;
19  import org.eclipse.core.resources.IResource;
20  import org.eclipse.core.runtime.CoreException;
21  import org.eclipse.core.runtime.IAdaptable;
22  
23  /**
24   * An editable copy of a launch configuration. Attributes of a
25   * launch configuration are modified by modifying the attributes
26   * of a working copy, and then saving the working copy.
27   * <p>
28   * Since 3.3, working copies can be nested. For example a working copy B can
29   * be created from the original launch configuration A. Then a nested working
30   * copy C can be created from working copy B. When the <code>doSave()</code> method
31   * is called on C, changes are written back to its parent working copy B without
32   * effecting the original launch configuration A. When <code>doSave()</code> is called
33   * on B, the changes are persisted back to the original A.
34   * </p>
35   * <p>
36   * This interface is not intended to be implemented by clients. Clients
37   * that define a launch configuration delegate extension implement the
38   * <code>ILaunchConfigurationDelegate</code> interface.
39   * </p>
40   * @see ILaunchConfiguration
41   * @see ILaunchConfigurationType
42   * @see org.eclipse.debug.core.model.ILaunchConfigurationDelegate
43   * @since 2.0
44   */
45  public interface ILaunchConfigurationWorkingCopy extends ILaunchConfiguration, IAdaptable {
46      
47      /**
48       * Returns whether this configuration has been modified
49       * since it was last saved or created.
50       * 
51       * @return whether this configuration has been modified
52       *  since it was last saved or created
53       */
54      public boolean isDirty();
55      
56      /**
57       * Saves this working copy to its underlying file and returns
58       * a handle to the resulting launch configuration.
59       * Has no effect if this configuration does not need saving.
60       * Creates the underlying file if not yet created.
61       * <p>
62       * Since 3.3, if this is a nested working copy, the contents of this working copy are
63       * saved to the parent working copy and the parent working copy is returned without
64       * effecting the original launch configuration.
65       * </p>
66       * @return handle to saved launch configuration
67       * @exception CoreException if an exception occurs while 
68       *  writing this configuration to its underlying file.
69       */
70      public ILaunchConfiguration doSave() throws CoreException;
71              
72      /**
73       * Sets the integer-valued attribute with the given name.  
74       *
75       * @param attributeName the name of the attribute, cannot be <code>null</code>
76       * @param value the value
77       */
78      public void setAttribute(String   attributeName, int value);
79      
80      /**
81       * Sets the String-valued attribute with the given name.
82       * If the value is <code>null</code>, the attribute is removed from
83       * this launch configuration.
84       *
85       * @param attributeName the name of the attribute, cannot be <code>null</code>
86       * @param value the value, or <code>null</code> if the attribute is to be undefined
87       */
88      public void setAttribute(String   attributeName, String   value);
89      
90      /**
91       * Sets the <code>java.util.List</code>-valued attribute with the given name.
92       * The specified List <em>must</em> contain only String-valued entries.
93       * If the value is <code>null</code>, the attribute is removed from
94       * this launch configuration.
95       *
96       * @param attributeName the name of the attribute, cannot be <code>null</code>
97       * @param value the value, or <code>null</code> if the attribute is to be undefined
98       */
99      public void setAttribute(String   attributeName, List   value);
100     
101     /**
102      * Sets the <code>java.util.Map</code>-valued attribute with the given name.
103      * The specified Map <em>must</em> contain only String keys and String values.
104      * If the value is <code>null</code>, the attribute is removed from
105      * this launch configuration.
106      *
107      * @param attributeName the name of the attribute, cannot be <code>null</code>
108      * @param value the value, or <code>null</code> if the attribute is to be undefined
109      */
110     public void setAttribute(String   attributeName, Map   value);
111     
112     /**
113      * Sets the boolean-valued attribute with the given name.  
114      *
115      * @param attributeName the name of the attribute, cannot be <code>null</code>
116      * @param value the value
117      */
118     public void setAttribute(String   attributeName, boolean value);  
119     
120     /**
121      * Returns the original launch configuration this working copy
122      * was created from or <code>null</code> if this is a new
123      * working copy created from a launch configuration type.
124      * 
125      * @return the original launch configuration, or <code>null</code>
126      */
127     public ILaunchConfiguration getOriginal();
128     
129     /**
130      * Renames this launch configuration to the specified name.
131      * The new name cannot be <code>null</code>. Has no effect if the name
132      * is the same as the current name. If this working copy is based
133      * on an existing launch configuration, this will cause
134      * the underlying launch configuration file to be renamed when
135      * this working copy is saved.
136      * 
137      * @param name the new name for this configuration 
138      */
139     public void rename(String   name);    
140     
141     /**
142      * Sets the container this launch configuration will be stored
143      * in when saved. When set to <code>null</code>, this configuration
144      * will be stored locally with the workspace. The specified
145      * container must exist, if specified.
146      * <p>
147      * If this configuration is changed from local to non-local,
148      * a file will be created in the specified container when
149      * saved. The local file associated with this configuration
150      * will be deleted.
151      * </p>
152      * <p>
153      * If this configuration is changed from non-local to local,
154      * a file will be created locally when saved.
155      * The original file associated with this configuration in
156      * the workspace will be deleted.
157      * </p>
158      * 
159      * @param container the container in which to store this
160      *  launch configuration, or <code>null</code> if this
161      *  configuration is to be stored locally
162      */
163     public void setContainer(IContainer container); 
164     
165     /**
166      * Sets the attributes of this launch configuration to be the ones contained
167      * in the given map. The values must be an instance of one of the following
168      * classes: <code>String</code>, <code>Integer</code>, or
169      * <code>Boolean</code>, <code>List</code>, <code>Map</code>. Attributes
170      * previously set on this launch configuration but not included in the given
171      * map are considered to be removals. Setting the given map to be
172      * <code>null</code> is equivalent to removing all attributes.
173      *
174      * @param attributes a map of attribute names to attribute values.
175      *  Attribute names are not allowed to be <code>null</code>
176      * @since 2.1
177      */
178     public void setAttributes(Map   attributes);
179     
180     /**
181      * Sets the resources associated with this launch configuration, possibly <code>null</code>.
182      * Clients contributing launch configuration types are responsible for maintaining
183      * resource mappings.
184      *  
185      * @param resources the resource to map to this launch configuration or <code>null</code>
186      * @since 3.2
187      */
188     public void setMappedResources(IResource[] resources);
189     
190     /**
191      * Set the launch modes for this configuration.
192      * Over-writes existing launch modes.
193      * <p>
194      * Setting launch modes on a configuration allows the configuration to
195      * be launched in a mixed mode - for example, debug and profile.
196      * </p>
197      * @param modes launch mode identifiers to set on this configuration
198      *  or <code>null</code> to clear mode settings
199      *  
200      * @since 3.3
201      */
202     public void setModes(Set   modes);
203     
204     /**
205      * Set the preferred launch delegates' id for the given mode set. Passing in <code>null</code> as a delegate
206      * id will cause the mapping for the specified mode set (if any) to be removed.
207      * 
208      * @param modes the set of modes to set this delegate id for
209      * @param delegateId the id of the delegate to associate as preferred for the specified mode set
210      *  or <code>null</code> to clear the setting
211      *  
212      * @since 3.3
213      */
214     public void setPreferredLaunchDelegate(Set   modes, String   delegateId);
215     
216     /**
217      * Adds the specified launch modes to this configuration's settings.
218      * <p>
219      * Setting launch modes on a configuration allows the configuration to
220      * be launched in a mixed mode - for example, debug and profile.
221      * </p>
222      * @param modes launch mode identifiers to append to the current set of
223      *  launch modes set on this configuration
224      * 
225      * @since 3.3
226      */
227     public void addModes(Set   modes);
228     
229     /**
230      * Removes the specified launch modes from this configuration's settings.
231      * <p>
232      * Setting launch modes on a configuration allows the configuration to
233      * be launched in a mixed mode - for example, debug and profile.
234      * </p>
235      * @param modes launch mode identifiers to remove from the current set of
236      *  launch modes set on this configuration
237      * 
238      * @since 3.3
239      */
240     public void removeModes(Set   modes);
241     
242     /**
243      * Returns the parent of this working copy or <code>null</code> if this working
244      * copy is not a nested copy of another working copy.
245      * 
246      * @return parent or <code>null</code>
247      * @since 3.3
248      */
249     public ILaunchConfigurationWorkingCopy getParent();
250 }
251
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags