Eclipse Platform
Release 3.0

org.eclipse.debug.core
Class DebugPlugin

java.lang.Object
  extended byorg.eclipse.core.runtime.Plugin
      extended byorg.eclipse.debug.core.DebugPlugin
All Implemented Interfaces:
BundleActivator

public class DebugPlugin
extends Plugin

There is one instance of the debug plug-in available from DebugPlugin.getDefault(). The debug plug-in provides:

Clients may not instantiate or subclass this class.


Field Summary
static String ATTR_PROCESS_FACTORY_ID
          The launch configuration attribute that designates the process factory ID for the process factory to be used when creating a new process as a result of launching the launch configuration.
static int ERR_WORKING_DIRECTORY_NOT_SUPPORTED
          Status code indicating that the Eclipse runtime does not support launching a program with a working directory.
static String EXTENSION_POINT_BREAKPOINTS
          Simple identifier constant (value "breakpoints") for the breakpoints extension point.
static String EXTENSION_POINT_LAUNCH_CONFIGURATION_COMPARATORS
          Simple identifier constant (value "launchConfigurationComparators") for the launch configuration comparators extension point.
static String EXTENSION_POINT_LAUNCH_CONFIGURATION_TYPES
          Simple identifier constant (value "launchConfigurationTypes") for the launch configuration types extension point.
static String EXTENSION_POINT_LAUNCH_DELEGATES
          Simple identifier constant (value "launchDelegates") for the launch delegates extension point.
static String EXTENSION_POINT_LAUNCH_MODES
          Simple identifier constant (value "launchModes") for the source modes extension point.
static String EXTENSION_POINT_LOGICAL_STRUCTURE_TYPES
          Simple identifier constant (value "logicalStructureTypes") for the logical structure types extension point.
static String EXTENSION_POINT_PROCESS_FACTORIES
          Simple identifier constant (value "processFactories") for the process factories extension point.
static String EXTENSION_POINT_SOURCE_CONTAINER_TYPES
          Simple identifier constant (value "sourceContainerTypes") for the source container types extension point.
static String EXTENSION_POINT_SOURCE_LOCATORS
          Simple identifier constant (value "sourceLocators") for the source locators extension point.
static String EXTENSION_POINT_SOURCE_PATH_COMPUTERS
          Simple identifier constant (value "sourcePathComputers") for the source path computers extension point.
static String EXTENSION_POINT_STATUS_HANDLERS
          Simple identifier constant (value "statusHandlers") for the status handlers extension point.
static int INTERNAL_ERROR
          Status code indicating an unexpected internal error.
 
Fields inherited from class org.eclipse.core.runtime.Plugin
PLUGIN_PREFERENCE_SCOPE, PREFERENCES_DEFAULT_OVERRIDE_BASE_NAME, PREFERENCES_DEFAULT_OVERRIDE_FILE_NAME
 
Constructor Summary
DebugPlugin()
          Constructs the debug plug-in.
 
Method Summary
 void addDebugEventFilter(IDebugEventFilter filter)
          Adds the given debug event filter to the registered event filters.
 void addDebugEventListener(IDebugEventSetListener listener)
          Adds the given listener to the collection of registered debug event listeners.
 void asyncExec(Runnable r)
          Asynchronously executes the given runnable in a seperate thread, after debug event dispatch has completed.
static Process exec(String[] cmdLine, File workingDirectory)
          Convenience method that performs a runtime exec on the given command line in the context of the specified working directory, and returns the resulting process.
static Process exec(String[] cmdLine, File workingDirectory, String[] envp)
          Convenience method that performs a runtime exec on the given command line in the context of the specified working directory, and returns the resulting process.
 void fireDebugEventSet(DebugEvent[] events)
          Notifies all registered debug event set listeners of the given debug events.
 IBreakpointManager getBreakpointManager()
          Returns the breakpoint manager.
static DebugPlugin getDefault()
          Returns the singleton instance of the debug plug-in.
 IExpressionManager getExpressionManager()
          Returns the expression manager.
 ILaunchManager getLaunchManager()
          Returns the launch manager.
static ILogicalStructureType[] getLogicalStructureTypes(IValue value)
          Returns any logical structure types that have been contributed for the given value.
 IStatusHandler getStatusHandler(IStatus status)
          Returns the status handler registered for the given status, or null if none.
static String getUniqueIdentifier()
          Convenience method which returns the unique identifier of this plugin.
