Package org.eclipse.debug.core

Class 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 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_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:
        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

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • ERROR

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

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

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        IMarker.getAttribute(String, boolean), Constant Field Values

      • 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:
        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.
        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:
        IDebugEventFilter, IDebugEventSetListener

      • 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

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

      • 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:
        IProcess, IProcessFactory

      • 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:
        IProcess, IProcessFactory

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

      • 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:
        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 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:
        renderArguments(String[], int[])

      • 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:
        parseArguments(String)

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

      • 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:
        IStepFilters, IStepFiltersHandler

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

      • 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