C H A P T E R 11

Debugging Applications

This chapter describes the Debugger tool (debugproxy) for Java Card 3 platform application developers and how to use it as a separate tool with any Java technology-enabled IDE. Using the Debugger, developers can debug their applications in any Java technology-enabled IDE.

##

Debugger Architecture

The following diagram illustrates the debugger architecture for `cjcre`.

FIGURE 11-1 Debugger Architecture

The Java Debug Wire Protocol (JDWP) used by the IDE is heavy for a small VM such as that provided by `cjcre`. Consequently, `cjcre` uses KVM Debug Wire Protocol (KDWP) to provide a minimum set of debugging capabilities. The Debugger tool, `debugproxy`, translates and sends the translated JDWP commands from the IDE to `cjcre` in KDWP format. Responses from `cjcre` are converted into JDWP format by `debugproxy` before it sends them to the IDE.

The communication between `cjcre`, `debugproxy`, and the IDE happens through sockets. Socket-based communication enables developers to debug `cjcre` from remote hosts. For example, `cjcre` could run on machine1, `debugproxy` could run on machine2, and the IDE could run on machine3. Developers can also run `cjcre`, `debugproxy`, and the IDE on same host.

Ports used by IDE communication to and from `debugproxy`, and `debugproxy` communication to and from `cjcre`, are distinguished by the names “listen port” and “remote port” respectively.

##

Running the Debugger From the Command Line

Use the Debugger tool’s functionality by starting `debugproxy` (`debugproxy.bat`), then attaching it to a Java technology-enabled IDE, and then starting `cjcre` with the `-debug` option. The file `debugproxy.bat` is located in the directory JC_CONNECTED_HOME`\bin`. Various command line options are available to configure the Debugger and `cjcre`. See cjcre.exe Command Line Options for additional details on the `cjcre` commands.

The command line interface for the Debugger has the following syntax:

    debugger.bat subcommand [option]

The following is a list of the subcommands for the Debugger:

- `debug` - Debugs the specified file

- `copyright` - Displays detailed copyright notice

- `help` - Displays information about the Debugger command

### `debug` Subcommand

Use the `debug` subcommand to debug a file at a specified location.

TABLE 11-1 `debug` Subcommand Options
Option | Description
--- | ---
`-c` filelocation or `--classpath` filelocation | Specifies the path of the class files to be debugged.
`-`C command-options-file or `--`commandoptionsfile command-options-file | Optional. Specifies a file containing command line options.

### `copyright` Subcommand

The `copyright` subcommand displays the detailed copyright notice. There are no options associated with this subcommand.

### `help` Subcommand

The `help` subcommand displays information about the Debugger command. Options are used with the `help` subcommand to specify the information that is displayed about each subcommand. For example, to display detailed help about the `debug` subcommand, type:

    debugproxy.bat help debug

##

Debugging a Java Card 3 Platform Application

This section describes how to debug an application using the development kit command line tools.

### Compile the Source Code

To fully utilize the capabilities of the Debugger, the application’s class files must first be compiled with debug information. This is done by specifying the `-g` flag for `javac` when compiling the source files. These class files must be available to `debugproxy` so the line number information can be retrieved while stepping through the code. All source files must be compiled using the `-g` option to generate the debug information in the class files. If the `-g` option is not used, it is not possible to set breakpoints in the source code.

### Start the Debugger

The Debugger needs to know the location of class files being debugged. The `Debugger` can be run from the command line using the following syntax, for example:

    debugproxy.bat debug -c myapp.war

When starting `debugproxy`, you can include the `-c` (or `--classpath`) option in the command line to `s`pecify the path of the class files to be debugged. In this example, `myapp.war` is the location of the class files to be debugged.

### Attach the Debugger to the IDE

This procedure is performed from within the IDE and so the details depend on the IDE used. If your IDE requires the Debugger to be attached, refer to the documentation provided with the IDE.

### Run `cjcre.exe` With `-debug` Option

This `-debug` option of `cjcre` enables debugging functionality in `cjcre`. Without this option, debugging functionality is disabled in `cjcre`. See cjcre.exe Command Line Options for additional details on the `cjcre` commands.

### Set Break Points

Break points must be set in the application source code. The exact procedure depends on the IDE used. The following steps are typical for most IDEs. Refer to the documentation provided with your IDE for specific instructions.

1. Display the source code of the application in the IDE.

2. With the source code displayed in the IDE, open any file and set break points where required.

Break points can be set at any time, even before attaching the Debugger.

3. Step through the code by executing the application from within the IDE.

When a break point is hit, the IDE stops execution and highlights the current line. Depending on the IDE being used, there are various options available to developers for stepping over or stepping into the code.

Note - Various IDE windows are available to monitor items such as local variables and threads. Refer to the documentation provided by the IDE for additional information about the windows used in monitoring debugger and application execution.

``

Copyright © 2009 Sun Microsystems, Inc. All rights reserved.