org.eclipse.debug.core
Class Launch

java.lang.Object
  org.eclipse.core.runtime.PlatformObject
      org.eclipse.debug.core.Launch

All Implemented Interfaces:

IAdaptable, IDebugEventSetListener, IDisconnect, ILaunch, ILaunchConfigurationListener, ILaunchListener, ITerminate

public class Launch

extends PlatformObject

implements ILaunch, IDisconnect, ILaunchListener, ILaunchConfigurationListener, IDebugEventSetListener

A launch is the result of launching a debug session and/or one or more system processes. This class provides a public implementation of ILaunch for client use.

Clients may instantiate this class. Clients may subclass this class. Many of the methods in this class that are part of the ILaunch interface are final. Clients that subclass this class are not intended to change the behavior or implementation of the provided methods. Subclassing is only intended to add additional information to a specific launch. For example, a client that implements a launch object representing a Java launch might store a classpath with the launch.

See Also:

ILaunch, ILaunchManager

Constructor Summary

Launch(ILaunchConfiguration launchConfiguration, String mode, ISourceLocator locator)
Constructs a launch with the specified attributes.

Method Summary

void	addDebugTarget(IDebugTarget target) Adds the given debug target to this launch.
void	addProcess(IProcess process) Adds the given process to this launch.
protected void	addProcesses(IProcess[] processes) Adds the given processes to this launch.
boolean	canDisconnect() Returns whether this element can currently disconnect.
boolean	canTerminate() Returns whether this element can be terminated.
void	disconnect() Disconnects this element from its target.
protected void	fireChanged() Notifies listeners that this launch has changed.
protected void	fireTerminate() Notifies listeners that this launch has terminated.
String	getAttribute(String key) Returns the value of a client defined attribute.
Object[]	getChildren() Returns the children of this launch - a collection of one or more debug targets and processes, possibly empty.
IDebugTarget	getDebugTarget() Returns the primary (first) debug target associated with this launch, or null if no debug target is associated with this launch.
IDebugTarget[]	getDebugTargets() Returns all the debug targets associated with this launch, or an empty collection if no debug targets are associated with this launch.
protected List	getDebugTargets0() Returns the debug targets associated with this launch, in its internal form - a list
ILaunchConfiguration	getLaunchConfiguration() Returns the configuration that was launched, or null if no configuration was launched.
protected ILaunchManager	getLaunchManager() Returns the launch manager.
String	getLaunchMode() Returns the mode of this launch - one of the mode constants defined by the launch manager.
IProcess[]	getProcesses() Returns the processes that were launched, or an empty collection if no processes were launched.
protected List	getProcesses0() Returns the processes associated with this launch, in its internal form - a list.
ISourceLocator	getSourceLocator() Returns the source locator to use for locating source elements for the debug target associated with this launch, or null if source lookup is not supported.
void	handleDebugEvents(DebugEvent[] events) Notifies this listener of the given debug events.
boolean	hasChildren() Returns whether this launch contains at least one process or debug target.
boolean	isDisconnected() Returns whether this element is disconnected.
boolean	isTerminated() Returns whether this element is terminated.
void	launchAdded(ILaunch launch) Notifies this listener that the specified launch has been added.
void	launchChanged(ILaunch launch) Notifies this listener that the specified launch has changed.
void	launchConfigurationAdded(ILaunchConfiguration configuration) The given launch configuration has been created.
void	launchConfigurationChanged(ILaunchConfiguration configuration) The given launch configuration has changed in some way.
void	launchConfigurationRemoved(ILaunchConfiguration configuration) The given launch configuration has been deleted.
void	launchRemoved(ILaunch launch) Notifies this listener that the specified launch has been removed.
void	removeDebugTarget(IDebugTarget target) Removes the given debug target from this launch.
void	removeProcess(IProcess process) Removes the given process from this launch.
void	setAttribute(String key, String value) Sets the value of a client defined attribute.
void	setSourceLocator(ISourceLocator sourceLocator) Sets the source locator to use for locating source elements for the debug target associated with this launch, or null if source lookup is not supported.
void	terminate() Causes this element to terminate, generating a TERMINATE event.

Methods inherited from class org.eclipse.core.runtime.PlatformObject

getAdapter

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.eclipse.core.runtime.IAdaptable

getAdapter

Constructor Detail

Launch

public Launch(ILaunchConfiguration launchConfiguration,
              String mode,
              ISourceLocator locator)

Constructs a launch with the specified attributes.

Parameters:

launchConfiguration - the configuration that was launched

mode - the mode of this launch - run or debug (constants defined by ILaunchManager)

locator - the source locator to use for this debug session, or null if not supported

Method Detail

canTerminate

public final boolean canTerminate()

Description copied from interface: ITerminate

Returns whether this element can be terminated.

Specified by:

canTerminate in interface ITerminate

Returns:

whether this element can be terminated

See Also:

