Package 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
  • access to the memory block manager
  • debug event notification
  • status handlers
Restriction:
This class is not intended to be sub-classed by clients.
Restriction:
This class is not intended to be instantiated by clients.

  • Field Details

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • EXTENSION_POINT_LOGICAL_STRUCTURE_PROVIDERS

      public static final String EXTENSION_POINT_LOGICAL_STRUCTURE_PROVIDERS
      Simple identifier constant (value "logicalStructureProviders") for the logical structure types extension point.
      Since:
      3.1
      See Also:

    • 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:

    • 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:

    • EXTENSION_POINT_LAUNCH_OPTIONS

      public static final String EXTENSION_POINT_LAUNCH_OPTIONS
      Simple identifier constant for the launch options extension point
      Since:
      3.3
      See Also:

    • EXTENSION_POINT_BREAKPOINT_IMPORT_PARTICIPANTS

      public static final String EXTENSION_POINT_BREAKPOINT_IMPORT_PARTICIPANTS
      Simple identifier constant for the breakpoint import participant extension point
      Since:
      3.5
      See Also:

    • EXTENSION_POINT_STEP_FILTERS

      public static final String EXTENSION_POINT_STEP_FILTERS
      Simple identifier constant (value "stepFilters") for the step filters extension point.
      Since:
      3.10
      See Also:

    • ERROR

      public static final int ERROR
      Status code indicating an unexpected error.
      Since:
      3.4
      See Also:

    • INTERNAL_ERROR

      public static final int INTERNAL_ERROR
      Status code indicating an unexpected internal error. Internal errors should never be displayed to the user in dialogs or status text. Internal error messages are not translated.
      See Also:

    • 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 re-launched with the default working directory.

      See Also:

    • 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:

    • ATTR_CAPTURE_OUTPUT

      public static final String ATTR_CAPTURE_OUTPUT
      The launch attribute that designates whether or not it's associated launch should capture output. Value is a string representing a boolean - true or false. When unspecified, the default value is considered true.
      Since:
      3.1
      See Also:

    • ATTR_LAUNCH_TIMESTAMP

      public static final String ATTR_LAUNCH_TIMESTAMP
      The launch attribute that stores the time stamp of when a launch configuration was launched. Value is Long.toString(long) of System.currentTimeMillis().
      Since:
      3.6
      See Also:

    • ATTR_TERMINATE_TIMESTAMP

      public static final String ATTR_TERMINATE_TIMESTAMP
      The launch attribute that stores the time stamp of when a launch configuration was launched. Value is Long.toString(long) of System.currentTimeMillis().
      Since:
      3.15
      See Also:

    • ATTR_CONSOLE_ENCODING

      public static final String ATTR_CONSOLE_ENCODING
      This launch attribute designates the encoding to be used by the console associated with the launch.

      For release 3.3, the system encoding is used when unspecified. Since 3.4, the inherited encoding is used when unspecified. See ILaunchManager for a description in getEncoding(ILaunchConfiguration).

      Value of this constant is the same as the value of the old IDebugUIConstants.ATTR_CONSOLE_ENCODING constant for backward compatibility.

      Since:
      3.3
      See Also:

    • ATTR_FORCE_SYSTEM_CONSOLE_ENCODING

      public static final String ATTR_FORCE_SYSTEM_CONSOLE_ENCODING
      This launch attribute forces system encoding to be used by the console associated with the launch, independently on other attributes. Since 3.20, this flag is used by ILaunchManager to define encoding in getEncoding(ILaunchConfiguration).
      Since:
      3.20
      See Also:

    • ATTR_MERGE_OUTPUT

      public static final String ATTR_MERGE_OUTPUT
      Launch configuration attribute - a boolean value indicating whether a configuration should be launched with merged error and standard output. Merging output can ensure the process output appears in console in same order as the process produce it. On the other hand the error output can not be colored different from standard output anymore. Default value is false.
      Since:
      3.14
      See Also:

    • PREF_DELETE_CONFIGS_ON_PROJECT_DELETE

      public static final String PREF_DELETE_CONFIGS_ON_PROJECT_DELETE
      Boolean preference key (value org.eclipse.debug.core.PREF_DELETE_CONFIGS_ON_PROJECT_DELETE) that controls whether to delete associated configurations when a project is deleted. Default value is false.
      Since:
      3.7
      See Also:

    • ATTR_BREAKPOINT_IS_DELETED

      public static final String ATTR_BREAKPOINT_IS_DELETED
      Deleted breakpoint marker attribute (value "org.eclipse.debug.core.breakpointIsDeleted"). The attribute is a boolean corresponding to the deleted state of a breakpoint.
      Since:
      3.7
      See Also:

    • ATTR_ENVIRONMENT

      public static final String ATTR_ENVIRONMENT
      Attribute key for the environment used when an IProcess was run
      Since:
      3.8
      See Also:

    • ATTR_WORKING_DIRECTORY

      public static final String ATTR_WORKING_DIRECTORY
      Attribute key for the path of the working directory for an IProcess
      Since:
      3.8
      See Also:

    • ATTR_PATH

      public static final String ATTR_PATH
      Attribute key for path of the executable that launched an IProcess
      Since:
      3.8
      See Also:

    • ATTR_TERMINATE_DESCENDANTS

      public static final String ATTR_TERMINATE_DESCENDANTS
      Launch configuration attribute that designates whether or not the descendants of the IProcess associated to a launch of this configuration should be terminated if the main-process is terminated. The descendants (also called child- or sub-processes) of a operating system process are the processes started by that process. Value is a string representing a boolean - true or false. When unspecified, the default value is considered true.
      Since:
      3.18
      See Also:

  • Constructor Details

    • 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 Details

    • getDefault

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

    • getUniqueIdentifier

      public static String getUniqueIdentifier()
      Convenience method which returns the unique identifier of this plug-in.
      Returns:
      debug plug-in identifier

    • 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:

    • asyncExec

      public void asyncExec(Runnable r)
      Asynchronously executes the given runnable in a separate thread, after debug event dispatch has completed. If debug events are not currently being dispatched, the runnable is scheduled to run in a separate 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:

    • getLaunchManager

      public ILaunchManager getLaunchManager()
      Returns the launch manager.
      Returns:
      the launch manager
      See Also:

    • getMemoryBlockManager

      public IMemoryBlockManager getMemoryBlockManager()
      Returns the memory block manager.
      Returns:
      the memory block manager.
      Since:
      3.1
      See Also:

    • getStatusHandler

      public IStatusHandler getStatusHandler(IStatus status)
      Returns the status handler registered for the given status, or null if none.
      Parameters:
      status - status for which a status handler has been requested
      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:

    • 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.

      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.

      Note 4: This method and the Plugin.start(BundleContext) may be called from separate threads, but the OSGi framework ensures that both methods will not be called simultaneously.

      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

    • start

      public void start(BundleContext context) throws Exception
      Description copied from class: Plugin
      Starts up this plug-in.

      This method should be overridden in subclasses that need to do something when this plug-in is started. Implementors should call the inherited method at the first possible point to ensure that any system requirements can be met.

      If this method throws an exception, it is taken as an indication that plug-in initialization has failed; as a result, the plug-in will not be activated; moreover, the plug-in will be marked as disabled and ineligible for activation for the duration.

      Note 1: This method is automatically invoked by the platform the first time any code in the plug-in is executed.

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

      Note 3: The class loader typically has monitors acquired during invocation of this method. It is strongly recommended that this method avoid synchronized blocks or other thread locking mechanisms, as this would lead to deadlock vulnerability.

      Note 4: 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.

      Note 5: This method and the Plugin.stop(BundleContext) may be called from separate threads, but the OSGi framework ensures that both methods will not be called simultaneously.

      Clients must never explicitly call this method.
      Specified by:
      start in interface BundleActivator
      Overrides:
      start in class Plugin
      Parameters:
      context - the bundle context for this plug-in
      Throws:
      Exception - if this plug-in did not start up properly

    • 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.

      If the launch configuration associated with the given launch specifies a process factory, it will be used to instantiate the new process.

      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:

    • newProcess

      public static IProcess newProcess(ILaunch launch, Process process, String label, Map<String,String> 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.

      If the launch configuration associated with the given launch specifies a process factory, it will be used to instantiate the new process.

      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:

    • 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

    • getDefaultStructureType

      public static ILogicalStructureType getDefaultStructureType(ILogicalStructureType[] types)
      Returns the default logical structure type among the given combination of logical structure types, or null if none. When the given combination of logical structure type is applicable for a value, the default logical structure type is used to display a value.
      Parameters:
      types - a combination of structures applicable to a value
      Returns:
      the default structure that should be used to display the value or null if none
      Since:
      3.1

    • setDefaultStructureType

      public static void setDefaultStructureType(ILogicalStructureType[] types, ILogicalStructureType def)
      Sets the default logical structure type among the given combination of logical structure types. The logical structure types provided should all be applicable to a single value. Specifying null indicates there is no default logical structure for the given combination of types.
      Parameters:
      types - a combination of logical structure types applicable to a value
      def - the default logical structure among the given combination of types or null if none
      Since:
      3.1

    • 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 canceled
      Throws:
      CoreException - if the exec fails
      Since:
      2.1
      See Also:

    • 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 canceled
      Throws:
      CoreException - if the exec fails
      Since:
      3.0
      See Also:

    • exec

      public static Process exec(String[] cmdLine, File workingDirectory, String[] envp, boolean mergeOutput) 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
      mergeOutput - if true the error stream will be merged with standard output stream and both can be read through the same output stream
      Returns:
      the resulting process or null if the exec is canceled
      Throws:
      CoreException - if the exec fails
      Since:
      3.14
      See Also:

    • 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 registered.
      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

    • parseArguments

      public static String[] parseArguments(String args)
      Parses the given command line into separate arguments that can be passed to DebugPlugin.exec(String[], File). Embedded quotes and backslashes are interpreted, i.e. the resulting arguments are in the form that will be passed to an invoked process.

      The reverse operation is renderArguments(String[], int[]).

      Parameters:
      args - command line arguments as a single string
      Returns:
      individual arguments
      Since:
      3.1
      See Also:

    • splitArguments

      public static String[] splitArguments(String args)
      Splits the given command line into separate arguments that can be concatenated with a space as joiner. Embedded quotes and backslashes are kept as is (i.e. not interpreted).

      Use this method to avoid e.g. losing quotes around an argument like "${env_var:A}", which may later be substituted by a string that contains spaces.

      Parameters:
      args - command line arguments as a single string
      Returns:
      individual arguments in original form
      Since:
      3.10

    • renderArguments

      public static String renderArguments(String[] arguments, int[] segments)
      Renders the given array of argument strings into a single command line.

      If an argument contains whitespace, it it quoted. Contained quotes or backslashes will be escaped.

      If segments is not null, the array is filled with the offsets of the start positions of arguments 1 to arguments.length - 1, as rendered in the resulting string.

      Parameters:
      arguments - the command line arguments
      segments - an array of size arguments.length - 1 or null
      Returns:
      the command line
      Since:
      3.8
      See Also:

    • setUseStepFilters

      public static void setUseStepFilters(boolean useStepFilters)
      Sets whether step filters should be applied to step commands. This setting is a global option applied to all registered debug targets.
      Parameters:
      useStepFilters - whether step filters should be applied to step commands
      Since:
      3.3
      See Also:

    • isUseStepFilters

      public static boolean isUseStepFilters()
      Returns whether step filters are applied to step commands.
      Returns:
      whether step filters are applied to step commands
      Since:
      3.3
      See Also:

    • getStepFilters

      public static IStepFilter[] getStepFilters(String modelIdentifier)
      Returns any step filters that have been contributed for the given model identifier.
      Parameters:
      modelIdentifier - the model identifier
      Returns:
      step filters that have been contributed for the given model identifier, possibly an empty collection
      Since:
      3.10
      See Also:

    • getAdapter

      public static Object getAdapter(Object element, Class<?> type)
      Returns an adapter of the specified type for the given object or null if none. The object itself is returned if it is an instance of the specified type. If the object is adaptable and does not subclass PlatformObject, and does not provide the specified adapter directly, the platform's adapter manager is consulted for an adapter.
      Parameters:
      element - element to retrieve adapter for
      type - adapter type
      Returns:
      adapter or null
      Since:
      3.4