JPDADebugger (JPDA Debugger API)

java.lang.Object
- org.netbeans.api.debugger.jpda.JPDADebugger

public abstract class JPDADebugger
extends Object

Represents one JPDA debugger session (one VirtualMachine).

How to obtain it from DebuggerEngine:

    JPDADebugger jpdaDebugger = (JPDADebugger) debuggerEngine.lookup 
        (JPDADebugger.class);

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static interface JPDADebugger.Registration
Declarative registration of a JPDADebugger implementation.

Nested Classes
Modifier and Type	Class and Description
`static interface`	`JPDADebugger.Registration` Declarative registration of a JPDADebugger implementation.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ENGINE_ID` ID of JPDA Debugger Engine.
`static String`	`PROP_BREAKPOINTS_ACTIVE` Property name constant.
`static String`	`PROP_CLASSES_FIXED` Property name constant.
`static String`	`PROP_CURRENT_CALL_STACK_FRAME` Name of property for current stack frame.
`static String`	`PROP_CURRENT_THREAD` Name of property for current thread.
`static String`	`PROP_STATE` Name of property for state of debugger.
`static String`	`PROP_SUSPEND` Property name constant.
`static String`	`PROP_THREAD_DIED` Property name constant.
`static String`	`PROP_THREAD_GROUP_ADDED` Property name constant.
`static String`	`PROP_THREAD_STARTED` Property name constant.
`static String`	`SESSION_ID` ID of JPDA Debugger Engine.
`static int`	`STATE_DISCONNECTED` Debugger state constant.
`static int`	`STATE_RUNNING` Debugger state constant.
`static int`	`STATE_STARTING` Debugger state constant.
`static int`	`STATE_STOPPED` Debugger state constant.
`static int`	`SUSPEND_ALL` Suspend property value constant.
`static int`	`SUSPEND_EVENT_THREAD` Suspend property value constant.

Constructor Summary

Constructors
Constructor and Description

JPDADebugger()

Constructors
Constructor and Description
`JPDADebugger()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract void`	`addPropertyChangeListener(PropertyChangeListener l)` Adds property change listener.
`abstract void`	`addPropertyChangeListener(String propertyName, PropertyChangeListener l)` Adds property change listener.
`static JPDADebugger`	`attach(String hostName, int portNumber, Object[] services)` This utility method helps to start a new JPDA debugger session.
`static JPDADebugger`	`attach(String name, Object[] services)` This utility method helps to start a new JPDA debugger session.
`boolean`	`canBeModified()` Determines if the target debuggee can be modified.
`abstract boolean`	`canFixClasses()` Returns `true` if this debugger supports fix & continue (HotSwap).
`boolean`	`canGetInstanceInfo()` Test whether the debuggee supports accessing of class instances, instance counts, and referring objects.
`abstract boolean`	`canPopFrames()` Returns `true` if this debugger supports Pop action.
`JPDAStep`	`createJPDAStep(int size, int depth)` Creates a new `JPDAStep`.
`Variable`	`createMirrorVar(Object obj)` Create a mirror object in the target virtual machine
`Variable`	`createMirrorVar(Object obj, boolean isPrimitive)` Create a mirror object in the target virtual machine
`abstract Variable`	`evaluate(String expression)` Evaluates given expression in the current context.
`protected void`	`fireBreakpointEvent(JPDABreakpoint breakpoint, JPDABreakpointEvent event)` Helper method that fires JPDABreakpointEvent on JPDABreakpoints.
`abstract void`	`fixClasses(Map<String,byte[]> classes)` Implements fix & continue (HotSwap).
`List<JPDAClassType>`	`getAllClasses()` Get the list of all classes in the debuggee.
`boolean`	`getBreakpointsActive()` Test, if breakpoints are active.
`List<JPDAClassType>`	`getClassesByName(String name)` Get the list of all classes mathing the given name in the debuggee.
`abstract CallStackFrame`	`getCurrentCallStackFrame()` Returns current stack frame or null.
`abstract JPDAThread`	`getCurrentThread()` Returns current thread or null.
`long[]`	`getInstanceCounts(List<JPDAClassType> classTypes)` Retrieves the number of instances of each class in the list.
`Session`	`getSession()` Get the session associated with this debugger.
`abstract SmartSteppingFilter`	`getSmartSteppingFilter()` Returns instance of SmartSteppingFilter.
`abstract int`	`getState()` Returns current state of JPDA debugger.
`abstract int`	`getSuspend()` Gets value of suspend property.
`ThreadsCollector`	`getThreadsCollector()` Get the collector of threads.
`static void`	`launch(String mainClassName, String[] args, String classPath, boolean suspend)` This utility method helps to start a new JPDA debugger session.
`static JPDADebugger`	`listen(com.sun.jdi.connect.ListeningConnector connector, Map<String,? extends com.sun.jdi.connect.Connector.Argument> args, Object[] services)` This utility method helps to start a new JPDA debugger session.
`abstract void`	`removePropertyChangeListener(PropertyChangeListener l)` Removes property change listener.
`abstract void`	`removePropertyChangeListener(String propertyName, PropertyChangeListener l)` Removes property change listener.
`void`	`setBreakpointsActive(boolean active)` Set all breakpoints to be active / inactive.
`abstract void`	`setSuspend(int s)` Sets value of suspend property.
`static void`	`startListening(com.sun.jdi.connect.ListeningConnector connector, Map<String,? extends com.sun.jdi.connect.Connector.Argument> args, Object[] services)` This utility method helps to start a new JPDA debugger session.
`static DebuggerEngine[]`	`startListeningAndGetEngines(com.sun.jdi.connect.ListeningConnector connector, Map<String,? extends com.sun.jdi.connect.Connector.Argument> args, Object[] services)` This utility method helps to start a new JPDA debugger session.
`abstract void`	`waitRunning()` Waits till the Virtual Machine is started and returns `DebuggerStartException` if some problem occurres.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - PROP_STATE
```
public static final String PROP_STATE
```
    Name of property for state of debugger.
    
    See Also:
    
    Constant Field Values
  - PROP_CURRENT_THREAD
```
public static final String PROP_CURRENT_THREAD
```
    Name of property for current thread.
    
    See Also:
    
    Constant Field Values
  - PROP_CURRENT_CALL_STACK_FRAME
```
public static final String PROP_CURRENT_CALL_STACK_FRAME
```
    Name of property for current stack frame.
    
    See Also:
    
    Constant Field Values
  - PROP_SUSPEND
```
public static final String PROP_SUSPEND
```
    Property name constant.
    
    See Also:
    
    Constant Field Values
  - PROP_THREAD_STARTED
```
public static final String PROP_THREAD_STARTED
```
    Property name constant.
    
    Since:
    
    2.16
    
    See Also:
    
    Constant Field Values
  - PROP_THREAD_DIED
```
public static final String PROP_THREAD_DIED
```
    Property name constant.
    
    Since:
    
    2.16
    
    See Also:
    
    Constant Field Values
  - PROP_THREAD_GROUP_ADDED
```
public static final String PROP_THREAD_GROUP_ADDED
```
    Property name constant.
    
    Since:
    
    2.16
    
    See Also:
    
    Constant Field Values
  - PROP_CLASSES_FIXED
```
public static final String PROP_CLASSES_FIXED
```
    Property name constant.
    
    Since:
    
    2.25
    
    See Also:
    
    Constant Field Values
  - PROP_BREAKPOINTS_ACTIVE
```
public static final String PROP_BREAKPOINTS_ACTIVE
```
    Property name constant. Fired when breakpoints are activated / deactivated.
    
    Since:
    
    2.42
    
    See Also:
    
    Constant Field Values
  - SUSPEND_ALL
```
public static final int SUSPEND_ALL
```
    Suspend property value constant.
    
    See Also:
    
    Constant Field Values
  - SUSPEND_EVENT_THREAD
```
public static final int SUSPEND_EVENT_THREAD
```
    Suspend property value constant.
    
    See Also:
    
    Constant Field Values
  - STATE_STARTING
```
public static final int STATE_STARTING
```
    Debugger state constant.
    
    See Also:
    
    Constant Field Values
  - STATE_RUNNING
```
public static final int STATE_RUNNING
```
    Debugger state constant.
    
    See Also:
    
    Constant Field Values
  - STATE_STOPPED
```
public static final int STATE_STOPPED
```
    Debugger state constant.
    
    See Also:
    
    Constant Field Values
  - STATE_DISCONNECTED
```
public static final int STATE_DISCONNECTED
```
    Debugger state constant.
    
    See Also:
    
    Constant Field Values
  - ENGINE_ID
```
public static final String ENGINE_ID
```
    ID of JPDA Debugger Engine.
    
    See Also:
    
    Constant Field Values
  - SESSION_ID
```
public static final String SESSION_ID
```
    ID of JPDA Debugger Engine.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - JPDADebugger
```
public JPDADebugger()
```
- Method Detail
  - launch
```
public static void launch(String mainClassName,
                          String[] args,
                          String classPath,
                          boolean suspend)
