Debugging distributed applications
Distributed application development is a feature of JBuilder Enterprise.
JBuilder includes several debugger features that assist in debugging distributed applications. In particular, it includes support for cross-process debugging and remote debugging.
This support is additional to the basic debugging features in JBuilder. If you are new to JBuilder, refer to "Debugging Java programs" in the online Help book Building Applications with JBuilder for information on the JBuilder debugger environment.
About remote debugging
Remote debugging is the process of debugging code running on one computer from another computer. This feature is ideal, for example, in situations where an application encounters a problem on one networked computer that is not duplicated on other computers.
For the purposes of this discussion, the "client computer" is the computer running JBuilder. This is the computer you debug from. The "remote computer" runs the application you want to debug.
There are two ways to debug remotely. You can either:
Note: Both the client and remote computer need to have JDK 1.3 or JDK 1.2.2 installed, or any JDK that supports the JPDA debugging API. The The JDK versions on the two computers do not need to match. Note that when you install JBuilder, JDK 1.3 is automatically installed.
You can also debug local code that is running in a separate process on the same computer JBuilder is installed on. To do this, start the process in debug mode and attach JBuilder to it. For more information, see "Debugging local code running in a separate process."
Additionally, you can set cross-process breakpoints, ideal for debugging client/server applications. For more information, see "Debugging with cross-process breakpoints."
You can also set remote debugging options for an individual configuration, using the Runtime Configurations dialog box. For more information, see "Setting runtime configurations" and
"Creating debugger configurations."
Launching and debugging a program on a remote computer
This section explains how to launch a program on a remote computer and debug it using JBuilder on the client computer. Briefly, you:
- Install the Debug Server on the remote computer and run it.
- Either compile the application on the remote computer or copy the application's .class files to the remote computer.
- Use JBuilder on the client computer to launch and debug the application on the remote computer.
Important: The source files for the application you are debugging must be available on the client computer. The compiled .class files must be available on the remote computer. They must match. Otherwise, unpredictable results may occur, including incorrect errors being generated or the debugger stopping on the wrong source code line. Every time you modify the source code, be sure to update .class files on the remote computer.
First, install and run the Debug Server on the remote computer. If JBuilder is already installed on the remote computer, you can start with Step 4 below.
-
Copy the
debugserver.jar
file (located in the /remote
directory of your JBuilder installation) to the remote computer. Note the directory location you copy it to as it will be needed in later steps.
- Copy the Debug Server shell script,
DebugServer
(Unix), or batch file, DebugServer.bat
(Windows),
to the same directory on the remote computer.
- Make sure the JDK 1.3 or JDK 1.2.2 is installed on the remote computer. For JDK 1.3 download and installation instructions, select:
Java 2 SDK, Standard Edition, V 1.3 from the drop-down list on
http://java.sun.com/products/OV_jdkProduct.html.
- Go to the directory on the remote computer where the Debug Server files are installed. Call
DebugServer
to
customize environment variables for the remote Debug Server and run it.
For Unix systems, use the following command:
./DebugServer [debugserver.jar_dir] [jdk_home_dir]
[-port=<portnumber>] [-timeout=<milliseconds>]
For Windows systems, use:
DebugServer [debugserver.jar_dir] [jdk_home_dir]
[-port=<portnumber>] [-timeout=<milliseconds>]
where:
- debugserver.jar_dir
- The directory on the remote computer where the Debug Server JAR file is located. On Windows systems, the drive letter is required.
- jdk_home_dir
- The home directory on the remote computer of the JDK installation. On Windows systems, the drive letter is required.
- -port
- Optional parameter that launches the debug server on a port different from the default, 18699. Change this value only if the default value is in use. Valid values are from 1025 to 65535. This value must match the value entered into the Port Number field on the Debug page in the Project Properties dialog box (on the client computer). See Step 6 below.
- -timeout
- Optional parameter that sets the number of milliseconds to try to connect the remote computer to the client computer. When this number is reached, the process will stop. The default setting is 60,000 milliseconds.
An example of this command in a Windows environment is:
DebugServer d:\remote d:\jdk1.3 -port=1234 -timeout=20000
When the Debug Server is loaded, JBuilder remote debugging functionality in launch mode is enabled. Once the Debug Server is running, you need to compile the application and copy the .class files to the remote computer. (You can also compile the application remotely.) Then, you use JBuilder, running on the client computer, to launch and debug the program on the remote computer.
- Compile the application. You can compile the application using JBuilder on the client computer, then copy or use File Transfer Protocol (FTP) to put .class files on the remote computer. You can also compile the application directly on the remote computer using the -g option when calling the
javac
compiler.
- Open JBuilder on the client computer.
- Open the project for the application to debug.
- Open the Project Properties dialog (Project|Project Properties) and choose the Debug tab.
- Select the Enable Remote Debugging checkbox. Choose the Launch option.
- Enter the following options:
- Host Name
- The name of the remote computer. localhost is the default. You may need to check the network settings on the remote computer to find the host name.
- Port Number
- The port number for the remote computer you are communicating with. Use the default port number, 18699. Change this value only if the default value is in use. Valid values are from 1024 to 65535. This value must match the -port parameter for the Debug Server on the remote computer. See Step 4 in the previous section.
- Remote Classpath
- The classpath where the compiled .class files for the application that you are remotely debugging can be found. This field works like other classpath fields - if the classes are in a package, specify the root of the package and not the directory containing the classes. On Windows systems, specify the drive letter. This remote classpath only applies to this debugging session.
- Remote Working Directory
- The working directory on the remote computer. On Windows systems, specify the drive letter. This remote working directory only applies to this debugging session.
Warning: The working directory is not supported in JDK 1.2.2. If your remote computer is running JDK 1.2.2 and you enter a remote working directory, the debugger will display a warning in the Console output, input, and errors view.
- Transport
- The transport type: Either dt_shmem (shared memory transport - not available on Unix systems) or dt_socket (socket transport). For more information on transport methods, see "JPDA: Connection and Invocation Details - Transports"
- Click OK.
- Start the debugging session by choosing one of the following options:
Command |
Shortcut |
Description |
Run|Debug Project |
Shift + F9
| Starts the program in the debugger, either running the program to completion, or suspending execution at the first line of code where user input is required, or at a breakpoint. |
Run|Step Over |
F8 |
Suspends execution at the first line of executable code. |
Run|Step Into |
F7 |
Suspends execution at the first line of executable code. |
Once you start the debugger, the application you want to debug (based on the Remote Classpath setting) is launched on the remote computer. The debugger is displayed in JBuilder running on the client computer; however, you are debugging the .class files running on the remote computer.
Note: If the application is already running on the remote computer, the Debug Server will launch a new instance of it. (To debug an already-running application, see "Debugging a program already running on the remote computer.")
- To terminate the application on the remote computer, stop the process in JBuilder. To close the Debug Server on the remote computer, choose the Debug Server's File|Exit command.
Debugging a program already running on the remote computer
This section explains how to attach to a program that is already running on a remote computer and debug it using JBuilder on the client computer. Briefly, you need to:
- Run the application with VM debug options on the remote computer.
- Use JBuilder on the client computer to attach to and debug the running application.
Important: The source files for the application you are debugging must be available on the client computer. The compiled .class files must be available on the remote computer. They must match. Otherwise, unpredictable results may occur, including incorrect errors being generated or the debugger stopping on the wrong source code line. Every time you modify the source code, be sure to update the .class files on the remote computer.
For a tutorial that walks through attaching to an already running program, see the "Remote debugging tutorial."
To start a program on the remote computer and attach to it:
- Compile the application on the remote computer. You can also compile the application in JBuilder on the client computer, then copy or use File Transfer Protocol (FTP) to put .class files on the remote computer.
- Run the application on the remote computer, using the following VM options.
- If you have JBuilder on the remote computer, you can run your program from within JBuilder. Open the project, then open the Run page of the Project Properties dialog box. Enter the following parameters into the VM Parameters field:
-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,
server=y,address=5000,suspend=y
The address
and suspend
are optional. See below for more information.
- If you don't have JBuilder on the remote computer, you need to run your program from the command line:
- Add the following VM options to the Java command line:
-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,
server=y,address=5000,suspend=y
The address and suspend parameters are optional. They follow the server parameter and are separated by a comma. No spaces are allowed between the parameters.
- The address parameter, based on the selected transport, holds the port number/address through which the debugger communicates with the remote computer. This parameter makes configuration easier - you don't need to continually modify the Address field on the Debug page of the Project Properties dialog box. If the Transport Type is set to dt_socket, the Address parameter holds the port number. If it's set to dt_shmem, this parameter is set to the unique address name.
- The suspend parameter indicates whether the program is suspended immediately when it is started. This setting can be turned off by specifying suspend=n. (If suspend=n and no breakpoints are set, the program will run to completion without stopping when you start it.)
Note: To run the application, use java.exe
from the /bin
directory
of your JDK installation, not the java.exe
in the /jre/bin
directory. This allows the Java VM to load the debugger file (libjdwp.so
in Unix; jdwp.dll
in Windows), which is necessary for debugging.
- Open JBuilder on the client computer.
- Open the project for the application already running on the remote computer.
- Open the Project Properties dialog (Project|Project Properties) and choose the Debug tab.
- Select the Enable Remote Debugging checkbox. Choose the Attach option, located below the checkbox.
- Enter the following options:
- Host Name
- The name of the remote computer. localhost is the default. You may need to check the network settings on the remote computer to find the host name.
- Transport
- The transport method options:
- Type: Either dt_socket (socket transport) or dt_shmem (shared memory transport - not available on Unix systems). For more information on transport methods, see "JPDA: Connection and Invocation Details - Transports."
- Address:
- If the Transport Type is set to dt_socket, this parameter holds the port number for the remote computer you are communicating with. Use the default port number, 5000. Change this value only if the default value is in use. This value must match the address parameter to the Java VM that starts the program on the remote computer. See Step 2 earlier in this section.
- If dt_shmem is selected as the Transport Type, set the Address parameter to the unique name for the remote computer you are communicating with. The default is javadebug.
- Click OK to close the dialog box.
- Choose either Run|Step Over or Run|Step Into to start the debugger.
- If the suspend parameter for the VM on the remote computer is set to y (see Step 2 earlier in this section), click the Resume Program button
on the debugger toolbar to proceed with debugging.
- To terminate the application, close the application on the remote computer.
- To detach from the remote computer, stop the process in JBuilder.
Note: To launch and debug an application on the remote computer, see the section called "Debugging and launching a program on a remote computer.")
Debugging local code running in a separate process
To debug local code that is running in a separate process on the same computer JBuilder is installed on, follow the instructions above, starting with Step 2. Use the following settings for the Attach options on the Debug page of the Project Properties dialog box:
- Host Name
- Set to the default, localhost.
- Transport Type
- Set to dt_socket (socket transport) or dt_shmem (shared memory transport - not available on Unix systems).
- Transport Address:
- If the Transport Type is dt_socket, set to 5000. If the Transport Type is dt_shmem, set to javadebug.
Debugging with cross-process breakpoints
A cross-process breakpoint causes the debugger to stop when you step into any method or the specified method in the specified class in a separate process. This allows you to step into a server process from a client process, rather than having to set breakpoints on the the client side and on the server side. You will usually set a line breakpoint on the client side and a cross-process breakpoint on the server side. For a tutorial that walks through cross-process stepping, see the "Remote debugging tutorial."
To activate a cross-process breakpoint set on a server process,
- Start the server process on the remote computer in debug mode - see Step 2 in the section called "Debugging a program already running on a remote computer."
- On the client computer, from within JBuilder, attach to the server already running on the remote computer. See Steps 4 - 8 in the section called "Debugging a program already running on a remote computer."
- Set a line breakpoint in the client code and start debugging the client. At the breakpoint, step into the server code. Do not use Step Over - stepping over will not stop at the cross-process breakpoint.
To set a cross-process breakpoint, use the Add Cross-Process Breakpoint dialog box. To open the Add Cross-Process Breakpoint dialog box, do one of the following:
- Before or during a debugging session, select Run|Add Breakpoint and choose Add Cross-Process Breakpoint.
- When you're in a debugging session, click the
down-facing arrow to the right of the Add Breakpoint button
on the debugger toolbar and choose Add Cross-Process Breakpoint.
- When you're in a debugging session, right-click an empty area of the Data and code breakpoints view and choose Add Cross-Process Breakpoint.
The Add Cross-Process Breakpoint dialog box is displayed.
To set a cross-process breakpoint,
- In the Class Name field, enter the name of the server-side class that contains the method you want the debugger to stop on. Use the Browse button to browse to the class.
- In the Method field, enter the name of the method you want the debugger to stop on. Use the Browse button to display the Select Method dialog box where you can browse through the methods available in the selected class. The method name is not required. If you do not specify the method name, the debugger stops at all method calls in the specfied class.
Note: You cannot select a method if the selected class contains syntax or compiler errors.
- In the Method Arguments field, enter a comma-delimited list of method arguments. This causes the debugger to stop when the method name and argument list match. This is useful for overloaded methods.
- If you don't specify any arguments, the debugger stops at all methods with the specified method name.
- If you choose a method name from the Select Method dialog box, the Methods Argument field is automatically filled in.
- Choose the Actions for the debugger. The debugger can stop execution at the breakpoint, display a message, or evaluate an expression. For more information, see "Setting breakpoint actions" in the "Debugging Java programs" chapter in Building Applications with JBuilder.
- In the Condition field, set the condition, if one exists, for this breakpoint. For more information, see "Creating conditional breakpoints" in the "Debugging Java programs" chapter in Building Applications with JBuilder.
- In the Pass Count field, set the number of times this breakpoint must be passed in order for the breakpoint to be activated. For more information, see "Using pass count breakpoints" in the "Debugging Java programs" chapter in Building Applications with JBuilder.
- Click OK to close the dialog box.
- Set a line breakpoint in the client on the method that calls the cross-process breakpoint.
- When you stop at the line breakpoint, click the Step Into button
on the debugger toolbar to step into the server-side breakpointed method. (If you use Step Over, the debugger will not stop.)