# Module jdk.jdi

Defines the Java Debug Interface.

The Java™ Debug Interface (JDI) is a high level Java API providing information useful for debuggers and similar systems needing access to the running state of a (usually remote) virtual machine.

JDI provides introspective access to a running virtual machine's state, Class, Array, Interface, and primitive types, and instances of those types.

JDI also provides explicit control over a virtual machine's execution. The ability to suspend and resume threads, and to set breakpoints, watchpoints, etc. Notification of exceptions, class loading, thread creation, etc. The ability to inspect a suspended thread's state, local variables, stack backtrace, etc.

JDI is the highest-layer of the Java Platform Debugger Architecture (JPDA).

This module includes a simple command-line debugger, jdb.

### Global Exceptions

This section documents exceptions which apply to the entire API and are thus not documented on individual methods.

> `VMMismatchException`

> Any method on a `Mirror` that takes a `Mirror` as an parameter directly or indirectly (e.g., as a element in a `List`) will throw `VMMismatchException` if the mirrors are from different virtual machines.

> `NullPointerException`

> Any method which takes a `Object` as an parameter will throw `NullPointerException` if null is passed directly or indirectly -- unless null is explicitly mentioned as a valid parameter.

NOTE: The exceptions below may be thrown whenever the specified conditions are met but a guarantee that they are thrown only exists when a valid result cannot be returned.

> `VMDisconnectedException`

> Any method on `ObjectReference`, `ReferenceType`, `EventRequest`, `StackFrame`, or `VirtualMachine` or which takes one of these directly or indirectly as an parameter may throw `VMDisconnectedException` if the target VM is disconnected and the `VMDisconnectEvent` has been or is available to be read from the `EventQueue`.

> `VMOutOfMemoryException`

> Any method on `ObjectReference`, `ReferenceType`, `EventRequest`, `StackFrame`, or `VirtualMachine` or which takes one of these directly or indirectly as an parameter may throw `VMOutOfMemoryException` if the target VM has run out of memory.

> `ObjectCollectedException`

> Any method on `ObjectReference` or which directly or indirectly takes `ObjectReference` as parameter may throw `ObjectCollectedException` if the mirrored object has been garbage collected.

> Any method on `ReferenceType` or which directly or indirectly takes `ReferenceType` as parameter may throw `ObjectCollectedException` if the mirrored type has been unloaded.

Tool Guides:
  jdb

Since:
  9
See Also:
  Java Platform Debugger Architecture (JPDA)

- - ## Packages

    Exports
    Package | Description
    --- | ---
    com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
    com.sun.jdi.connect | This package defines connections between the virtual machine using the JDI and the target virtual machine.
    com.sun.jdi.connect.spi | This package comprises the interfaces and classes used to develop new `TransportService` implementations.
    com.sun.jdi.event | This package defines JDI events and event processing.
    com.sun.jdi.request | This package is used to request that a JDI event be sent under specified conditions.

  - ## Services

    Provides
    Type | Description
    --- | ---
    Connector |

    Uses
    Type | Description
    --- | ---
    Connector | A method of connection between a debugger and a target VM.
    TransportService | A transport service for connections between a debugger and a target VM.