Debugging a Java Card Applet in Eclipse Plug-in

From Eclipse, you can run the debug proxy to set breakpoints, get or set variable values, and debug a library using the Java Card Plug-in.

The following steps provide an overview of debugging an application using Eclipse.

1. Create (or import) your Java Card project. Make sure that debugging information is generated when the project is built.

   Note:

   The debugging information is generated only if you select the Enable generation of debugging information check box in the CAP file settings.
2. Create a new Java Card Project Debug configuration and select the Java Card tab. Perform the following steps:
   1. Specify commands to be executed when the Java Card Development Kit Simulator starts. The commands run in an order represented in the table.
   2. Add CAP files for the applet and imported libraries, which include the code that you want to debug. These not only include CAP files generated in the deliverables directory, but also the CAP files that you generated.

   Note:

   The CAP files generated by the current project will be added automatically.
3. Once the debug session starts:
   1. The Simulator is started in debug mode.
   2. The debug proxy starts and establishes a connection with the Simulator.
   3. The Eclipse debugger connects to the debug proxy.
   4. The command(s) starts execution.
   You can experiment with the debug perspective and look at the debug console for debug proxy output.
4. Set breakpoints and execute scripts.

   Note:

   Due to Eclipse's handling of the class unload events, unload commands cannot be used in the middle of a debugging session. All unload commands must be done at the end, with no breakpoints set.

Debug Configuration

Debug Configuration can be used to automate how commands are run before sending the commands to hit the breakpoints. You can specify a list of commands to be executed.

In the JC Debug Configuration, under Connect tab > Connection Properties -> Port the value must match the Proxy to IDE port from the Java Card Development Kit Simulator properties which, by default, are both 8000.

The Debug Configuration has an option to start the Simulator, inside Eclipse, for you. This option can be disabled to allow the Plug-in to use an already running Simulator in debug mode. The running Simulator must match the configuration made in the selected Simulator (ex. Java_Card_Simulator_1) for the current project (Port number, GP ISD AND SCP03 Keys Config file, Debug Port).

Note:

If the selected Java Card Development Kit Simulator for the current project has set a Platform IP Address other than localhost, this option is disabled.

Note:

The Debug Configuration also allows you to run a client application externally (option External Client). That is, if you select this option, after the debug starts you can use any client application for sending APDUs to the Simulator. From the Eclipse side, the commands will be disabled.

Debugging HelloWorld Sample from Eclipse

These steps explain how to debug the HelloWorld sample. The Java Card Plug-in for Eclipse must already be installed.

Start Eclipse. Java_Card_Simulator_1 must already be created.

1. Click the File menu, select Import >General > Projects from Folder or Archive, and select the applet directory from the HelloWorld project to import the HelloWorld Java Card project into your workspace. If the build doesn't start automatically, start it manually.
2. Make sure debugging information generation is enabled for the HelloWorld package:
   1. Right-click on the imported project and select Java Card and CAP Files Settings.
   2. Select the HelloWorld CAP file and click Edit.
   3. In the new wizard, click Next on the first page.
   4. In the second page, select the Enable generation of debugging information check box.
   5. Click Finish and Apply, and close the wizard.
3. Create a new debug configuration:
   1. Right-click on the HelloWorld project in the Package Explorer and select Debug As and Debug Configurations.
   2. In the Debug Configurations dialog, double-click Java Card Project Debug (in the list). This will create a new debug configuration named HelloWorld.
   3. Select the Java Card tab.
   4. Select the Start simulator in debug mode… and Start debug proxy… check boxes.
   5. The Scripts to be executed on simulator table must include the Connect command. Every script is required to start with the Connect command. If it is not included, add it manually using the Add command button.
   6. Click Add command. Browse to the HelloWorld project directory and select the Load command file. This script will install the applet without creating an applet instance.
   7. Click Debug.
   The debug configuration starts. First, the Java Card Developent Kit Simulator is started in debug mode, then the commands are executed, the debug proxy is started and, finally, the Eclipse debugger connects to the debug proxy.
4. The Confirm Perspective Switch dialog appears, asking if you want to open the Debug perspective. You may choose to open it, depending on your preference.
   The Debug console shows output from the debug proxy.
5. In the Package Explorer, locate HelloWorld.java and open it. Set two breakpoints: one in the install() method of the applet, the other in the beginning of the process() method.
   There are several ways to set a breakpoint in Eclipse. In the source code editor, position the cursor on the desired line and do one of the following:
   1. Double-click the left most space on the source code line (the line number will be to the right).
   2. Press Ctrl + Shift + B to toggle the breakpoint (the type of breakpoint will be selected automatically depending on the source code).
   3. Select a specific breakpoint to toggle from the Run menu.
6. Execute the two remaining scripts in the order that they appear in the Package Explorer in the Select Command dropdown from Java_Card_Simulator_1 Console (Install and Select command).

   After each script is run, execution will suspend on the corresponding breakpoint. Step* and resume debugger commands can be used to resume applet code execution.