Configuration Before Running the Samples

To run a sample Java Card application, you will:

  • Import the projects
  • Build the projects
  • Start the Java Card Development Kit Simulator
  • Run the sample-specific client Java application, which loads the applets(s), sends the necessary APDUs, and performs cleanup

Some instructions demonstrate different ways to complete a task to help you learn more about the Plug-in. Most options in the Plug-in dialogs correspond to command-line options for the Development Kit Tools (converter and verifier), as described in Building and Running the Samples from the Command Line. The Plug-in executes these tools with the options you select.

Here are a few notes on running the sample Java Card applications.

Java Card Development Kit Simulator Settings

When you start Eclipse, the Plug-in automatically creates or re-creates the Java Card Development Kit Simulator Entry: Java_Card_Simulator_1. If this entry is not created, refer to the instructions in Create a New Simulator Settings Profile.

Java Card View

The sample instructions refer to the Java Card view. If you don't see the Java Card view, go to the Window menu, select Reset Perspective..., and click Yes to confirm the reset.

Importing and Building Projects

Using the File menu, select Import > General > Projects from Folder or Archive to import a Java Card project. Make sure that you select the directory that contains the Java Card source files. For the samples provided, this directory is the applet folder.

After you have imported a project, the build starts (if Build Automatically under the Project menu is selected) and generates the following artifacts for each Java Package within the deliverables subdirectory, which are created by the Converter Tool.

  • deliverables - cap, jca, and exp files
  • cap file - Standard file format containing a binary representation of a shared library (library CAP file) or an application with its libraries that might be exported or not (applet CAP file). A CAP file represents a module, which is a unit of code, made of one or more Java packages, with dependencies and list of exported packages and an assigned name (AID) for lifecycle management. Its structure is made of multiple CAP components deployed within a JAR file
  • jca file - A JCA (Java Card platform Assembly) file is a textual representation of a converted package that you can use to aid testing and debug. You can use a JCA file as an input to the capgen tool to create a CAP file
  • exp file - A Java Card technology-based export file ("Java Card export file") contains the public interface information for an entire packages of classes. This means that an export file only contains information about the public API of a package and does not include information used to link classes within a package

After having built the Java Card applets(s), the corresponding client project must be imported and built. To do so, use the File menu, select Import > General > Projects from Folder or Archive to import the corresponding Java client project. Make sure that you select the directory that has Java source files for the client project. This directory is the client folder.

Running Java_Card_Simulator_1

Start the Simulator by right-clicking on Java_Card_Simulator_1 in Java Card View and selecting Start. The console opens with the output from the Simulator and a prompt: CMD>. Here you can enter an APDU command, which is sent to the Java Card Development Kit Simulator (Java_Card_Simulator_1), and the response will be displayed on the console.

One simple way to test if the console is running is to type the help command at the prompt:
help

You should see a screen with all of the available options.

Java_Card_Simulator_1 Settings

Change settings for the Simulator by double-clicking on Java_Card_Simulator_1 in the Java Card View to open the Properties dialog for Java_Card_Simulator_1. From this dialog, you can also change the debugger and other settings.

If you change these settings, ensure they match the expected sample Simulator settings before running the next sample. For the required Simulator settings, refer to the instructions in Editing a Simulator Settings Profile.

Classpath Variable Settings

All samples come with a pre-defined classpath file, including all of the necessary external libraries. These classpath files are part of the according Eclipse projects and use an internally defined classpath variable to automatically match the installation folder.

To create or update a classpath variable in Eclipse, select Window > Preferences then expand Java > Build Path > Classpath variables and check for the JC_HOME_SIMULATOR variable. If it does not exist, create it and set its value to the root directory of the Java Card Development Kit Simulator bundle.

External JREs vs. Eclipse Internal JREs

We recommend installing either Oracle Java SE 17 or OpenJDK 17, as these versions have been tested. After installation, select Window > Preferences, expand Java > Installed JREs, click Add and select the installed JDK. Ensure that the corresponding check box for the selected JDK is checked to set it as the default JRE. Once a default JRE has been set, the line will change to bold with "(default)" added.

To verify the JRE that will be used, select Window > Preferences, expand Java > Installed JREs > Execution Environment, and check the external version of your choice.