# Module jdk.jdi

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.

Module Graph:
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
  A method of connection between a debugger and a target VM.
  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.