```
    This utility method helps to start a new JPDA debugger session. Its implementation use LaunchingDICookie and DebuggerManager.getDebuggerManager().
    
    Parameters:
    
    mainClassName - a name or main class
    
    args - command line arguments
    
    classPath - a classPath
    
    suspend - if true session will be suspended
  - listen
```
public static JPDADebugger listen(com.sun.jdi.connect.ListeningConnector connector,
                                  Map<String,? extends com.sun.jdi.connect.Connector.Argument> args,
                                  Object[] services)
                           throws DebuggerStartException
```
    This utility method helps to start a new JPDA debugger session. Its implementation use ListeningDICookie and DebuggerManager.getDebuggerManager().
    Parameters:
    
    connector - The listening connector
    
    args - The arguments
    services - The additional services, which are added to the debugger session lookup.
    It is expected, that one element in the services array is a Map with following setup properties:
    
    name with the value being the session name as String,
    
    sourcepath with the ClassPath value containing class path of sources used by debugger,
    
    jdksources with the ClassPath value containing class path of platform sources,
    
    listeningCP optional String representation of source class path which is in compile-on-save mode, which we listen on for artifacts changes,
    
    baseDir with the debugging project's base directory as File.
    Throws:
    
    DebuggerStartException
  - startListening
```
public static void startListening(com.sun.jdi.connect.ListeningConnector connector,
                                  Map<String,? extends com.sun.jdi.connect.Connector.Argument> args,
                                  Object[] services)
                           throws DebuggerStartException
```
    This utility method helps to start a new JPDA debugger session. Its implementation use ListeningDICookie and DebuggerManager.getDebuggerManager().
    
    Parameters:
    
    connector - The listening connector
    
    args - The arguments
    
    services - The additional services, which are added to the debugger session lookup.
    See JPDADebugger.listen(com.sun.jdi.connect.ListeningConnector, java.util.Map, java.lang.Object[]) for a more detailed description of this argument.
    
    Throws:
    
    DebuggerStartException - when DebuggerManager.startDebugging(org.netbeans.api.debugger.DebuggerInfo) returns an empty array
  - startListeningAndGetEngines
```
public static DebuggerEngine[] startListeningAndGetEngines(com.sun.jdi.connect.ListeningConnector connector,
                                                           Map<String,? extends com.sun.jdi.connect.Connector.Argument> args,
                                                           Object[] services)
                                                    throws DebuggerStartException
```
    This utility method helps to start a new JPDA debugger session. Its implementation use ListeningDICookie and DebuggerManager.getDebuggerManager(). It's identical to JPDADebugger.startListening(com.sun.jdi.connect.ListeningConnector, java.util.Map, java.lang.Object[]), but returns the started engines.
    
    Parameters:
    
    connector - The listening connector
    
    args - The arguments
    
    services - The additional services, which are added to the debugger session lookup.
    See JPDADebugger.listen(com.sun.jdi.connect.ListeningConnector, java.util.Map, java.lang.Object[]) for a more detailed description of this argument.
    
    Returns:
    
    A non-empty array of started engines (since 2.26)
    
    Throws:
    
    DebuggerStartException - when DebuggerManager.startDebugging(org.netbeans.api.debugger.DebuggerInfo) returns an empty array
    
    Since:
    
    2.26
  - attach
```
public static JPDADebugger attach(String hostName,
                                  int portNumber,
                                  Object[] services)
                           throws DebuggerStartException
```
    This utility method helps to start a new JPDA debugger session. Its implementation use AttachingDICookie and DebuggerManager.getDebuggerManager().
    Parameters:
    
    hostName - a name of computer to attach to
    
    portNumber - a port number
    services - The additional services, which are added to the debugger session lookup.
    It is expected, that one element in the services array is a Map with following setup properties:
    
    name with the value being the session name as String,
    
    sourcepath with the ClassPath value containing class path of sources used by debugger,
    
    jdksources with the ClassPath value containing class path of platform sources,
    
    listeningCP optional String representation of source class path which is in compile-on-save mode, which we listen on for artifacts changes,
    
    baseDir with the debugging project's base directory as File.
    Throws:
    
    DebuggerStartException
  - attach
```
public static JPDADebugger attach(String name,
                                  Object[] services)
                           throws DebuggerStartException
