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 subclassed by clients.
-
Restriction:
- This class is not intended to be instantiated by clients.
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 separate
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. |
static
Object
|
getAdapter
(
Object element,
Class type)
Returns an adapter of the specified type for the given object or null
if none. |
IBreakpointManager
|
getBreakpointManager
()
Returns the breakpoint manager. |
static
DebugPlugin
|
getDefault
()
Returns the singleton instance of the debug plug-in. |
static
ILogicalStructureType
|
getDefaultStructureType
(
ILogicalStructureType[] types)
Returns the default logical structure type among the given combination of
logical structure types, or null if none. |
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. |
IMemoryBlockManager
|
getMemoryBlockManager
()
Returns the memory block manager. |
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 plug-in. |
static boolean
|
isUseStepFilters
()
Returns whether step filters are applied to step commands. |
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
String[]
|
parseArguments
(
String args)
Parses the given command line into separate arguments that can be passed to
DebugPlugin.exec(String[], File) . |
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. |
static void
|
setDefaultStructureType
(
ILogicalStructureType[] types,
ILogicalStructureType def)
Sets the default logical structure type among the given combination of logical structure
types. |
static void
|
setUseStepFilters
(boolean useStepFilters)
Sets whether step filters should be applied to step commands. |
void
|
start
(
BundleContext context)
Starts up this plug-in. |
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,
startup,
toString
|
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
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
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.
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
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
getMemoryBlockManager
public
IMemoryBlockManager getMemoryBlockManager()
- Returns the memory block manager.
-
-
Returns:
- the memory block manager.
-
Since:
- 3.1
-
See Also:
-
IMemoryBlockManager
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:
-
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.
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 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
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 slashes
are escaped.
-
-
Parameters:
-
args
- command line arguments as a single string
-
Returns:
- individual arguments
-
Since:
- 3.1
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
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
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.