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  ;
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   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   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   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   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   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   generateUniqueLaunchConfigurationNameFrom(String   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  [] 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   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   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   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   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   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   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   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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags