Integrating with Your Software

Modifying JSwat

Integrating the features of JSwat with your software is easily done using the latest version of the debugger. JSwat is based on the NetBeans Platform, written as a set of modules, and licensed under the Common Development and Distribution License. The core module defines a set of services for the various key components of the debugger, which can be programmatically replaced at runtime with software of your own making. That is, you can override some or all of the base functionality in JSwat with your custom code, allowing you to better integrate JSwat with your system. To learn more, read the developer documentation in the docs/dev directory of the JSwat source tree. In particular, see the instructions for building the API documentation, then take a look at the NetBeans Platform documentation to learn about writing modules for JSwat on NetBeans.

If you need help getting started, or encounter problems during development, you can send email to the jswat-dev mailing list.

Launching JSwat

If you want to launch JSwat from your software and have it connect to a debuggee, set the sourcepath, or even set a breakpoint and run to a particular line of code, use the following "API".

Connecting to a Remote Debuggee

JSwat detects the following system properties during startup, which allow it to connect to a debuggee that has been started by an external program:

jswat.transport
Examples: dt_socket, dt_shmem
Specifies the JDI transport to use to connect to the debuggee.
jswat.address
Examples: localhost:5858, jpdaconn
Address at which to connect to the debuggee, using the transport specified above.
Launching a Local Debuggee

JSwat detects the following system properties during startup, which specify a class and classpath for which to launch a locally running debuggee:

jswat.launch
Example: org.pkg.Klass arg1 arg2 arg3...
Specifies the name of the "main" class that the debuggee JVM will invoke at startup. The arguments are optional and depend entirely on the implementation of the main class.
jswat.classpath
Example: /path1:/path2:/path3
Sets the classpath to be used to launch the debuggee. This is required when using the jswat.launch property.
jswat.jvmhome
Example: /usr/java
Optional: The path to the Java runtime. If this is not provided, JSwat will use the runtime on which the debugger is running.
jswat.jvmexec
Example: java.exe
Optional: The name of the Java runtime executable.
jswat.jvmopts
Example: -client
Optional: Arguments for the Java runtime. Do not include the classpath setting, as JSwat will set that automatically.
Additional Settings

The following settings are optional and used in both the remote connect and local launch scenarios.

jswat.sourcepath
Example: /path1:/path2:/path3
Sets the sourcepath for the current session, so JSwat can find the source code for the application being debugged.
jswat.runto
Example: org.pkg.Klass.main(java.lang.String[])
Creates a method breakpoint that will be deleted when hit, then resumes debuggee, and when breakpoint is hit the source code will be shown.

The sourcepath and runto values should be quoted and contain no spaces, otherwise the launcher will get confused. For example:

./bin/jswat -J-Djswat.transport=dt_socket -J-Djswat.address=5858 -J-Djswat.sourcepath="/java/jswat/core/test/integration/src" -J-Djswat.runto="PackRat.main(java.lang.String[])"