ILaunchConfiguration


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.IFile;
19  import org.eclipse.core.resources.IResource;
20  import org.eclipse.core.runtime.CoreException;
21  import org.eclipse.core.runtime.IAdaptable;
22  import org.eclipse.core.runtime.IPath;
23  import org.eclipse.core.runtime.IProgressMonitor;
24  
25  /**
26   * A launch configuration describes how to launch an application.
27   * Each launch configuration is an instance of a type of launch
28   * configuration as described by a launch configuration type 
29   * extension. Each launch configuration has a launch configuration
30   * delegate which performs the actual launching of a
31   * configuration.
32   * <p>
33   * A launch configuration may be shared in a repository via
34   * standard VCM mechanisms, or may be stored locally, essentially
35   * making the launch configuration private for a single user.
36   * Thus, a launch configuration may stored as a file in the
37   * workspace (shared), or as a file in the debug plug-in's state
38   * location.
39   * </p>
40   * A launch configuration is a handle to its underlying storage.
41   * Methods annotated as "handle-only" do not require a configuration
42   * to exist. Methods that require an underlying configuration to exist
43   * throw a <code>CoreException</code> when an underlying configuration
44   * is missing.
45   * </p>
46   * <p>
47   * A launch configuration is modified by obtaining a working copy
48   * of a launch configuration, modifying the working copy, and then
49   * saving the working copy.
50   * </p>
51   * <p>
52   * This interface is not intended to be implemented by clients. Clients
53   * that define a launch configuration delegate extension implement the
54   * <code>ILaunchConfigurationDelegate</code> interface.
55   * </p>
56   * @see ILaunchConfigurationType
57   * @see org.eclipse.debug.core.model.ILaunchConfigurationDelegate
58   * @see ILaunchConfigurationWorkingCopy
59   * @since 2.0
60   */
61  public interface ILaunchConfiguration extends IAdaptable {
62      
63      /**
64       * The file extension for launch configuration files
65       * (value <code>"launch"</code>).
66       */
67      public static final String   LAUNCH_CONFIGURATION_FILE_EXTENSION = "launch"; //$NON-NLS-1$
68      
69      /**
70       * Launch configuration attribute storing an identifier of
71       * a persistable source locator extension. When this attribute is
72       * specified, a new source locator will be created automatically and
73       * associated with the launch for this configuration.
74       * 
75       * @see org.eclipse.debug.core.model.IPersistableSourceLocator
76       */
77      public static final String   ATTR_SOURCE_LOCATOR_ID = DebugPlugin.getUniqueIdentifier() + ".source_locator_id"; //$NON-NLS-1$
78      
79      /**
80       * Launch configuration attribute storing a memento of a 
81       * source locator. When this attribute is specified in
82       * conjunction with a source locator id, the source locator
83       * created for a launch will be initialized with this memento.
84       * When not specified, but a source locator id is specified,
85       * the source locator will be initialized to default values.
86       * 
87       * @see org.eclipse.debug.core.model.IPersistableSourceLocator
88       */
89      public static final String   ATTR_SOURCE_LOCATOR_MEMENTO = DebugPlugin.getUniqueIdentifier() + ".source_locator_memento"; //$NON-NLS-1$
90      
91      /**
92       * Returns whether the contents of this launch configuration are 
93       * equal to the contents of the given launch configuration.
94       * 
95       * @param configuration launch configuration
96       * @return whether the contents of this launch configuration are equal to the contents
97       * of the specified launch configuration.
98       */
99      public boolean contentsEqual(ILaunchConfiguration configuration);
100     
101     /**
102      * Returns a copy of this launch configuration, as a
103      * working copy, with the specified name. The new
104      * working copy does not refer back to this configuration
105      * as its original launch configuration (the working copy
106      * will return <code>null</code> for <code>getOriginal()</code>).
107      * When the working copy is saved it will not effect this
108      * launch configuration.
109      * 
110      * @param name the name of the copy
111      * @return a copy of this launch configuration
112      * @exception CoreException if this method fails. Reasons include:
113      * <ul>
114      * <li>An exception occurs while initializing the contents of the
115      * working copy from this configuration's underlying storage.</li>
116      * </ul>
117      * @see ILaunchConfigurationWorkingCopy#getOriginal()
118      */
119     public ILaunchConfigurationWorkingCopy copy(String   name) throws CoreException;
120     
121     /**
122      * Deletes this launch configuration. This configuration's underlying
123      * storage is deleted. Has no effect if this configuration
124      * does not exist.
125      * 
126      * @exception CoreException if this method fails. Reasons include:
127      * <ul>
128      * <li>An exception occurs while deleting this configuration's
129      *  underlying storage.</li>
130      * </ul>
131      */
132     public void delete() throws CoreException;
133     
134     /**
135      * Returns whether this launch configuration's underlying
136      * storage exists. This is a handle-only method.
137      * 
138      * @return whether this launch configuration's underlying
139      *  storage exists
140      */
141     public boolean exists();
142     
143     /**
144      * Returns the boolean-valued attribute with the given name.  
145      * Returns the given default value if the attribute is undefined.
146      *
147      * @param attributeName the name of the attribute
148      * @param defaultValue the value to use if no value is found
149      * @return the value or the default value if no value was found.
150      * @exception CoreException if this method fails. Reasons include:
151      * <ul>
152      * <li>An exception occurs while retrieving the attribute from
153      *  underlying storage.</li>
154      * <li>An attribute with the given name exists, but does not
155      *  have a boolean value</li>
156      * </ul>
157      */
158     public boolean getAttribute(String   attributeName, boolean defaultValue) throws CoreException;
159         
160     /**
161      * Returns the integer-valued attribute with the given name.  
162      * Returns the given default value if the attribute is undefined.
163      *
164      * @param attributeName the name of the attribute
165      * @param defaultValue the value to use if no value is found
166      * @return the value or the default value if no value was found.
167      * @exception CoreException if this method fails. Reasons include:
168      * <ul>
169      * <li>An exception occurs while retrieving the attribute from
170      *  underlying storage.</li>
171      * <li>An attribute with the given name exists, but does not
172      *  have an integer value</li>
173      * </ul>
174      */
175     public int getAttribute(String   attributeName, int defaultValue) throws CoreException;
176     
177     /**
178      * Returns the <code>java.util.List</code>-valued attribute with the given name.  
179      * Returns the given default value if the attribute is undefined.
180      *
181      * @param attributeName the name of the attribute
182      * @param defaultValue the value to use if no value is found
183      * @return the value or the default value if no value was found.
184      * @exception CoreException if this method fails. Reasons include:
185      * <ul>
186      * <li>An exception occurs while retrieving the attribute from
187      *  underlying storage.</li>
188      * <li>An attribute with the given name exists, but does not
189      *  have a List value</li>
190      * </ul>
191      */
192     public List   getAttribute(String   attributeName, List   defaultValue) throws CoreException;
193     
194     /**
195      * Returns the <code>java.util.Set</code>-valued attribute with the given name.  
196      * Returns the given default value if the attribute is undefined.
197      *
198      * @param attributeName the name of the attribute
199      * @param defaultValue the value to use if no value is found
200      * @return the value or the default value if no value was found.
201      * @exception CoreException if this method fails. Reasons include:
202      * <ul>
203      * <li>An exception occurs while retrieving the attribute from
204      *  underlying storage.</li>
205      * <li>An attribute with the given name exists, but does not
206      *  have a List value</li>
207      * </ul>
208      * 
209      * @since 3.3
210      */
211     public Set   getAttribute(String   attributeName, Set   defaultValue) throws CoreException;
212     
213     /**
214      * Returns the <code>java.util.Map</code>-valued attribute with the given name.  
215      * Returns the given default value if the attribute is undefined.
216      *
217      * @param attributeName the name of the attribute
218      * @param defaultValue the value to use if no value is found
219      * @return the value or the default value if no value was found.
220      * @exception CoreException if this method fails. Reasons include:
221      * <ul>
222      * <li>An exception occurs while retrieving the attribute from
223      *  underlying storage.</li>
224      * <li>An attribute with the given name exists, but does not
225      *  have a Map value</li>
226      * </ul>
227      */
228     public Map   getAttribute(String   attributeName, Map   defaultValue) throws CoreException;
229     
230     /**
231      * Returns the string-valued attribute with the given name.  
232      * Returns the given default value if the attribute is undefined.
233      *
234      * @param attributeName the name of the attribute
235      * @param defaultValue the value to use if no value is found
236      * @return the value or the default value if no value was found.
237      * @exception CoreException if this method fails. Reasons include:
238      * <ul>
239      * <li>An exception occurs while retrieving the attribute from
240      *  underlying storage.</li>
241      * <li>An attribute with the given name exists, but does not
242      *  have a String value</li>
243      * </ul>
244      */
245     public String   getAttribute(String   attributeName, String   defaultValue) throws CoreException;
246     
247     /**
248      * Returns a map containing the attributes in this launch configuration.
249      * Returns an empty map if this configuration has no attributes.
250      * <p>
251      * Modifying the map does not affect this launch configuration's attributes.
252      * A launch configuration is modified by obtaining a working copy of that
253      * launch configuration, modifying the working copy, and then saving the working
254      * copy.
255      * </p>
256      * @return a map of attribute keys and values
257      * @exception CoreException unable to generate/retrieve an attribute map
258      * @since 2.1
259      */
260     public Map   getAttributes() throws CoreException;
261     
262     /**
263      * Returns this launch configuration's type's category, or <code>null</code>
264      * if unspecified. This is a handle-only method.
265      * 
266      * @return this launch configuration's type's category, or <code>null</code>
267      * @exception CoreException if this method fails. Reasons include:
268      * <ul>
269      * <li>Unable to retrieve or instantiate this launch configuration's type.</li>
270      * </ul>
271      * @since 2.1
272      */
273     public String   getCategory() throws CoreException;
274     
275     /**
276      * Returns the file this launch configuration is stored
277      * in, or <code>null</code> if this configuration is stored
278      * locally with the workspace. This is a handle-only method.
279      * 
280      * @return the file this launch configuration is stored
281      *  in, or <code>null</code> if this configuration is stored
282      *  locally with the workspace
283      */
284     public IFile getFile();
285         
286     /**
287      * Returns the location of this launch configuration as a
288      * path. This is a handle-only method.
289      * 
290      * @return the location of this launch configuration as a
291      *  path
292      */
293     public IPath getLocation();
294     
295     /**
296      * Returns the resources this launch configuration is associated with or <code>null</code>
297      * if none. Clients contributing launch configuration types are responsible for maintaining
298      * resource mappings as appropriate.
299      * 
300      * @return the resources this launch configuration is associated with or <code>null</code>
301      * @throws CoreException unable to get the mapped resource
302      * @since 3.2
303      */
304     public IResource[] getMappedResources() throws CoreException;
305         
306     /**
307      * Returns a memento for this launch configuration, or <code>null</code>
308      * if unable to generate a memento for this configuration. A memento
309      * can be used to re-create a launch configuration, via the
310      * launch manager.
311      * 
312      * @return a memento for this configuration
313      * @see ILaunchManager#getLaunchConfiguration(String)
314      * @exception CoreException if an exception occurs generating this
315      *  launch configuration's memento 
316      */
317     public String   getMemento() throws CoreException;
318     
319     /**
320      * Returns the name of this launch configuration. This is
321      * a handle-only method.
322      * 
323      * @return the name of this launch configuration
324      */
325     public String   getName();        
326     
327     /**
328      * Returns the launch modes that have been set on this configuration.
329      * An empty set is returned if no specific launch modes have been set
330      * on a launch configuration. 
331      * <p>
332      * Setting launch modes on a configuration allows a launch to be
333      * performed in mixed mode - for example, debug and profile at the
334      * same time.
335      * </p>
336      * @return this configuration's launch modes, possibly an empty set
337      * @exception CoreException if an exception occurs retrieving modes
338      * @since 3.3
339      */
340     public Set   getModes() throws CoreException;
341     
342     /**
343      * Returns the preferred launch delegate that has been set on this
344      * configuration or <code>null</code> if one is not specified.
345      * 
346      * @param modes mode set for which a preferred delegate has been requested
347      * @return this configuration's preferred launch delegate for the specified mode set, or  
348      *  <code>null</code> if one is not specified
349      * @exception CoreException if an exception occurs retrieving preferred delegate
350      * @since 3.3
351      */
352     public ILaunchDelegate getPreferredDelegate(Set   modes) throws CoreException;
353     
354     /**
355      * Returns the type of this launch configuration. This is a
356      * handle-only method.
357      * 
358      * @return the type of this launch configuration
359      * @exception CoreException if this method fails. Reasons include:
360      * <ul>
361      * <li>Unable to retrieve or instantiate this launch configuration's type.</li>
362      * </ul>
363      * @see ILaunchConfigurationType
364      */
365     public ILaunchConfigurationType getType() throws CoreException; 
366     
367     /**
368      * Returns a working copy of this launch configuration.
369      * Since 3.3, if this method is called on a working copy, a nested working 
370      * copy is created (a working copy of a working copy).
371      * Changes to the working copy will be applied to this
372      * launch configuration when saved, or to the parent working copy. 
373      * The working copy will refer to this launch configuration as its original
374      * launch configuration, or the working copy it was created from.
375      * <p>
376      * When a working copy (B) is created from a working copy (A), the newly
377      * created working copy (B) is initialized with the attributes from
378      * the first working copy (A). Whenever a working copy is saved, it is written
379      * back to the working copy from which it was created: in this example working 
380      * copy B will write back to working copy A, and A will write back to the 
381      * original launch configuration.
382      * </p>
383      * @return a working copy of this launch configuration, or a nested working copy if called
384      * on an instance of <code>ILaunchConfigurationWorkingCopy</code>
385      * @exception CoreException if this method fails. Reasons include:
386      * <ul>
387      * <li>An exception occurs while initializing the contents of the
388      * working copy from this configuration's underlying storage.</li>
389      * </ul>
390      * @see ILaunchConfigurationWorkingCopy#getOriginal()
391      */
392     public ILaunchConfigurationWorkingCopy getWorkingCopy() throws CoreException;
393     
394     /**
395      * Returns whether this launch configuration is stored
396      * locally within the workspace. This is a handle-only method.
397      * 
398      * @return whether this launch configuration is stored
399      *  locally with the workspace
400      */
401     public boolean isLocal();
402     
403     /**
404      * Returns whether this launch configuration is a candidate for migration.
405      * 
406      * @return whether this launch configuration is a candidate for migration
407      * @throws CoreException
408      * @see ILaunchConfigurationMigrationDelegate
409      * @since 3.2
410      */
411     public boolean isMigrationCandidate() throws CoreException ;
412     
413     /**
414      * Returns whether this launch configuration is a working
415      * copy. Launch configurations which return <code>true</code>
416      * to this method can be safely cast to 
417      * <code>org.eclipse.debug.core.ILaunchConfigurationWorkingCopy</code>.
418      * This is a handle-only method.
419      * 
420      * @return whether this launch configuration is a working
421      *  copy
422      */
423     public boolean isWorkingCopy();
424     
425     /**
426      * Launches this configuration in the specified mode by delegating to
427      * this configuration's launch configuration delegate, and returns the
428      * resulting launch.
429      * <p>
430      * Equivalent to calling <code>launch(String, IProgressMontitor, boolean)</code>
431      * with a <code>build</code> flag of <code>false</code>.
432      * </p>
433      * @param mode the mode in which to launch, one of the mode constants
434      *  defined by <code>ILaunchManager</code> - <code>RUN_MODE</code> or <code>DEBUG_MODE</code>.
435      * @param monitor progress monitor, or <code>null</code>. Since 3.0, this
436      *  parameter is ignored. A cancelable progress monitor is provided by the Job
437      *  framework.
438      * @return the resulting launch
439      * @exception CoreException if this method fails. Reasons include:<ul>
440      * <li>unable to instantiate the underlying launch configuration delegate</li>
441      * <li>the launch fails (in the delegate)</code>
442      * </ul>
443      */
444     public ILaunch launch(String   mode, IProgressMonitor monitor) throws CoreException;
445     
446     /**
447      * Launches this configuration in the specified mode by delegating to
448      * this configuration's launch configuration delegate, and returns the
449      * resulting launch.
450      * <p>
451      * If this configuration's launch delegate implements
452      * <code>ILaunchConfigurationDelegate2</code>, the launch delegate will
453      * be consulted to provide a launch object for the launch,
454      * perform pre-launch checks, and build before the launch.
455      * If <code>build</code> is <code>true</code> and the associated launch
456      * delegate does not implement <code>ILaunchConfigurationDelegate2</code>
457      * an incremental workspace build will be performed before the launch
458      * by the debug platform.
459      * </p>
460      * <p>
461      * The resulting launch object is registered with the launch manager
462      * before passing it to this configuration's delegate launch method, for
463      * contributions (debug targets and processes).
464      * </p>
465      * <p>
466      * If the delegate contributes a source locator to the launch, that
467      * source locator is used. Otherwise an appropriate source locator is
468      * contributed to the launch  based on the values of
469      * <code>ATTR_SOURCE_LOCATOR_ID</code> and
470      * <code>ATTR_SOURCE_LOCATOR_MEMENTO</code>. If the launch is canceled (via
471      * the given progress monitor), the launch is removed from the launch
472      * manager. The launch is returned whether canceled or not. Invoking this
473      * method causes the underlying launch configuration delegate to be
474      * instantiated (if not already).
475      * </p>
476      * @param mode the mode in which to launch, one of the mode constants
477      *  defined by <code>ILaunchManager</code> - <code>RUN_MODE</code> or <code>DEBUG_MODE</code>.
478      * @param monitor progress monitor, or <code>null</code>. Since 3.0, this
479      *  parameter is ignored. A cancelable progress monitor is provided by the Job
480      *  framework.
481      * @param build whether the workspace should be built before the launch
482      * @return resulting launch
483      * @throws CoreException if an exception occurs during the launch sequence
484      * @since 3.0
485      */
486     public ILaunch launch(String   mode, IProgressMonitor monitor, boolean build) throws CoreException;   
487     
488     /**
489      * Launches this configuration in the specified mode by delegating to
490      * this configuration's launch configuration delegate, and returns the
491      * resulting launch.
492      * <p>
493      * If this configuration's launch delegate implements
494      * <code>ILaunchConfigurationDelegate2</code>, the launch delegate will
495      * be consulted to provide a launch object for the launch,
496      * perform pre-launch checks, and build before the launch.
497      * If <code>build</code> is <code>true</code> and the associated launch
498      * delegate does not implement <code>ILaunchConfigurationDelegate2</code>
499      * an incremental workspace build will be performed before the launch
500      * by the debug platform.
501      * </p>
502      * <p>
503      * When <code>register</code> is <code>true</code>, the resulting launch object
504      * is registered with the launch manager before passing it to this configuration's delegate
505      * launch method, for contributions (debug targets and processes). When
506      * <code>register</code> is <code>false</code>, the launch is not registered with
507      * the launch manager. Clients that launch configurations without registering
508      * a launch should register appropriate debug event filters to intercept events
509      * from unregistered launches.
510      * </p>
511      * <p>
512      * If the delegate contributes a source locator to the launch, that
513      * source locator is used. Otherwise an appropriate source locator is
514      * contributed to the launch  based on the values of
515      * <code>ATTR_SOURCE_LOCATOR_ID</code> and
516      * <code>ATTR_SOURCE_LOCATOR_MEMENTO</code>. If the launch is canceled (via
517      * the given progress monitor), the launch is removed from the launch
518      * manager. The launch is returned whether canceled or not. Invoking this
519      * method causes the underlying launch configuration delegate to be
520      * instantiated (if not already).
521      * </p>
522      * @param mode the mode in which to launch, one of the mode constants
523      *  defined by <code>ILaunchManager</code> - <code>RUN_MODE</code> or <code>DEBUG_MODE</code>.
524      * @param monitor progress monitor, or <code>null</code>. Since 3.0, this
525      *  parameter is ignored. A cancelable progress monitor is provided by the Job
526      *  framework.
527      * @param build whether the workspace should be built before the launch
528      * @param register whether to register the resulting launch with the launch manager
529      * @return resulting launch
530      * @throws CoreException if an exception occurs during the launch sequence
531      * @since 3.1
532      */
533     public ILaunch launch(String   mode, IProgressMonitor monitor, boolean build, boolean register) throws CoreException;
534     
535     /**
536      * Migrates this launch configuration to be compatible with current tooling.
537      * Has no effect if this configuration is not a candidate for migration.
538      * Migration is performed by a launch configuration migration delegate.
539      * @throws CoreException if migration fails
540      * @since 3.2
541      * @see ILaunchConfigurationMigrationDelegate
542      */
543     public void migrate() throws CoreException;
544     
545     /**
546      * Returns whether this launch configuration supports the
547      * specified mode. This is a handle-only method.
548      * 
549      * @param mode a mode in which a configuration can be launched, one of
550      *  the mode constants defined by <code>ILaunchManager</code> - <code>RUN_MODE</code> or
551      *  <code>DEBUG_MODE</code>.
552      * @return whether this launch configuration supports the
553      *  specified mode
554      * @exception CoreException if this method fails. Reasons include:
555      * <ul>
556      * <li>Unable to retrieve this launch configuration's type.</li>
557      * </ul>
558      */
559     public boolean supportsMode(String   mode) throws CoreException;
560     
561     /**
562      * Returns whether this launch configuration is read-only.
563      * A read-only configuration cannot be modified.
564      * 
565      * @return whether this configuration is read-only
566      * 
567      * @since 3.3
568      */
569     public boolean isReadOnly();    
570 }
571
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags