Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: 5bc8a81723e3fe47baafbc07fb850e256d59debb (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
/*******************************************************************************
 * Copyright (c) 2000, 2017 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *     Axel Richard (Obeo) - Bug 41353 - Launch configurations prototypes
 *******************************************************************************/
package org.eclipse.debug.core;


import java.util.Map;

import org.eclipse.core.resources.IFile;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.debug.core.model.IDebugTarget;
import org.eclipse.debug.core.model.IPersistableSourceLocator;
import org.eclipse.debug.core.model.IProcess;
import org.eclipse.debug.core.sourcelookup.ISourceContainerType;
import org.eclipse.debug.core.sourcelookup.ISourcePathComputer;

/**
 * The launch manager manages the set of registered launches, maintaining
 * a collection of active processes and debug targets. Clients interested
 * in launch notification may register with the launch manager.
 * @see ILaunch
 * @see ILaunchListener
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface ILaunchManager {
	/**
	 * A launch in a normal, non-debug mode(value <code>"run"</code>).
	 */
	String RUN_MODE= "run"; //$NON-NLS-1$
	/**
	 * A launch in a special debug mode (value <code>"debug"</code>).
	 */
	String DEBUG_MODE= "debug"; //$NON-NLS-1$
	/**
	 * A launch in a special profile mode (value <code>"profile"</code>).
	 * @since 3.0
	 */
	String PROFILE_MODE= "profile"; //$NON-NLS-1$

	/**
	 * Launch configuration attribute - a boolean value that indicates if the
	 * launch configuration is 'private'. A private configuration is one that
	 * does not appear in the user interface (launch history or the launch
	 * configuration dialog).
	 *
	 * @since 3.6
	 */
	String ATTR_PRIVATE = "org.eclipse.debug.ui.private"; //$NON-NLS-1$

	/**
	 * Launch configuration attribute name. The value is a map of environment
	 * variables passed into Runtime.exec(...) when a launch configuration is launched.
	 * Default value is <code>null</code> which indicates the default environment
	 * should be used.
	 *
	 * @since 3.0
	 */
	String ATTR_ENVIRONMENT_VARIABLES = DebugPlugin.getUniqueIdentifier() + ".environmentVariables"; //$NON-NLS-1$

	/**
	 * Launch configuration attribute name. The value is a boolean value specifying
	 * whether the environment variables in a launch configuration
	 * should be appended to the native environment (i.e. when <code>true</code>),
	 * or if they should replace the environment (i.e. <code>false</code>). The
	 * default value is <code>true</code>.
	 *
	 * @since 3.0
	 */
	String ATTR_APPEND_ENVIRONMENT_VARIABLES = DebugPlugin.getUniqueIdentifier() + ".appendEnvironmentVariables"; //$NON-NLS-1$

	/**
	 * Adds the specified launch and notifies listeners. Has no
	 * effect if an identical launch is already registered.
	 *
	 * @param launch the launch to add
	 * @since 2.0
	 */
	void addLaunch(ILaunch launch);
	/**
	 * Adds the given launch configuration listener to the list
	 * of listeners notified when a launch configuration is
	 * added, removed, or changed. Has no effect if the given listener
	 * is already registered.
	 *
	 * @param listener launch configuration listener
	 * @since 2.0
	 */
	void addLaunchConfigurationListener(ILaunchConfigurationListener listener);
	/**
	 * Adds the specified launch objects and notifies listeners. Has no
	 * effect on identical launch objects already registered.
	 *
	 * @param launches the launch objects to add
	 * @since 2.1
	 */
	void addLaunches(ILaunch[] launches);
	/**
	 * Adds the given listener to the collection of registered launch listeners.
	 * Has no effect if an identical listener is already registered.
	 *
	 * @param listener the listener to register
	 * @since 2.1
	 */
	void addLaunchListener(ILaunchesListener listener);
	/**
	 * Adds the given listener to the collection of registered launch listeners.
	 * Has no effect if an identical listener is already registered.
	 *
	 * @param listener the listener to register
	 */
	void addLaunchListener(ILaunchListener listener);
	/**
	 * Return a String that can be used as the name of a launch configuration.  The name
	 * is guaranteed to be unique (no existing launch configurations will have this name).
	 * The name that is returned uses the <code>namePrefix</code> as a starting point.  If
	 * there is no existing launch configuration with this name, then <code>namePrefix</code>
	 * is returned.  Otherwise, the value returned consists of the specified prefix plus
	 * some suffix that guarantees uniqueness.
	 *
	 * @param namePrefix the String that the returned name must begin with
	 * @return launch configuration name
	 * @since 2.0
	 * @deprecated since 3.6 clients should use the {@link #generateLaunchConfigurationName(String)} method which
	 * will perform validation of the name and correct unsupported name parts.
	 */
	@Deprecated String generateUniqueLaunchConfigurationNameFrom(String namePrefix);

	/**
	 * Returns a string that can be used as the name of a launch configuration.  The name
	 * is guaranteed to be unique (no existing launch configurations will have this name).
	 * The name that is returned uses the <code>namePrefix</code> as a starting point.  If
	 * there is no existing launch configuration with this name, then <code>namePrefix</code>
	 * is returned.  Otherwise, the value returned consists of the specified prefix plus
	 * some suffix that guarantees uniqueness.
	 * <p>
	 * If the name prefix does not pass name validation any illegal parts of the name will be removed
	 * during the name generation. Illegal characters will be replaced with '_' and illegal names will be
	 * replaced with "_reserved_".
	 * </p>
	 * @param namePrefix the string that the returned name should begin with
	 * @return launch configuration name
	 * @since 3.6
	 */
	String generateLaunchConfigurationName(String namePrefix);

	/**
	 * Returns if the given name is valid or not. If an invalid name part is located
	 * an {@link IllegalArgumentException} is thrown.
	 *
	 * @param configname the name to check
	 * @return true if the given name is valid or throws an exception if not, where an invalid name
	 * is either a reserved system name (like 'aux' on Win 32) or the name contains invalid characters (like ':' or '/').
	 * @throws IllegalArgumentException if the name is invalid, where an invalid
	 * is either a reserved system name (like 'aux' on Win 32) or the name contains invalid characters (like ':' or '/').
	 * @since 3.6
	 */
	boolean isValidLaunchConfigurationName(String configname) throws IllegalArgumentException;

	/**
	 * Returns the collection of debug targets currently registered with this
	 * launch manager.
	 *
	 * @return an array of debug targets
	 */
	IDebugTarget[] getDebugTargets();
	/**
	 * Returns an array of environment variables to be used when
	 * launching the given configuration or <code>null</code> if unspecified.
	 * Each entry is of the form "<code>var_name=value</code>".
	 *
	 * @return an array of environment variables to use when launching the given
	 *  configuration or <code>null</code> if unspecified
	 * @param configuration launch configuration
	 * @throws CoreException if unable to access associated attribute or if
	 * unable to resolve a variable in an environment variable's value
	 * @since 3.0
	 */
	String[] getEnvironment(ILaunchConfiguration configuration) throws CoreException;
	/**
	 * This method returns the character encoding to use when launching the specified <code>ILaunchConfiguration</code>.
	 * The returned encoding can be derived from one of three places in the following order:
	 * <ol>
	 * <li>An attribute saved on the configuration itself (where no attribute means use the default encoding).</li>
	 * <li>The mapped resources for the configuration, in the event one of them has a specific encoding that
	 * is not the workspace default. If there are more than one mapped resource we optimistically ask only the first resource
	 * for its encoding.</li>
	 * <li>We ask the <code>ResourcesPlugin</code> for the workspace preference (which resolves back to the system
	 * property <code>file.encoding</code> if the user has made no changes to the workspace encoding preference).</li>
	 * </ol>
	 * @param configuration the <code>ILaunchConfiguration</code> to get the encoding for
	 * @return the encoding to use when launching the specified <code>ILaunchConfiguration</code>
	 * @throws CoreException if a problem is encountered
	 *
	 * @since 3.4
	 */
	String getEncoding(ILaunchConfiguration configuration) throws CoreException;
	/**
	 * Returns a handle to the launch configuration contained
	 * in the specified file. This method does not check if the specified <code>IFile</code> is
	 * a launch configuration file or that it exists in the local or
	 * remote file system.
	 * <p>
	 * Since 3.12, the returned configuration may be a launch configuration template.
	 * </p>
	 * 
	 * @param file launch configuration file
	 * @return a handle to the launch configuration contained
	 *  in the specified file
	 * @since 2.0
	 */
	ILaunchConfiguration getLaunchConfiguration(IFile file);
	/**
	 * Returns a handle to the launch configuration specified by
	 * the given memento. The configuration may not exist.
	 * <p>
	 * Since 3.12, the returned configuration may be a launch configuration template.
	 * </p>
	 * 
	 * @param memento launch configuration memento
	 * @return a handle to the launch configuration specified by
	 *  the given memento
	 * @exception CoreException if the given memento is invalid or
	 *  an exception occurs parsing the memento
	 * @see ILaunchConfiguration#getMemento()
	 * @since 2.0
	 */
	ILaunchConfiguration getLaunchConfiguration(String memento) throws CoreException;
	/**
	 * Returns all launch configurations defined in the workspace.
	 *
	 * @return all launch configurations defined in the workspace
	 * @exception CoreException if an exception occurs retrieving configurations
	 * @since 2.0
	 * @see ILaunchConfigurationType#getPrototypes()
	 */
	ILaunchConfiguration[] getLaunchConfigurations() throws CoreException;
	/**
	 * Returns all launch configurations of the specified type defined in the workspace
	 * <p>
	 * Does not include launch configuration templates.
	 * </p>
	 * @param type a launch configuration type
	 * @return all launch configurations of the specified type defined in the workspace
	 * @exception CoreException if an error occurs while retrieving
	 *  a launch configuration
	 * @since 2.0
	 * @see ILaunchConfigurationType#getPrototypes()
	 */
	ILaunchConfiguration[] getLaunchConfigurations(ILaunchConfigurationType type) throws CoreException;

	/**
	 * Returns all launch configurations defined in the workspace of the specified
	 * kind(s) (configurations and/or prototypes).
	 * 
	 * @param kinds bit mask of kinds of configurations to consider
	 * @return all launch configurations defined in the workspace
	 * @exception CoreException if an exception occurs retrieving configurations
	 * @since 3.12
	 * @see ILaunchConfiguration#CONFIGURATION
	 * @see ILaunchConfiguration#PROTOTYPE
	 * @see ILaunchConfiguration#getKind()
	 * @see ILaunchConfigurationType#getPrototypes()
	 */
	ILaunchConfiguration[] getLaunchConfigurations(int kinds) throws CoreException;

	/**
	 * Returns all launch configurations of the specified type defined in the workspace
	 * of the specified kind(s) (configurations and/or prototypes).
	 * 
	 * @param type a launch configuration type
	 * @param kinds bit mask of kinds of configurations to consider
	 * @return all launch configurations of the specified type defined in the workspace
	 * @exception CoreException if an error occurs while retrieving
	 *  a launch configuration
	 * @since 3.12
	 * @see ILaunchConfiguration#CONFIGURATION
	 * @see ILaunchConfiguration#PROTOTYPE
	 * @see ILaunchConfiguration#getKind()
	 * @see ILaunchConfigurationType#getPrototypes()
	 */
	ILaunchConfiguration[] getLaunchConfigurations(ILaunchConfigurationType type, int kinds) throws CoreException;

	/**
	 * Returns the launch configuration type extension with the specified
	 * id, or <code>null</code> if it does not exist.
	 *
	 * @param id unique identifier for a launch configuration type extension
	 * @return the launch configuration type extension with the specified
	 * id, or <code>null</code> if it does not exist
	 * @since 2.0
	 */
	ILaunchConfigurationType getLaunchConfigurationType(String id);

	/**
	 * Returns all defined launch configuration type extensions
	 *
	 * @return all defined launch configuration type extensions
	 * @since 2.0
	 */
	ILaunchConfigurationType[] getLaunchConfigurationTypes();

	/**
	 * Returns the collection of launches currently registered
	 * with this launch manager.
	 *
	 * @return an array of launches
	 */
	ILaunch[] getLaunches();

	/**
	 * Returns the launch mode registered with the given mode identifier,
	 * or <code>null</code> if none.
	 *
	 * @param mode mode identifier
	 * @return launch mode or <code>null</code>
	 * @since 3.0
	 */
	ILaunchMode getLaunchMode(String mode);

	/**
	 * Returns all registered launch modes.
	 *
	 * @return all registered launch modes
	 * @since 3.0
	 */
	ILaunchMode[] getLaunchModes();

	/**
	 * Returns a collection of launch configurations that required migration to be
	 * compatible with current tooling.
	 *
	 * @return a collection of launch configurations that required migration
	 * @exception org.eclipse.core.runtime.CoreException if an exception occurs determining
	 * 	 migration candidates
	 * @since 3.2
	 */
	ILaunchConfiguration[] getMigrationCandidates() throws CoreException;

	/**
	 * When a launch configuration is created or moved, registered launch
	 * configuration listeners (see <code>ILaunchConfigurationListener</code>)
	 * are notified of an add notification for the new configuration. If the
	 * notification is the result of a move this method will return a handle to
	 * the launch configuration that the added launch configuration was moved
	 * from. This method returns <code>null</code> if the added launch
	 * configuration was not the result of a rename or move. This information is
	 * only available during the add notification call back
	 * <code>launchConfigurationAdded</code>.
	 * <p>
	 * Renaming a configuration is considered the same as moving a
	 * configuration.
	 * </p>
	 *
	 * @param addedConfiguration a launch configuration for which an add
	 * notification is being broadcast
	 * @return the launch configuration that the added launch configuration was
	 * moved from, or <code>null</code> if the add notification is not the
	 * result of a move
	 * @since 2.1
	 */
	ILaunchConfiguration getMovedFrom(ILaunchConfiguration addedConfiguration);

	/**
	 * When a launch configuration is deleted or moved, registered launch
	 * configuration listeners (see <code>ILaunchConfigurationListener</code>)
	 * are notified of a remove notification for launch configuration that has
	 * been deleted. If the notification is the result of a move this method
	 * will return a handle to the launch configuration that the removed launch
	 * configuration was moved to. This method returns <code>null</code> if the
	 * removed launch configuration was not the result of a rename or move. This
	 * information is only available during the add notification call back
	 * <code>launchConfigurationRemoved</code>.
	 * <p>
	 * Renaming a configuration is considered the same as moving a
	 * configuration.
	 * </p>
	 *
	 * @param removedConfiguration a launch configuration for which a
	 * remove notification is being broadcast
	 * @return the launch configuration that the removed launch configuration
	 * was moved to, or <code>null</code> if the add notification is not the
	 * result of a move
	 * @since 2.1
	 */
	ILaunchConfiguration getMovedTo(ILaunchConfiguration removedConfiguration);

	/**
	 * Returns the native system environment variables as a map of
	 * variable names and values (Strings).
	 * <p>
	 * Note that WIN32 system environment preserves
	 * the case of variable names but is otherwise case insensitive.
	 * Depending on what you intend to do with the environment, the
	 * lack of normalization may or may not be create problems. On
	 * WIN32, this method normalizes mixed-case keys variable names
	 * to upper case. Use {@link #getNativeEnvironmentCasePreserved()}
	 * instead to get a WIN32 system environment where the keys are
	 * the mixed-case variable names recorded by the OS.
	 * </p>
	 *
	 * @return the native system environment variables; on WIN32, mixed-case
	 * variable names (keys) have been normalized to upper case
	 * (key type: <code>String</code>; value type: <code>String</code>)
	 * @since 3.0
	 */
	Map<String, String> getNativeEnvironment();

	/**
	 * Returns the native system environment variables as a map of
	 * variable names and values (Strings).
	 * <p>
	 * Note that WIN32 system environment preserves
	 * the case of variable names but is otherwise case insensitive.
	 * Depending on what you intend to do with the environment, the
	 * lack of normalization may or may not be create problems. This
	 * method returns mixed-case keys using the variable names
	 * recorded by the OS.
	 * Use {@link #getNativeEnvironment()} instead to get a WIN32 system
	 * environment where all keys have been normalized to upper case.
	 * </p>
	 *
	 * @return the native system environment variables; on WIN32, mixed-case
	 * variable names (keys) are returned without normalization
	 * (key type: <code>String</code>; value type: <code>String</code>)
	 * @since 3.1
	 */
	Map<String, String> getNativeEnvironmentCasePreserved();

	/**
	 * Returns the collection of processes currently registered with this
	 * launch manager.
	 *
	 * @return an array of processes
	 */
	IProcess[] getProcesses();

	/**
	 * Returns the source container type extension registered with the
	 * given unique identifier, or <code>null</code> if none.
	 *
	 * @param id unique identifier of a source container type extension
	 * @return the source container type extension registered with the
	 * given unique identifier, or <code>null</code> if none
	 * @since 3.0
	 */
	ISourceContainerType getSourceContainerType(String id);

	/**
	 * Returns all registered source container type extensions.
	 *
	 * @return all registered source container type extensions
	 * @since 3.0
	 */
	ISourceContainerType[] getSourceContainerTypes();

	/**
	 * Returns a source path computer to compute a default source lookup path for
	 * the given launch configuration, or <code>null</code> if a source path
	 * computer has not been registered for the associated launch configuration
	 * type.
	 *
	 * @param configuration a launch configuration
	 * @return a source path computer registered for the associated launch
	 *  configurations type, or <code>null</code> if unspecified
	 * @throws CoreException if an exception occurs while instantiating a source
	 *  path computer
	 * @since 3.0
	 */
	ISourcePathComputer getSourcePathComputer(ILaunchConfiguration configuration) throws CoreException;

	/**
	 * Returns the source path computer extension registered with the given
	 * unique identifier, or <code>null</code> if none.
	 *
	 * @param id source path computer identifier
	 * @return the source path computer extension registered with the given
	 * unique identifier, or <code>null</code> if none
	 * @since 3.0
	 */
	ISourcePathComputer getSourcePathComputer(String id);

	/**
	 * Return <code>true</code> if there is a launch configuration with the specified name,
	 * <code>false</code> otherwise.
	 *
	 * @return whether a launch configuration already exists with the given name
	 * @param name the name of the launch configuration whose existence is being checked
	 * @exception CoreException if unable to retrieve existing launch configuration names
	 * @since 2.0
	 */
	boolean isExistingLaunchConfigurationName(String name) throws CoreException;

	/**
	 * Returns whether the given launch is currently registered.
	 *
	 * @param launch a launch
	 * @return whether the launch is currently registered
	 * @since 3.1
	 */
	boolean isRegistered(ILaunch launch);

	/**
	 * Creates and returns a new source locator of the specified
	 * type.
	 *
	 * @param identifier the identifier associated with a
	 *  persistable source locator extension
	 * @return a source locator
	 * @exception CoreException if an exception occurs creating
	 *  the source locator
	 * @since 2.0
	 */
	IPersistableSourceLocator newSourceLocator(String identifier) throws CoreException;

	/**
	 * Removes the specified launch and notifies listeners.
	 * Has no effect if an identical launch is not already
	 * registered.
	 *
	 * @param launch the launch to remove
	 * @since 2.0
	 */
	void removeLaunch(ILaunch launch);

	/**
	 * Removes the given launch configuration listener from the list
	 * of listeners notified when a launch configuration is
	 * added, removed, or changed. Has no effect if the given listener
	 * is not already registered.
	 *
	 * @param listener launch configuration listener
	 * @since 2.0
	 */
	void removeLaunchConfigurationListener(ILaunchConfigurationListener listener);

	/**
	 * Removes the specified launch objects and notifies listeners.
	 * Has no effect on identical launch objects that are not already
	 * registered.
	 *
	 * @param launches the launch objects to remove
	 * @since 2.1
	 */
	void removeLaunches(ILaunch[] launches);

	/**
	 * Removes the given listener from the collection of registered launch listeners.
	 * Has no effect if an identical listener is not already registered.
	 *
	 * @param listener the listener to unregister
	 * @since 2.1
	 */
	void removeLaunchListener(ILaunchesListener listener);

	/**
	 * Removes the given listener from the collection of registered launch listeners.
	 * Has no effect if an identical listener is not already registered.
	 *
	 * @param listener the listener to unregister
	 */
	void removeLaunchListener(ILaunchListener listener);

}


Back to the top