KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > debug > core > ILaunchManager


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.Map JavaDoc;
15
16 import org.eclipse.core.resources.IFile;
17 import org.eclipse.core.runtime.CoreException;
18 import org.eclipse.debug.core.model.IDebugTarget;
19 import org.eclipse.debug.core.model.IPersistableSourceLocator;
20 import org.eclipse.debug.core.model.IProcess;
21 import org.eclipse.debug.core.sourcelookup.ISourceContainerType;
22 import org.eclipse.debug.core.sourcelookup.ISourcePathComputer;
23
24 /**
25  * The launch manager manages the set of registered launches, maintaining
26  * a collection of active processes and debug targets. Clients interested
27  * in launch notification may register with the launch manager.
28  * <p>
29  * Clients are not intended to implement this interface.
30  * </p>
31  * @see ILaunch
32  * @see ILaunchListener
33  */

34 public interface ILaunchManager {
35     /**
36      * A launch in a normal, non-debug mode(value <code>"run"</code>).
37      */

38     public static final String JavaDoc RUN_MODE= "run"; //$NON-NLS-1$
39
/**
40      * A launch in a special debug mode (value <code>"debug"</code>).
41      */

42     public static final String JavaDoc DEBUG_MODE= "debug"; //$NON-NLS-1$
43
/**
44      * A launch in a special profile mode (value <code>"profile"</code>).
45      * @since 3.0
46      */

47     public static final String JavaDoc PROFILE_MODE= "profile"; //$NON-NLS-1$
48

49     /**
50      * Launch configuration attribute name. The value is a map of environment
51      * variables passed into Runtime.exec(...) when a launch configuration is launched.
52      * Default value is <code>null</code> which indicates the default environment
53      * should be used.
54      *
55      * @since 3.0
56      */

57     public static final String JavaDoc ATTR_ENVIRONMENT_VARIABLES = DebugPlugin.getUniqueIdentifier() + ".environmentVariables"; //$NON-NLS-1$
58

59     /**
60      * Launch configuration attribute name. The value is a boolean value specifying
61      * whether the environment variables in a launch configuration
62      * should be appended to the native environment (i.e. when <code>true</code>),
63      * or if they should replace the environment (i.e. <code>false</code>). The
64      * default value is <code>true</code>.
65      *
66      * @since 3.0
67      */

68     public static final String JavaDoc ATTR_APPEND_ENVIRONMENT_VARIABLES = DebugPlugin.getUniqueIdentifier() + ".appendEnvironmentVariables"; //$NON-NLS-1$
69

70     /**
71      * Adds the specified launch and notifies listeners. Has no
72      * effect if an identical launch is already registered.
73      *
74      * @param launch the launch to add
75      * @since 2.0
76      */

77     public void addLaunch(ILaunch launch);
78     /**
79      * Adds the given launch configuration listener to the list
80      * of listeners notified when a launch configuration is
81      * added, removed, or changed. Has no effect if the given listener
82      * is already registered.
83      *
84      * @param listener launch configuration listener
85      * @since 2.0
86      */

87     public void addLaunchConfigurationListener(ILaunchConfigurationListener listener);
88     /**
89      * Adds the specified launch objects and notifies listeners. Has no
90      * effect on identical launch objects already registered.
91      *
92      * @param launches the launch objects to add
93      * @since 2.1
94      */

95     public void addLaunches(ILaunch[] launches);
96     /**
97      * Adds the given listener to the collection of registered launch listeners.
98      * Has no effect if an identical listener is already registered.
99      *
100      * @param listener the listener to register
101      * @since 2.1
102      */

103     public void addLaunchListener(ILaunchesListener listener);
104     /**
105      * Adds the given listener to the collection of registered launch listeners.
106      * Has no effect if an identical listener is already registered.
107      *
108      * @param listener the listener to register
109      */

110     public void addLaunchListener(ILaunchListener listener);
111     /**
112      * Return a String that can be used as the name of a launch configuration. The name
113      * is guaranteed to be unique (no existing launch configurations will have this name).
114      * The name that is returned uses the <code>namePrefix</code> as a starting point. If
115      * there is no existing launch configuration with this name, then <code>namePrefix</code>
116      * is returned. Otherwise, the value returned consists of the specified prefix plus
117      * some suffix that guarantees uniqueness.
118      *
119      * @param namePrefix the String that the returned name must begin with
120      * @return launch configuration name
121      * @since 2.0
122      */

123     public String JavaDoc generateUniqueLaunchConfigurationNameFrom(String JavaDoc namePrefix);
124     /**
125      * Returns the collection of debug targets currently registered with this
126      * launch manager.
127      *
128      * @return an array of debug targets
129      */

130     public IDebugTarget[] getDebugTargets();
131     /**
132      * Returns an array of environment variables to be used when
133      * launching the given configuration or <code>null</code> if unspecified.
134      * Each entry is of the form "<code>var_name=value</code>".
135      *
136      * @return an array of environment variables to use when launching the given
137      * configuration or <code>null</code> if unspecified
138      * @param configuration launch configuration
139      * @throws CoreException if unable to access associated attribute or if
140      * unable to resolve a variable in an environment variable's value
141      * @since 3.0
142      */

143     public String JavaDoc[] getEnvironment(ILaunchConfiguration configuration) throws CoreException;
144     /**
145      * Returns a handle to the launch configuration contained
146      * in the specified file. The file is not verified to exist
147      * or contain a launch configuration.
148      *
149      * @param file launch configuration file
150      * @return a handle to the launch configuration contained
151      * in the specified file
152      * @since 2.0
153      */

154     public ILaunchConfiguration getLaunchConfiguration(IFile file);
155     /**
156      * Returns a handle to the launch configuration specified by
157      * the given memento. The configuration may not exist.
158      *
159      * @param memento launch configuration memento
160      * @return a handle to the launch configuration specified by
161      * the given memento
162      * @exception CoreException if the given memento is invalid or
163      * an exception occurs parsing the memento
164      * @see ILaunchConfiguration#getMemento()
165      * @since 2.0
166      */

167     public ILaunchConfiguration getLaunchConfiguration(String JavaDoc memento) throws CoreException;
168     /**
169      * Returns all launch configurations defined in the workspace.
170      *
171      * @return all launch configurations defined in the workspace
172      * @exception CoreException if an exception occurs retrieving configurations
173      * @since 2.0
174      */

175     public ILaunchConfiguration[] getLaunchConfigurations() throws CoreException;
176     /**
177      * Returns all launch configurations of the specified type defined in the workspace
178      *
179      * @param type a launch configuration type
180      * @return all launch configurations of the specified type defined in the workspace
181      * @exception CoreException if an error occurs while retrieving
182      * a launch configuration
183      * @since 2.0
184      */

185     public ILaunchConfiguration[] getLaunchConfigurations(ILaunchConfigurationType type) throws CoreException;
186     
187     /**
188      * Returns the launch configuration type extension with the specified
189      * id, or <code>null</code> if it does not exist.
190      *
191      * @param id unique identifier for a launch configuration type extension
192      * @return the launch configuration type extension with the specified
193      * id, or <code>null</code> if it does not exist
194      * @since 2.0
195      */

196     public ILaunchConfigurationType getLaunchConfigurationType(String JavaDoc id);
197     
198     /**
199      * Returns all defined launch configuration type extensions
200      *
201      * @return all defined launch configuration type extensions
202      * @since 2.0
203      */

204     public ILaunchConfigurationType[] getLaunchConfigurationTypes();
205     
206     /**
207      * Returns the collection of launches currently registered
208      * with this launch manager.
209      *
210      * @return an array of launches
211      */

212     public ILaunch[] getLaunches();
213     
214     /**
215      * Returns the launch mode registered with the given mode identifier,
216      * or <code>null</code> if none.
217      *
218      * @param mode mode identifier
219      * @return launch mode or <code>null</code>
220      * @since 3.0
221      */

222     public ILaunchMode getLaunchMode(String JavaDoc mode);
223     
224     /**
225      * Returns all registered launch modes.
226      *
227      * @return all registered launch modes
228      * @since 3.0
229      */

230     public ILaunchMode[] getLaunchModes();
231     
232     /**
233      * Returns a collection of launch configurations that required migration to be
234      * compatible with current tooling.
235      *
236      * @return a collection of launch configurations that required migration
237      * @exception org.eclipse.core.runtime.CoreException if an exception occurs determining
238      * migration candidates
239      * @since 3.2
240      */

241     public ILaunchConfiguration[] getMigrationCandidates() throws CoreException;
242     
243     /**
244      * When a launch configuration is created or moved, registered launch
245      * configuration listeners (see <code>ILaunchConfigurationListener</code>)
246      * are notified of an add notification for the new configuration. If the
247      * notification is the result of a move this method will return a handle to
248      * the launch configuration that the added launch configuration was moved
249      * from. This method returns <code>null</code> if the added launch
250      * configuration was not the result of a rename or move. This information is
251      * only available during the add notification call back
252      * <code>launchConfigurationAdded</code>.
253      * <p>
254      * Renaming a configuration is considered the same as moving a
255      * configuration.
256      * </p>
257      *
258      * @param addedConfiguration a launch configuration for which an add
259      * notification is being broadcast
260      * @return the launch configuration that the added launch configuration was
261      * moved from, or <code>null</code> if the add notification is not the
262      * result of a move
263      * @since 2.1
264      */

265     public ILaunchConfiguration getMovedFrom(ILaunchConfiguration addedConfiguration);
266     
267     /**
268      * When a launch configuration is deleted or moved, registered launch
269      * configuration listeners (see <code>ILaunchConfigurationListener</code>)
270      * are notified of a remove notification for launch configuration that has
271      * been deleted. If the notification is the result of a move this method
272      * will return a handle to the launch configuration that the removed launch
273      * configuration was moved to. This method returns <code>null</code> if the
274      * removed launch configuration was not the result of a rename or move. This
275      * information is only available during the add notification call back
276      * <code>launchConfigurationRemoved</code>.
277      * <p>
278      * Renaming a configuration is considered the same as moving a
279      * configuration.
280      * </p>
281      *
282      * @param removedConfiguration a launch configuration for which a
283      * remove notification is being broadcast
284      * @return the launch configuration that the removed launch configuration
285      * was moved to, or <code>null</code> if the add notification is not the
286      * result of a move
287      * @since 2.1
288      */

289     public ILaunchConfiguration getMovedTo(ILaunchConfiguration removedConfiguration);
290     
291     /**
292      * Returns the native system environment variables as a map of
293      * variable names and values (Strings).
294      * <p>
295      * Note that WIN32 system environment preserves
296      * the case of variable names but is otherwise case insensitive.
297      * Depending on what you intend to do with the environment, the
298      * lack of normalization may or may not be create problems. On
299      * WIN32, this method normalizes mixed-case keys variable names
300      * to upper case. Use {@link #getNativeEnvironmentCasePreserved()}
301      * instead to get a WIN32 system environment where the keys are
302      * the mixed-case variable names recorded by the OS.
303      * </p>
304      *
305      * @return the native system environment variables; on WIN32, mixed-case
306      * variable names (keys) have been normalized to upper case
307      * (key type: <code>String</code>; value type: <code>String</code>)
308      * @since 3.0
309      */

310     public Map JavaDoc getNativeEnvironment();
311
312     /**
313      * Returns the native system environment variables as a map of
314      * variable names and values (Strings).
315      * <p>
316      * Note that WIN32 system environment preserves
317      * the case of variable names but is otherwise case insensitive.
318      * Depending on what you intend to do with the environment, the
319      * lack of normalization may or may not be create problems. This
320      * method returns mixed-case keys using the variable names
321      * recorded by the OS.
322      * Use {@link #getNativeEnvironment()} instead to get a WIN32 system
323      * environment where all keys have been normalized to upper case.
324      * </p>
325      *
326      * @return the native system environment variables; on WIN32, mixed-case
327      * variable names (keys) are returned without normalization
328      * (key type: <code>String</code>; value type: <code>String</code>)
329      * @since 3.1
330      */

331     public Map JavaDoc getNativeEnvironmentCasePreserved();
332
333     /**
334      * Returns the collection of processes currently registered with this
335      * launch manager.
336      *
337      * @return an array of processes
338      */

339     public IProcess[] getProcesses();
340     
341     /**
342      * Returns the source container type extension registered with the
343      * given unique identifier, or <code>null</code> if none.
344      *
345      * @param id unique identifier of a source container type extension
346      * @return the source container type extension registered with the
347      * given unique identifier, or <code>null</code> if none
348      * @since 3.0
349      */

350     public ISourceContainerType getSourceContainerType(String JavaDoc id);
351     
352     /**
353      * Returns all registered source container type extensions.
354      *
355      * @return all registered source container type extensions
356      * @since 3.0
357      */

358     public ISourceContainerType[] getSourceContainerTypes();
359
360     /**
361      * Returns a source path computer to compute a default source lookup path for
362      * the given launch configuration, or <code>null</code> if a source path
363      * computer has not been registered for the associated launch configuration
364      * type.
365      *
366      * @param configuration a launch configuration
367      * @return a source path computer registered for the associated launch
368      * configurations type, or <code>null</code> if unspecified
369      * @throws CoreException if an exception occurs while instantiating a source
370      * path computer
371      * @since 3.0
372      */

373     public ISourcePathComputer getSourcePathComputer(ILaunchConfiguration configuration) throws CoreException;
374     
375     /**
376      * Returns the source path computer extension registered with the given
377      * unique identifier, or <code>null</code> if none.
378      *
379      * @param id source path computer identifier
380      * @return the source path computer extension registered with the given
381      * unique identifier, or <code>null</code> if none
382      * @since 3.0
383      */

384     public ISourcePathComputer getSourcePathComputer(String JavaDoc id);
385     
386     /**
387      * Return <code>true</code> if there is a launch configuration with the specified name,
388      * <code>false</code> otherwise.
389      *
390      * @return whether a launch configuration already exists with the given name
391      * @param name the name of the launch configuration whose existence is being checked
392      * @exception CoreException if unable to retrieve existing launch configuration names
393      * @since 2.0
394      */

395     public boolean isExistingLaunchConfigurationName(String JavaDoc name) throws CoreException;
396     
397     /**
398      * Returns whether the given launch is currently registered.
399      *
400      * @param launch a launch
401      * @return whether the launch is currently registered
402      * @since 3.1
403      */

404     public boolean isRegistered(ILaunch launch);
405     
406     /**
407      * Creates and returns a new source locator of the specified
408      * type.
409      *
410      * @param identifier the identifier associated with a
411      * persistable source locator extension
412      * @return a source locator
413      * @exception CoreException if an exception occurs creating
414      * the source locator
415      * @since 2.0
416      */

417     public IPersistableSourceLocator newSourceLocator(String JavaDoc identifier) throws CoreException;
418
419     /**
420      * Removes the specified launch and notifies listeners.
421      * Has no effect if an identical launch is not already
422      * registered.
423      *
424      * @param launch the launch to remove
425      * @since 2.0
426      */

427     public void removeLaunch(ILaunch launch);
428
429     /**
430      * Removes the given launch configuration listener from the list
431      * of listeners notified when a launch configuration is
432      * added, removed, or changed. Has no effect if the given listener
433      * is not already registered.
434      *
435      * @param listener launch configuration listener
436      * @since 2.0
437      */

438     public void removeLaunchConfigurationListener(ILaunchConfigurationListener listener);
439
440     /**
441      * Removes the specified launch objects and notifies listeners.
442      * Has no effect on identical launch objects that are not already
443      * registered.
444      *
445      * @param launches the launch objects to remove
446      * @since 2.1
447      */

448     public void removeLaunches(ILaunch[] launches);
449     
450     /**
451      * Removes the given listener from the collection of registered launch listeners.
452      * Has no effect if an identical listener is not already registered.
453      *
454      * @param listener the listener to unregister
455      * @since 2.1
456      */

457     public void removeLaunchListener(ILaunchesListener listener);
458     
459     /**
460      * Removes the given listener from the collection of registered launch listeners.
461      * Has no effect if an identical listener is not already registered.
462      *
463      * @param listener the listener to unregister
464      */

465     public void removeLaunchListener(ILaunchListener listener);
466     
467 }
468
469
470
Popular Tags