Debugging Java code remotely

You can debug Java code running under control of a Notes client JVM (Java Virtual Machine) with a debugger that supports the JPDA (Java Platform Debugger Architecture), such as Eclipse. See java.sun.com/products/jpda for information on the JPDA. See www.eclipse.org for information on Eclipse and the Eclipse debugger. You cannot debug Java code running on a Domino server.

Complete these steps to debug Java code:

  1. Enable Java debugging on a Notes client.
  2. Enable Java debugging in an agent, Web service, or script library.
  3. Connect a debugger to the JVM.
Note: Debugging Java agents is new with Release 7.
CAUTION: Java debugging is insecure and degrades performance. Disable Java debugging when it is not needed.

To enable Java debugging on a Notes client

The Notes client supports Java debugging in the following contexts. Each context has its own JVM. Only one user can debug at a time in each context.

  • Foreground -- Java code that runs in the Notes client interactively, for example, an agent triggered from the Actions menu.
  • Background -- Java code that runs in the Notes client under control of the task loader, for example, a locally scheduled agent.
  • Web preview -- Java code being previewed in a browser through Domino Designer, for example, an applet on a form.

Java code from a script library runs in the context of the calling code.

To enable and disable Java debugging on the Notes client:

  1. Choose Tools - Java Debugging Preferences. This brings up the "Java Debugging Preferences" dialog.
  2. To enable foreground debugging, select "Client Agents/Applets" and specify a port number to connect the Notes and debugger computers. Deselect to disable.
  3. To enable background debugging, select "Locally Scheduled Agents" and specify a port number to connect the Notes and debugger computers. Deselect to disable.
  4. To enable Web preview debugging, select "Http Preview" and specify a port number to connect the Notes and debugger computers. Deselect to disable.

Pick a port number that you think is free. This may require trial and error.

Java debugging is disabled by default.

If changes are made to the foreground or background preference, Notes must be restarted. If changes are made to the Web preview preference, the preview must be restarted.

To enable Java debugging in an agent, Web service, or script library

To enable Java debugging, go to the Basics tab of the Agent or Web Service properties box, or to the Script Library properties box, and check:

Compile Java code with debugging information

If you are compiling the Java to be debugged outside Domino Designer, compile it with the -g option.

After modifying an agent or Web service, export the source code to a file that is accessible to your debugger.

To connect a debugger to the JVM

The following instructions assume the Eclipse debugger. You have to interpolate for other debuggers.

  1. Start the Notes client containing the agent or Web service to be debugged with Java debugging enabled.
  2. Start the debugger.
  3. Create a Java project and switch to the Java perspective. For example: choose File - New - Project; select "Java" in the Project window; enter a name for the project; select "Finish"; switch to the Java perspective. Or open the project if it already exists.
  4. Import the source Java files. For example: right-click on the project folder in the left-hand pane; select "Import"; browse to and select the source files; import them.

    Source code that is not imported is not available to the debugger. You can see the execution thread and can access variables, but you cannot see the source code and set breakpoints.

  5. In Notes, start the agent or Web service to be debugged.
  6. In Eclipse, attach the debugger to the Notes JVM. For example, choose Run - Debug; enter a name for the debug configuration; select the "Connect" tab; select the project, enter the host name or address of the Notes computer, and enter the Java debug port number on the Notes client; select "Apply" (only necessary the first time or if you change the configuration); select "Debug." The host address is 127.0.0.1 if the Notes client and Eclipse are on the same machine.

After you attach the debugger, you will see the execution threads for the JVM. An agent's thread looks something like this:

Thread(AgentThread: JavaAgent)(Running)

You can suspend the agent's thread to gain control over it. At this point, the usual debugger features become available (setting breakpoints, stepping, continuing, viewing variable values, and so on).

The Java agent must run long enough for you to attach the debugger to the JVM. You might delay execution at the beginning of the procedure, for example, by inserting a loop with sleep statements.

If Notes and the debugger are on separate computers, and you get the error "Failed to connect to remote VM," the designated port is probably taken by another process. Try specifying another port number and restarting Notes.

Security considerations

Java debugging over a network is insecure. You should restart Notes or the Web preview without Java debugging enabled when you're not debugging.