3.3 Using a Debugger with a Java Driver

You cannot currently debug a Java driver on NetWare or Unix systems. For the Windows platform (NT or 2000), the following debug interfaces and debuggers are available:

3.3.1 Agent Debugger

To use a debug agent, you must install the debug agent and then enable it. Complete the following steps.

  1. Obtain a copy of JDK 1.3.0.

  2. Make a backup copy of the DirXML jre directory (default location—C:\novell\nds\jre).

  3. Delete the DirXML jre directory.

  4. Copy the jre directory from the JDK into the DirXML jre directory.

  5. Copy the contents of the jdk/lib directory (includes tools.jar) into the DirXML jre/lib directory.

  6. Add the DirXML-JavaDebugPort attribute to the DirXML-DriverSet object.

    1. From ConsoleOne, right click on the DirXML-DriverSet object and select the Properties option.

    2. Select the Other tab.

    3. Press the Add button and select the DirXML-JavaDebugPort attribute.

    4. Set the value to some TCP port not in use on your machine (8080 usually works).

    5. Press the OK button.

  7. Restart eDirectory.

  8. Before the first driver starts, a small dialog will pop up with the debugger password. At this point, you can choose to attach a debugger to the JVM and press OK.

Sometimes you can attach a debugger after you have dismissed the dialog that pauses for you to attach to the JVM; sometimes you can’t.

3.3.2 Java Platform Debugger Architecture (JPDA)

To use a JPDA type debugger, you must set options for the JVM using a DirXML environment variable: DHOST_JVM_OPTIONS. Java 2 options are set using this environment variable and passed to the JVM by DirXML.

For more information on the environment variables, see JVM Variables. For information on the JVM options and JPDA see Java Platform Debugger Architecture.

3.3.3 Visual Cafe 3.0 Debugger

The Visual Cafe debugger is an agent-type debugger.To set up a debug session, complete the following steps.

  1. Create a project for debugging.

  2. Set the main class to “sun.tools.agent.EmptyApp”.

  3. Set your source directories and input class files directories appropriately for your environment.

  4. Attach the debugger using Projects | Debug in Waiting VM. Use “localhost” as the host name and the password supplied by the dialog box.

If you stop the debugging session in VisualCafe, it shuts down the JVM inside of eDirectory and you will have to restart eDirectory to get it back up again.

The VisualCafe debugger has a lot of quirks. Be aware of the following:

  • Sometimes it has trouble attaching to the JVM.
  • Sometimes it gets internal java exceptions, after which no data will display until you shut down VisualCafe and restart it.
  • Often it will still stop at breakpoints that have been removed or disabled.

3.3.4 JDB Debugger

To attach the jdb debugger, complete the following steps.

  1. Enter the following command: 

      jdb -host localhost -password <password>

  2. Set the path to your source directories using the “use” command.

If you stop the debugging session in jdb, it shuts down the JVM inside of eDirectory and you will have to restart eDirectory to get it back up again.

You can create a file called startup.jdb in the working directory that can contain commands that will be executed when jdb starts. This is a good place to put the “use” command to set up the source directories.

The password is really just an obfuscated version of the port number. Since you are picking a static port number, you can reuse any of the passwords that are generated. If you see one that is easy to memorize, remember and use it instead of using a new password every time.

3.3.5 JVM Variables

A number of environment variables may be set to control the JVM under Windows NT and Windows 2000:

Table 3-1 JVM environment variables for Windows

Variable

Description

DHOST_JVM_USE_VFPRINTF

If set to a value other than “0”, causes the installation of a vfprintf hook function that will write to a log file named “jvm_vfprintf.log” in the temp directory. This will also enable verbose class and JNI messages.

DHOST_JVM_VERBOSE_GC

If set to a value other than “0”, enables verbose garbage collector messages. This is only useful in conjunction with JVM_USE_VFPRINTF.

DHOST_JVM_INITIAL_HEAP

Specifies the value, in decimal number of bytes, of the initial JVM heap size.

DHOST_JVM_MAX_HEAP

Specifies the value, in decimal number of bytes, of maximum JVM heap size.

DHOST_JVM_OPTIONS

Specifies the arguments for the JVM 1.2. For example:

  • -Xnoagent -Xdebug -Xrunjdwp: transport=dt_socket,server=y, address=8000

Each option string is separated by whitespace. If an option string contains whitespace, it must be enclosed in double quotes.

DHOST_JVM_DESTROY

If set to a value other than “0”, causes the JVM loader thread to call DestroyJavaVM() when DirXML is unloaded. This is useful to cause the Java 2 hprof profiler to dump its data to a file.

NOTE:The JVM is unusable after this call and cannot be reloaded. DHOST must be shutdown and restarted to use the JVM again. This means DirXML cannot be restarted until DHOST has restarted.

The following options can be used on NetWare:

Table 3-2 JVM environment variables for NetWare

Option

Description

DIRXML_JVM_INITIAL_HEAP

Specifies the value, in bytes, of the initial java heap size. This option works with JVM 1.1.x and 1.2.x. Examples:

  • DIRXML_JVM_INITIAL_HEAP=4M
  • DIRXML_JVM_INITIAL_HEAP=4096K

DIRXML_JVM_MAX_HEAP

Specifies the value, in decimal bytes, of the maximum java heap size. This option works with JVM 1.1.x and 1.2.x. Examples:

  • DIRXML_JVM_MAX_HEAP=36M
  • DIRXML_JVM_MAX_HEAP=36864K

DIRXML_JVM_VIRTUAL_HEAP

Specifies the value, in decimal bytes, of the virtual java heap size. This option works with JVM 1.1.x and 1.2.x. Examples:

  • DIRXML_JVM_VIRTUAL_HEAP=36M
  • DIRXML_JVM_VIRTUAL_HEAP=36864K

DIRXML_JVM_OPTIONS

Specifies the arguments for the JVM 1.2. For example:

  • -Xnoagent -Xdebug -Xdebugport8080

Each option string is separated by whitespace. If an option string contains whitespace, it must be enclosed in double quotes.

This option only works with JVM 1.2.x.

DirXML_JVM_C_STACK_SIZE

Specifies in decimal bytes the Java C process stack size. Examples:

  • DIRXML_JVM_C_STACK_SIZE=128K
  • DIRXML_JVM_C_STACK_SIZE=256K

Default: 128K