static void log(IStatus status)
          Logs the specified status with this plug-in's log.
static void log(Throwable t)
          Logs the specified throwable with this plug-in's log.
static void logDebugMessage(String message)
          Logs the given message if in debug mode.
static void logMessage(String message, Throwable throwable)
          Logs the given message with this plug-in's log and the given throwable or null if none.
static Document newDocument()
          Creates and returns a new XML document.
static IProcess newProcess(ILaunch launch, Process process, String label)
          Creates and returns a new process representing the given java.lang.Process.
static IProcess newProcess(ILaunch launch, Process process, String label, Map attributes)
          Creates and returns a new process representing the given java.lang.Process.
static Element parseDocument(String document)
          Parses the given string representing an XML document, returning its root element.
 void removeDebugEventFilter(IDebugEventFilter filter)
          Removes the given debug event filter from the registered event filters.
 void removeDebugEventListener(IDebugEventSetListener listener)
          Removes the given listener from the collection of registered debug event listeners.
static String serializeDocument(Document document)
          Serializes the given XML document into a string.
 void stop(BundleContext context)
          Stops this plug-in.
 
Methods inherited from class org.eclipse.core.runtime.Plugin
find, find, getBundle, getDescriptor, getLog, getPluginPreferences, getStateLocation, initializeDefaultPluginPreferences, internalInitializeDefaultPluginPreferences, isDebugging, openStream, openStream, savePluginPreferences, setDebugging, shutdown, start, startup, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

EXTENSION_POINT_LAUNCH_CONFIGURATION_TYPES

public static final String EXTENSION_POINT_LAUNCH_CONFIGURATION_TYPES
Simple identifier constant (value "launchConfigurationTypes") for the launch configuration types extension point.

Since:
2.0
See Also:
Constant Field Values

EXTENSION_POINT_LAUNCH_CONFIGURATION_COMPARATORS

public static final String EXTENSION_POINT_LAUNCH_CONFIGURATION_COMPARATORS
Simple identifier constant (value "launchConfigurationComparators") for the launch configuration comparators extension point.

Since:
2.0
See Also:
Constant Field Values

EXTENSION_POINT_BREAKPOINTS

public static final String EXTENSION_POINT_BREAKPOINTS
Simple identifier constant (value "breakpoints") for the breakpoints extension point.

Since:
2.0
See Also:
Constant Field Values

EXTENSION_POINT_STATUS_HANDLERS

public static final String EXTENSION_POINT_STATUS_HANDLERS
Simple identifier constant (value "statusHandlers") for the status handlers extension point.

Since:
2.0
See Also:
Constant Field Values

EXTENSION_POINT_SOURCE_LOCATORS

public static final String EXTENSION_POINT_SOURCE_LOCATORS
Simple identifier constant (value "sourceLocators") for the source locators extension point.

Since:
2.0
See Also:
Constant Field Values

EXTENSION_POINT_LAUNCH_MODES

public static final String EXTENSION_POINT_LAUNCH_MODES
Simple identifier constant (value "launchModes") for the source modes extension point.

Since:
3.0
See Also:
Constant Field Values

EXTENSION_POINT_LAUNCH_DELEGATES

public static final String EXTENSION_POINT_LAUNCH_DELEGATES
Simple identifier constant (value "launchDelegates") for the launch delegates extension point.

Since:
3.0
See Also:
Constant Field Values

EXTENSION_POINT_PROCESS_FACTORIES

public static final String EXTENSION_POINT_PROCESS_FACTORIES
Simple identifier constant (value "processFactories") for the process factories extension point.

Since:
3.0
See Also:
Constant Field Values

EXTENSION_POINT_LOGICAL_STRUCTURE_TYPES

public static final String EXTENSION_POINT_LOGICAL_STRUCTURE_TYPES
Simple identifier constant (value "logicalStructureTypes") for the logical structure types extension point.

Since:
3.0
See Also:
Constant Field Values

EXTENSION_POINT_SOURCE_CONTAINER_TYPES

public static final String EXTENSION_POINT_SOURCE_CONTAINER_TYPES
Simple identifier constant (value "sourceContainerTypes") for the source container types extension point.

Since:
3.0
See Also:
Constant Field Values

EXTENSION_POINT_SOURCE_PATH_COMPUTERS

public static final String EXTENSION_POINT_SOURCE_PATH_COMPUTERS
Simple identifier constant (value "sourcePathComputers") for the source path computers extension point.