ITerminate.canTerminate()

getChildren

public final Object[] getChildren()

Description copied from interface: ILaunch

Returns the children of this launch - a collection of one or more debug targets and processes, possibly empty.

Specified by:

getChildren in interface ILaunch

Returns:

an array (element type:IDebugTarget or IProcess), or an empty array

See Also:

ILaunch.getChildren()

getDebugTarget

public final IDebugTarget getDebugTarget()

Description copied from interface: ILaunch

Returns the primary (first) debug target associated with this launch, or null if no debug target is associated with this launch. All debug targets associated with this launch may be retrieved by getDebugTargets().

Specified by:

getDebugTarget in interface ILaunch

Returns:

the primary debug target associated with this launch, or null

See Also:

ILaunch.getDebugTarget()

getProcesses

public final IProcess[] getProcesses()

Description copied from interface: ILaunch

Returns the processes that were launched, or an empty collection if no processes were launched.

Specified by:

getProcesses in interface ILaunch

Returns:

array of processes

See Also:

ILaunch.getProcesses()

getProcesses0

protected List getProcesses0()

Returns the processes associated with this launch, in its internal form - a list.

Returns:

list of processes

getSourceLocator

public final ISourceLocator getSourceLocator()

Description copied from interface: ILaunch

Returns the source locator to use for locating source elements for the debug target associated with this launch, or null if source lookup is not supported.

Specified by:

getSourceLocator in interface ILaunch

Returns:

the source locator

See Also:

ILaunch.getSourceLocator()

setSourceLocator

public final void setSourceLocator(ISourceLocator sourceLocator)

Description copied from interface: ILaunch

Sets the source locator to use for locating source elements for the debug target associated with this launch, or null if source lookup is not supported.

Specified by:

setSourceLocator in interface ILaunch

Parameters:

sourceLocator - source locator or null

See Also:

ILaunch.setSourceLocator(ISourceLocator)

isTerminated

public final boolean isTerminated()

Description copied from interface: ITerminate

Returns whether this element is terminated.

Specified by:

isTerminated in interface ITerminate

Returns:

whether this element is terminated

See Also:

ITerminate.isTerminated()

terminate

public final void terminate()
                     throws DebugException

Description copied from interface: ITerminate

Causes this element to terminate, generating a TERMINATE event. Implementations may be blocking or non-blocking.

Specified by:

terminate in interface ITerminate

Throws:

DebugException - on failure. Reasons include:

• TARGET_REQUEST_FAILED - The request failed in the target
• NOT_SUPPORTED - The capability is not supported by the target

See Also:

ITerminate.terminate()

getLaunchMode

public final String getLaunchMode()

Description copied from interface: ILaunch

Returns the mode of this launch - one of the mode constants defined by the launch manager.

Specified by:

getLaunchMode in interface ILaunch

Returns:

the launch mode

See Also:

ILaunch.getLaunchMode()

getLaunchConfiguration

public ILaunchConfiguration getLaunchConfiguration()

Description copied from interface: ILaunch

Returns the configuration that was launched, or null if no configuration was launched.

Specified by:

getLaunchConfiguration in interface ILaunch

Returns:

the launched configuration or null

See Also:

ILaunch.getLaunchConfiguration()

setAttribute

public void setAttribute(String key,
                         String value)

Description copied from interface: ILaunch

Sets the value of a client defined attribute.

Specified by:

setAttribute in interface ILaunch

Parameters:

key - the attribute key

value - the attribute value

See Also:

ILaunch.setAttribute(String, String)

getAttribute

public String getAttribute(String key)

Description copied from interface: ILaunch

Returns the value of a client defined attribute.

Specified by:

getAttribute in interface ILaunch

Parameters:

key - the attribute key

Returns:

value the attribute value, or null if undefined

See Also:

ILaunch.getAttribute(String)

getDebugTargets

public IDebugTarget[] getDebugTargets()

Description copied from interface: ILaunch

Returns all the debug targets associated with this launch, or an empty collection if no debug targets are associated with this launch. The primary debug target is the first in the collection (if any).

Specified by:

getDebugTargets in interface ILaunch

Returns:

array of debug targets

See Also:

ILaunch.getDebugTargets()

getDebugTargets0

protected List getDebugTargets0()

Returns the debug targets associated with this launch, in its internal form - a list

Returns:

list of debug targets

addDebugTarget

public final void addDebugTarget(IDebugTarget target)

Description copied from interface: ILaunch

Adds the given debug target to this launch. Has no effect if the given debug target is already associated with this launch. Registered listeners are notified that this launch has changed.

Specified by:

addDebugTarget in interface ILaunch

Parameters:

target - debug target to add to this launch

See Also:

ILaunch.addDebugTarget(IDebugTarget)

removeDebugTarget

public final void removeDebugTarget(IDebugTarget target)

Description copied from interface: ILaunch