```
    This utility method helps to start a new JPDA debugger session. Its implementation use AttachingDICookie and DebuggerManager.getDebuggerManager().
    
    Parameters:
    
    name - a name of shared memory block
    
    services - The additional services, which are added to the debugger session lookup.
    See JPDADebugger.attach(java.lang.String, int, java.lang.Object[]) for a more detailed description of this argument.
    
    Throws:
    
    DebuggerStartException
  - getState
```
public abstract int getState()
```
    Returns current state of JPDA debugger.
    
    Returns:
    
    current state of JPDA debugger
    
    See Also:
    
    JPDADebugger.STATE_STARTING, JPDADebugger.STATE_RUNNING, JPDADebugger.STATE_STOPPED, JPDADebugger.STATE_DISCONNECTED
  - getSuspend
```
public abstract int getSuspend()
```
    Gets value of suspend property.
    
    Returns:
    
    value of suspend property
  - setSuspend
```
public abstract void setSuspend(int s)
```
    Sets value of suspend property.
    
    Parameters:
    
    s - a new value of suspend property
  - getCurrentThread
```
public abstract JPDAThread getCurrentThread()
```
    Returns current thread or null.
    
    Returns:
    
    current thread or null
  - getCurrentCallStackFrame
```
public abstract CallStackFrame getCurrentCallStackFrame()
```
    Returns current stack frame or null.
    
    Returns:
    
    current stack frame or null
  - evaluate
```
public abstract Variable evaluate(String expression)
                           throws InvalidExpressionException
```
    Evaluates given expression in the current context.
    
    Parameters:
    
    expression - a expression to be evaluated
    
    Returns:
    
    current value of given expression
    
    Throws:
    
    InvalidExpressionException
  - waitRunning
```
public abstract void waitRunning()
                          throws DebuggerStartException
```
    Waits till the Virtual Machine is started and returns DebuggerStartException if some problem occurres.
    
    Throws:
    
    DebuggerStartException - is some problems occurres during debugger start
    
    See Also:
    
    AbstractDICookie.getVirtualMachine()
  - canFixClasses
```
public abstract boolean canFixClasses()
```
    Returns true if this debugger supports fix & continue (HotSwap).
    
    Returns:
    
    true if this debugger supports fix & continue
  - canPopFrames
```
public abstract boolean canPopFrames()
```
    Returns true if this debugger supports Pop action.
    
    Returns:
    
    true if this debugger supports Pop action
  - canBeModified
```
public boolean canBeModified()
```
    Determines if the target debuggee can be modified.
    
    Returns:
    
    true if the target debuggee can be modified or when this information is not available (on JDK 1.4).
    
    Since:
    
    2.3
  - fixClasses
```
public abstract void fixClasses(Map<String,byte[]> classes)
```
    Implements fix & continue (HotSwap). Map should contain class names as a keys, and byte[] arrays as a values.
    
    Parameters:
    
    classes - a map from class names to be fixed to byte[]
  - getSmartSteppingFilter
```
public abstract SmartSteppingFilter getSmartSteppingFilter()
```
    Returns instance of SmartSteppingFilter.
    
    Returns:
    
    instance of SmartSteppingFilter
  - fireBreakpointEvent
```
protected void fireBreakpointEvent(JPDABreakpoint breakpoint,
                                   JPDABreakpointEvent event)
```
    Helper method that fires JPDABreakpointEvent on JPDABreakpoints.
    
    Parameters:
    
    breakpoint - a breakpoint to be changed
    
    event - a event to be fired
  - getBreakpointsActive
```
public boolean getBreakpointsActive()
```
    Test, if breakpoints are active.
    
    Returns:
    
    true when breakpoints are active, false otherwise. The default implementation returns true, to be overridden when needed.
    
    Since:
    
    2.42
  - setBreakpointsActive
```
public void setBreakpointsActive(boolean active)
```
    Set all breakpoints to be active / inactive. Activation or deactivation of breakpoints should not alter the enabled/disabled state of individual breakpoints. The default implementation does nothing, override together with JPDADebugger.getBreakpointsActive() when needed.
    
    Parameters:
    
    active - true to make all breakpoints active, false to make all breakpoints inactive.
    
    Since:
    
    2.42
  - addPropertyChangeListener
```
public abstract void addPropertyChangeListener(PropertyChangeListener l)
```
    Adds property change listener.
    
    Parameters:
    
    l - new listener.
  - removePropertyChangeListener
```
public abstract void removePropertyChangeListener(PropertyChangeListener l)
```
    Removes property change listener.
    
    Parameters:
    
    l - removed listener.
  - addPropertyChangeListener
```
public abstract void addPropertyChangeListener(String propertyName,
                                               PropertyChangeListener l)