Since:
3.0
See Also:
Constant Field Values

INTERNAL_ERROR

public static final int INTERNAL_ERROR
Status code indicating an unexpected internal error.

See Also:
Constant Field Values

ERR_WORKING_DIRECTORY_NOT_SUPPORTED

public static final int ERR_WORKING_DIRECTORY_NOT_SUPPORTED
Status code indicating that the Eclipse runtime does not support launching a program with a working directory. This feature is only available if Eclipse is run on a 1.3 runtime or higher.

A status handler may be registered for this error condition, and should return a Boolean indicating whether the program should be relaunched with the default working directory.

See Also:
Constant Field Values

ATTR_PROCESS_FACTORY_ID

public static final String ATTR_PROCESS_FACTORY_ID
The launch configuration attribute that designates the process factory ID for the process factory to be used when creating a new process as a result of launching the launch configuration.

Since:
3.0
See Also:
Constant Field Values
Constructor Detail

DebugPlugin

public DebugPlugin()
Constructs the debug plug-in.

An instance of this plug-in runtime class is automatically created when the facilities provided by this plug-in are required. Clients must never explicitly instantiate a plug-in runtime class.

Method Detail

getDefault

public static DebugPlugin getDefault()
Returns the singleton instance of the debug plug-in.


getUniqueIdentifier

public static String getUniqueIdentifier()
Convenience method which returns the unique identifier of this plugin.


addDebugEventListener

public void addDebugEventListener(IDebugEventSetListener listener)
Adds the given listener to the collection of registered debug event listeners. Has no effect if an identical listener is already registered.

Parameters:
listener - the listener to add
Since:
2.0

fireDebugEventSet

public void fireDebugEventSet(DebugEvent[] events)
Notifies all registered debug event set listeners of the given debug events. Events which are filtered by a registered debug event filter are not fired.

Parameters:
events - array of debug events to fire
Since:
2.0
See Also:
IDebugEventFilter, IDebugEventSetListener

asyncExec

public void asyncExec(Runnable r)
Asynchronously executes the given runnable in a seperate thread, after debug event dispatch has completed. If debug events are not currently being dispatched, the runnable is scheduled to run in a seperate thread immediately.

Parameters:
r - runnable to execute asynchronously
Since:
2.1

getBreakpointManager

public IBreakpointManager getBreakpointManager()
Returns the breakpoint manager.

Returns:
the breakpoint manager
See Also:
IBreakpointManager

getLaunchManager

public ILaunchManager getLaunchManager()
Returns the launch manager.

Returns:
the launch manager
See Also:
ILaunchManager

getStatusHandler

public IStatusHandler getStatusHandler(IStatus status)
Returns the status handler registered for the given status, or null if none.

Returns:
the status handler registered for the given status, or null if none
Since:
2.0

getExpressionManager

public IExpressionManager getExpressionManager()
Returns the expression manager.

Returns:
the expression manager
Since:
2.0
See Also:
IExpressionManager

removeDebugEventListener

public void removeDebugEventListener(IDebugEventSetListener listener)
Removes the given listener from the collection of registered debug event listeners. Has no effect if an identical listener is not already registered.

Parameters:
listener - the listener to remove
Since:
2.0

stop

public void stop(BundleContext context)
          throws Exception
Description copied from class: Plugin
Stops this plug-in.

This method should be re-implemented in subclasses that need to do something when the plug-in is shut down. Implementors should call the inherited method as late as possible to ensure that any system requirements can be met.

Plug-in shutdown code should be robust. In particular, this method should always make an effort to shut down the plug-in. Furthermore, the code should not assume that the plug-in was started successfully, as this method will be invoked in the event of a failure during startup.

Note 1: If a plug-in has been automatically started, this method will be automatically invoked by the platform when the platform is shut down.

Note 2: This method is intended to perform simple termination of the plug-in environment. The platform may terminate invocations that do not complete in a timely fashion.

Note 3: The supplied bundle context represents the plug-in to the OSGi framework. For security reasons, it is strongly recommended that this object should not be divulged.

Clients must never explicitly call this method.

Specified by:
stop in interface BundleActivator
Overrides:
stop in class Plugin
Parameters:
context - the bundle context for this plug-in
Throws:
Exception - if this method fails to shut down this plug-in

newProcess

public static IProcess newProcess(ILaunch launch,
                                  Process process,
                                  String label)
