Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.debug.core
Class DebugPlugin

    java.lang.Object
      org.eclipse.core.runtime.Plugin
          org.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:

- access to the breakpoint manager
- access to the launch manager
- access to the expression manager
- access to the registered launcher extensions
- debug event notification
- status handlers

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

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