```
    Adds property change listener.
    
    Parameters:
    
    propertyName - a name of property to listen on
    
    l - new listener.
  - removePropertyChangeListener
```
public abstract void removePropertyChangeListener(String propertyName,
                                                  PropertyChangeListener l)
```
    Removes property change listener.
    
    Parameters:
    
    propertyName - a name of property to listen on
    
    l - removed listener.
  - createJPDAStep
```
public JPDAStep createJPDAStep(int size,
                               int depth)
```
    Creates a new JPDAStep. Parameters correspond to JPDAStep constructor.
    
    Returns:
    
    JPDAStep
    
    Throws:
    
    UnsupportedOperationException - If not overridden
  - canGetInstanceInfo
```
public boolean canGetInstanceInfo()
```
    Test whether the debuggee supports accessing of class instances, instance counts, and referring objects.
    
    Returns:
    
    true when the feature is supported, false otherwise.
    
    See Also:
    
    JPDADebugger.getInstanceCounts(java.util.List<org.netbeans.api.debugger.jpda.JPDAClassType>), JPDAClassType.getInstanceCount(), JPDAClassType.getInstances(long), ObjectVariable.getReferringObjects(long)
  - getAllClasses
```
public List<JPDAClassType> getAllClasses()
```
    Get the list of all classes in the debuggee.
    
    Returns:
    
    The list of all classes.
  - getClassesByName
```
public List<JPDAClassType> getClassesByName(String name)
```
    Get the list of all classes mathing the given name in the debuggee.
    
    Returns:
    
    The list of classes.
  - createMirrorVar
```
public Variable createMirrorVar(Object obj)
                         throws InvalidObjectException
```
    Create a mirror object in the target virtual machine
    
    Parameters:
    
    obj - the object to create the mirror from
    
    Returns:
    
    variable containing the mirror value
    
    Throws:
    
    InvalidObjectException - when the mirror operation fails
    
    Since:
    
    2.47
  - createMirrorVar
```
public Variable createMirrorVar(Object obj,
                                boolean isPrimitive)
                         throws InvalidObjectException
```
    Create a mirror object in the target virtual machine
    
    Parameters:
    
    obj - the object to create the mirror from
    
    isPrimitive - when true and the object is an encapsulation of a primitive value, then primitive mirror is created.
    
    Returns:
    
    variable containing the mirror value
    
    Throws:
    
    InvalidObjectException - when the mirror operation fails
    
    Since:
    
    2.47
  - getInstanceCounts
```
public long[] getInstanceCounts(List<JPDAClassType> classTypes)
                         throws UnsupportedOperationException
```
    Retrieves the number of instances of each class in the list. Use JPDADebugger.canGetInstanceInfo() to determine if this operation is supported.
    
    Returns:
    
    an array of long containing one instance counts for each respective element in the classTypes list.
    
    Throws:
    
    UnsupportedOperationException
  - getThreadsCollector
```
public ThreadsCollector getThreadsCollector()
```
    Get the collector of threads.
    
    Returns:
    
    The threads collector
    
    Since:
    
    2.16
  - getSession
```
public Session getSession()
```
    Get the session associated with this debugger.
    
    Since:
    
    3.19

Class JPDADebugger

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PROP_STATE

PROP_CURRENT_THREAD

PROP_CURRENT_CALL_STACK_FRAME

PROP_SUSPEND

PROP_THREAD_STARTED

PROP_THREAD_DIED

PROP_THREAD_GROUP_ADDED

PROP_CLASSES_FIXED

PROP_BREAKPOINTS_ACTIVE

SUSPEND_ALL

SUSPEND_EVENT_THREAD

STATE_STARTING

STATE_RUNNING

STATE_STOPPED

STATE_DISCONNECTED

ENGINE_ID

SESSION_ID

Constructor Detail

JPDADebugger

Method Detail

launch

listen

startListening

startListeningAndGetEngines

attach

attach

getState

getSuspend

setSuspend

getCurrentThread

getCurrentCallStackFrame

evaluate

waitRunning

canFixClasses

canPopFrames

canBeModified

fixClasses

getSmartSteppingFilter

fireBreakpointEvent

getBreakpointsActive

setBreakpointsActive

addPropertyChangeListener

removePropertyChangeListener

addPropertyChangeListener

removePropertyChangeListener

createJPDAStep

canGetInstanceInfo

getAllClasses

getClassesByName

createMirrorVar

createMirrorVar

getInstanceCounts

getThreadsCollector

getSession