Creates and returns a new process representing the given java.lang.Process. A streams proxy is created for the I/O streams in the system process. The process is added to the given launch.

Parameters:
launch - the launch the process is contained in
process - the system process to wrap
label - the label assigned to the process
Returns:
the process
See Also:
IProcess

newProcess

public static IProcess newProcess(ILaunch launch,
                                  Process process,
                                  String label,
                                  Map attributes)
Creates and returns a new process representing the given java.lang.Process. A streams proxy is created for the I/O streams in the system process. The process is added to the given launch, and the process is initialized with the given attribute map. The process will be created by the IProcessFactory if it has been designated via the org.eclipse.debug.core.processFactories extension point for the process factory id indicated in the launch configuration associated with the launch.

Parameters:
launch - the launch the process is contained in
process - the system process to wrap
label - the label assigned to the process
attributes - initial values for the attribute map
Returns:
the process null can be returned if errors occur dealing with the process factory designated to create the process.
Since:
2.1
See Also:
IProcess

getLogicalStructureTypes

public static ILogicalStructureType[] getLogicalStructureTypes(IValue value)
Returns any logical structure types that have been contributed for the given value.

Parameters:
value - the value for which logical structure types have been requested
Returns:
logical structure types that have been contributed for the given value, possibly an empty collection
Since:
3.0

exec

public static Process exec(String[] cmdLine,
                           File workingDirectory)
                    throws CoreException
Convenience method that performs a runtime exec on the given command line in the context of the specified working directory, and returns the resulting process. If the current runtime does not support the specification of a working directory, the status handler for error code ERR_WORKING_DIRECTORY_NOT_SUPPORTED is queried to see if the exec should be re-executed without specifying a working directory.

Parameters:
cmdLine - the command line
workingDirectory - the working directory, or null
Returns:
the resulting process or null if the exec is cancelled
Throws:
CoreException
Since:
2.1
See Also:
Runtime

exec

public static Process exec(String[] cmdLine,
                           File workingDirectory,
                           String[] envp)
                    throws CoreException
Convenience method that performs a runtime exec on the given command line in the context of the specified working directory, and returns the resulting process. If the current runtime does not support the specification of a working directory, the status handler for error code ERR_WORKING_DIRECTORY_NOT_SUPPORTED is queried to see if the exec should be re-executed without specifying a working directory.

Parameters:
cmdLine - the command line
workingDirectory - the working directory, or null
envp - the environment variables set in the process, or null
Returns:
the resulting process or null if the exec is cancelled
Throws:
CoreException
Since:
3.0
See Also:
Runtime

addDebugEventFilter

public void addDebugEventFilter(IDebugEventFilter filter)
Adds the given debug event filter to the registered event filters. Has no effect if an identical filter is already registerd.

Parameters:
filter - debug event filter
Since:
2.0

removeDebugEventFilter

public void removeDebugEventFilter(IDebugEventFilter filter)
Removes the given debug event filter from the registered event filters. Has no effect if an identical filter is not already registered.

Parameters:
filter - debug event filter
Since:
2.0

logDebugMessage

public static void logDebugMessage(String message)
Logs the given message if in debug mode.

Parameters:
message - the message to log
Since:
2.0

logMessage

public static void logMessage(String message,
                              Throwable throwable)
Logs the given message with this plug-in's log and the given throwable or null if none.

Parameters:
message - the message to log
throwable - the exception that occurred or null if none

log

public static void log(IStatus status)
Logs the specified status with this plug-in's log.

Parameters:
status - status to log
Since:
2.0

log

public static void log(Throwable t)
Logs the specified throwable with this plug-in's log.

Parameters:
t - throwable to log
Since:
2.0

newDocument

public static Document newDocument()
                            throws CoreException
Creates and returns a new XML document.

Returns:
a new XML document
Throws:
CoreException - if unable to create a new document
Since:
3.0

serializeDocument

public static String serializeDocument(Document document)
                                throws CoreException
Serializes the given XML document into a string.

Parameters:
document - XML document to serialize
Returns:
a string representing the given document
Throws:
CoreException - if unable to serialize the document
Since:
3.0

parseDocument

public static Element parseDocument(String document)
                             throws CoreException
Parses the given string representing an XML document, returning its root element.

Parameters:
document - XML document as a string
Returns:
the document's root element
Throws:
CoreException - if unable to parse the document
Since:
3.0

Eclipse Platform
Release 3.0

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.