Removes the given debug target from this launch. Has no effect if the given debug target is not already associated with this launch. Registered listeners are notified that this launch has changed.

Specified by:

removeDebugTarget in interface ILaunch

Parameters:

target - debug target to remove from this launch

See Also:

ILaunch.removeDebugTarget(IDebugTarget)

addProcess

public final void addProcess(IProcess process)

Description copied from interface: ILaunch

Adds the given process to this launch. Has no effect if the given process is already associated with this launch. Registered listeners are notified that this launch has changed.

Specified by:

addProcess in interface ILaunch

Parameters:

process - the process to add to this launch

See Also:

ILaunch.addProcess(IProcess)

removeProcess

public final void removeProcess(IProcess process)

Description copied from interface: ILaunch

Removes the given process from this launch. Has no effect if the given process is not already associated with this launch. Registered listeners are notified that this launch has changed.

Specified by:

removeProcess in interface ILaunch

Parameters:

process - the process to remove from this launch

See Also:

ILaunch.removeProcess(IProcess)

addProcesses

protected void addProcesses(IProcess[] processes)

Adds the given processes to this launch.

Parameters:

processes - processes to add

fireChanged

protected void fireChanged()

Notifies listeners that this launch has changed. Has no effect of this launch has not yet been properly created/initialized.

fireTerminate

protected void fireTerminate()

Notifies listeners that this launch has terminated. Has no effect of this launch has not yet been properly created/initialized.

hasChildren

public boolean hasChildren()

Description copied from interface: ILaunch

Returns whether this launch contains at least one process or debug target.

Specified by:

hasChildren in interface ILaunch

Returns:

whether this launch contains at least one process or debug target

See Also:

ILaunch.hasChildren()

canDisconnect

public boolean canDisconnect()

Description copied from interface: IDisconnect

Returns whether this element can currently disconnect.

Specified by:

canDisconnect in interface IDisconnect

Returns:

whether this element can currently disconnect

See Also:

IDisconnect.canDisconnect()

disconnect

public void disconnect()
                throws DebugException

Description copied from interface: IDisconnect

Disconnects this element from its target. Generally, disconnecting ends a debug session with a debug target, but allows the target program to continue running.

Specified by:

disconnect in interface IDisconnect

Throws:

DebugException - on failure. Reasons include:

• TARGET_REQUEST_FAILED - The request failed in the target
• NOT_SUPPORTED - The capability is not supported by the target

See Also:

IDisconnect.disconnect()

isDisconnected

public boolean isDisconnected()

Description copied from interface: IDisconnect

Returns whether this element is disconnected.

Specified by:

isDisconnected in interface IDisconnect

Returns:

whether this element is disconnected

See Also:

IDisconnect.isDisconnected()

launchRemoved

public void launchRemoved(ILaunch launch)

Description copied from interface: ILaunchListener

Notifies this listener that the specified launch has been removed.

Specified by:

launchRemoved in interface ILaunchListener

Parameters:

launch - the removed launch

getLaunchManager

protected ILaunchManager getLaunchManager()

Returns the launch manager.

Returns:

the launch manager.

launchAdded

public void launchAdded(ILaunch launch)

Description copied from interface: ILaunchListener

Notifies this listener that the specified launch has been added.

Specified by:

launchAdded in interface ILaunchListener

Parameters:

launch - the newly added launch

launchChanged

public void launchChanged(ILaunch launch)

Description copied from interface: ILaunchListener

Notifies this listener that the specified launch has changed. For example, a process or debug target has been added to the launch.

Specified by:

launchChanged in interface ILaunchListener

Parameters:

launch - the changed launch

launchConfigurationAdded

public void launchConfigurationAdded(ILaunchConfiguration configuration)

Description copied from interface: ILaunchConfigurationListener

The given launch configuration has been created.

Specified by:

launchConfigurationAdded in interface ILaunchConfigurationListener

Parameters:

configuration - the newly created launch configuration

launchConfigurationChanged

public void launchConfigurationChanged(ILaunchConfiguration configuration)

Description copied from interface: ILaunchConfigurationListener

The given launch configuration has changed in some way. The configuration may be a working copy.

Specified by:

launchConfigurationChanged in interface ILaunchConfigurationListener

Parameters:

configuration - the launch configuration that has changed

launchConfigurationRemoved

public void launchConfigurationRemoved(ILaunchConfiguration configuration)

Description copied from interface: ILaunchConfigurationListener

The given launch configuration has been deleted.

Specified by:

launchConfigurationRemoved in interface ILaunchConfigurationListener

Parameters:

configuration - the deleted launch configuration

handleDebugEvents

public void handleDebugEvents(DebugEvent[] events)

Description copied from interface: IDebugEventSetListener

Notifies this listener of the given debug events. All of the events in the given event collection occurred at the same location the program be run or debugged.

Specified by:

handleDebugEvents in interface IDebugEventSetListener

Parameters:

events - the debug events