KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > debug > core > 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 JavaDoc;
15 import java.util.Map JavaDoc;
16 import java.util.Set JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getAttribute(String JavaDoc attributeName, List JavaDoc 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 JavaDoc getAttribute(String JavaDoc attributeName, Set JavaDoc 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 JavaDoc getAttribute(String JavaDoc attributeName, Map JavaDoc 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 JavaDoc getAttribute(String JavaDoc attributeName, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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
Popular Tags