-Xrunjdwp
The -Xrunjdwp
option enables the Java™ Debug Wire Protocol (JDWP) agent in the VM. The JDWP agent provides a connection point for the debugger to debug a Java application in that VM.
Note: You can enable the JDWP support on Checkpoint/Restore In Userspace (CRIU) restore by specifying the following command-line options pre-checkpoint:
-Xrunjdwp
-agentlib:jdwp
-agentpath:/path/to/libjdwp.so
Parameters
These parameters are applicable for both the -Xrunjdwp
and -agentlib:jdwp
options.
address
-Xrunjdwp:address=<value>
- Specifies the transport address for the connection. If
server=y
andaddress
is specified, the VM listens for a connection at this address. Ifserver=y
andaddress
is not specified, the VM chooses atransport
address to listen for a debugger application. Ifserver=n
, theaddress
parameter is mandatory. The VM attempts to attach to the debugger application at the specified address.
help
-Xrunjdwp:help
- Prints a brief help message that describes all the available options for the
-Xrunjdwp
option and exits the VM.
launch
-Xrunjdwp:launch=<path>
- Starts the debugger process from the specified path. The values of the
address
andtransport
parameters, if available, are also added to the specified path. These parameters help the debugger to connect to the target VM. This option is used withonthrow
,onuncaught
or both the parameters to provide Just-In-Time debugging in which a debugger process is started when a particular event occurs in this VM.
onthrow
-Xrunjdwp:onthrow=<exception>
- Delays the debugging process until the specified exception is thrown in this VM. The JDWP agent attaches to the VM and starts debugging when the exception is thrown.
onuncaught
-Xrunjdwp:onuncaught=[y|n]
- If
onuncaught=y
, delays the debugging process until an uncaught exception is thrown in this VM.
server
-Xrunjdwp:server=[y|n]
- If
server=n
, the VM does not listen to any incoming debugger connection and it attempts to attach to the local debugger application at the specifiedaddress
. In this case, specifying theaddress
parameter is mandatory. Ifserver=y
, the target VM acts as a server listening for an incoming debugger connection through the JDWP agent. Ifserver=y
andaddress
is specified, the VM listens for a debugger connection at this address. Ifserver=y
andaddress
is not specified, the VM selects atransport
address at which to listen for a debugger application.
suspend
-Xrunjdwp:suspend=[y|n]
- If
suspend=y
, the VM suspends running of the target Java application until the debugger is attached successfully and is ready for debugging. Ifsuspend=n
, the VM does not suspend running of the target Java application while the debug connection is established. The VM continues running the application as normal. The debugger can attach to the running application at any time. - When a debug session is restored from a checkpoint, the VM suspends the running of the Java application that was being debugged even if
suspend=n
. The VM waits for the debugger to send aResume
request before it restarts the Java application to continue the debug session. When the debug session is complete, the debugger disconnects from the JDWP agent, and the agent resumes normal running of the Java application.
suspendOnRestore
(Linux® x86, Linux on POWER® (Little Endian), Linux on AArch64, and Linux on IBM Z® only)
suspendOnRestore
is an OpenJ9 specific parameter and is similar to the suspend
parameter. But unlike suspend
, this parameter only affects a VM on restore.
-Xrunjdwp:suspendOnRestore=[y|n]
- If
suspendOnRestore=y
, the VM suspends running of the target Java application until the debugger is attached successfully and is ready for debugging on CRIU restore. IfsuspendOnRestore=n
, the VM does not suspend the running of the target Java application while the debug connection is established on restore. - If
suspend=y
is set pre-checkpoint, the VM suspends the application pre-checkpoint, and on restore. The application remains suspended when you restore the VM even if you specifysuspend=n
pre-checkpoint. Therefore, to ensure that the application is not suspended on restore, you can use thesuspendOnRestore=n
setting.
timeout
-Xrunjdwp:timeout=<milliseconds>
- If
server=y
, thetimeout
parameter specifies the time the VM waits for the debugger to attach before the VM ends the connection. Ifserver=n
, the parameter specifies the time until the VM tries attaching to the debugger before it ends the connection.
transport
-Xrunjdwp:transport=<value>
- Specifies the name of the transport to use in connecting to the debugger application. Transport refers to a method of communication between a debugger and the VM that is being debugged.
<value>
can bedt_socket
ordt_shmem
.dt_socket
or the socket transport relies on TCP sockets that listen on a port for debugger connections, and uses that connection to transfer the debug session packets. This transport mechanism enables debugging remote target VM application.dt_shmem
or the shared memory transport uses shared memory to send and receive packets. This transport mechanism enables debugging only locally running applications.
For more information, see -agentlib:jdwp and -Xrunjdwp sub-options.