Installation
Description: This document describes how to use the development kit for the Java Card 3 Platform, Connected Edition, Version 3.0.2, to develop applet applications, web applications, servlets, and extended applets
Date: December 2009

C H A P T E R 2

Installation

This chapter describes the prerequisites you need to install on your system before you use the development kit, how to install the development kit and the NetBeans IDE, how to set system variables, and how to uninstall the development kit. This chapter also lists the files installed onto your system by the Connected Edition of the development kit. You can run both a Classic and Connected development kit simultaneously.

Binary and source code development kits are available for the Microsoft Windows XP SP2 operating system. Source code bundles allow you to change the development kit’s reference implementation, whereas the binary bundles allow you only to use the reference implementation.

Each development kit is provided in an executable JAR file bundle. See Chapter 1 for a description of this development kit bundle and a list of all the files installed by this development kit.

Note - The Java Card specifications are not included in the development kit bundle. The specifications must be downloaded separately.

##

Prerequisites to Installing the Development Kit

The following software must be installed before installing the development kit:

- Apache ANT - download and install Apache Ant version 1.6.5 or higher from `http://ant.apache.org`.

- Firefox browser - download the Firefox browser from `http://www.mozilla.com`.

- GCC compiler - download and install MinGW from `http://sourceforge.net/projects/mingw` and install it according to the instructions on the `http://www.mingw.org` web site.

- Java Development Kit - download the JDK software from `http://java.sun.com/javase/downloads` and install it according to the instructions on the web site.

- NetBeans IDE (optional IDE, required to run samples) - download the NetBeans IDE version 6.8 from `http://www.netbeans.org/downloads` and install it according to the instructions on the web site.

##

Install and Setup the Development Kit

This section describes how to install and set up the development kit.

### Installing the Development Kit

1. Verify that the additional software required by the development kit is installed on the development system.

See Prerequisites to Installing the Development Kit for the download location and installation instructions of the required additional software.

2. Download an appropriate development kit JAR file to a directory of your choice.

3. Launch the development kit installer.

The development kit can be launched automatically when you download the JAR file or by using the Windows file manager tool to navigate to the directory containing the development kit JAR file and double clicking the file name or icon.

The development kit can also be launched by opening a Command Prompt window, navigating to the directory containing the development kit JAR file, and executing the following command from the command line:

`java` `-jar` Bundle-Filename

In the command, Bundle-Filename is the name of the downloaded development kit JAR file.

The installation wizard displays the following screen.

4. Complete each action requested by the installer.

By default, the development kit for the Connected Edition is installed in:

`C:\JCDK3.0.2_ConnectedEdition`

If you specify a different installation directory, the names of the installation directory and its parent must not contain a space.

For example, the installation directory cannot be located in `C:\program files` because of the space in the `program files` directory name.

Note - The installation directory (either the default directory or the alternate installation directory you specify) is referred to as JC_CONNECTED_HOME.

5. Click the Finish button to complete installation.

The bundle installs files and directories containing the binary files and source code described in Directories and Files Installed From All Bundles. The files and directories are installed under the root installation directory, either `C:\JCDK3.0.2_ConnectedEdition` or the directory you specified during installation. The root installation directory is referred to as JC_CONNECTED_HOME in this document.

### Setting Up the System Variables

1. Set the `JAVA_HOME` system variable to the JDK root directory.

Before running the development kit, you must set the `JAVA_HOME` environment variable permanently in the Windows Control Panel or temporarily from the command line:

- To permanently set `JAVA_HOME`, go to Windows Control Panel > System > Advanced > Environment Variables dialog and either create or edit a System variable named `JAVA_HOME` with the literal value of the JDK root directory on your system. For example, in the System variables box enter the following:

Variable Value `JAVA_HOME` `C:\JAVA\jdk1.6.0_10`

- To temporarily set `JAVA_HOME`, enter the following command in a Command Prompt window:

    set JAVA_HOME=C:\java_home_path;

For example, if the Java platform software is stored in the `c:\jdk6` directory, enter:

    set JAVA_HOME=C:\jdk6;

Note - If using the Category view, choose Windows Control Panel > Performance and Maintenance > System > Advanced to open the Environment Variables panel.

2. Set the `ANT_HOME` system variable to the Ant root directory.

Before running the development kit, you must set the `ANT_HOME` environment variable permanently in the Windows Control Panel or temporarily from the command line:

- To permanently set `ANT_HOME`, go to Windows Control Panel > System > Advanced > Environment Variables dialog and either create or edit a System variable named `ANT_HOME` so that its value is the Apache Ant folder. For example, in the System variables box enter the following:

Variable Value `ANT_HOME` `C:\ant\apache-ant-1.6.5`

- To temporarily set `ANT_HOME`, enter the following command in a Command Prompt window:

    set ANT_HOME=C:\ANT_HOME_path;

For example if Ant was installed in `C:\ant\apache-ant1.6.5`, enter:

    set ANT_HOME=C:\ant\apache-ant1.6.5;

3. Set the `JC_CONNECTED_HOME` system variable to the development kit root directory.

Before running the development kit, you must set the `JC_CONNECTED_HOME` environment variable permanently in the Windows Control Panel or temporarily from the command line:

Note - Some of the command line tools require that the `JC_CONNECTED_HOME` variable is set correctly.

- To permanently set `JC_CONNECTED_HOME`, go to Windows Control Panel > System > Advanced > Environment Variables dialog and either create or edit a system variable named `JC_CONNECTED_HOME` variable so that its value is either `C:\JCDK3.0.2_ConnectedEdition` or the directory you specified during installation. For example, in the System variables box enter the following:

Variable Value `JC_CONNECTED_HOME` `C:\JCDK3.0.2_ConnectedEdition`

- To temporarily set `JC_CONNECTED_HOME`, enter the following command in a Command Prompt window:

    set JC_CONNECTED_HOME=C:\JC_CONNECTED_HOME_path;

For example if you installed in `C:\JCDK3.0.2_ConnectedEdition`, enter:

    set JC_CONNECTED_HOME=C:\JCDK3.0.2_ConnectedEdition;

4. Add `%JAVA_HOME%,` `%JC_CONNECTED_HOME%`, and `%ANT_HOME%` to the `Path` variable displayed in the Environment Variables panel.

5. Add MinGW to the `Path` variable.

MinGW is not required if only the development kit binary bundle is installed. If the development kit source bundle is installed, set the `MinGW` environment variable permanently in the Windows Control Panel or temporarily from the command line:

- To permanently set the MinGW path, edit the `Path` variable in the System variables box to include the location of `MinGW\bin`:

    C:\MinGW\bin;

- To temporarily set the MinGW path, enter the following command in a Command Prompt window:

    set PATH=C:\MinGW_path;%PATH%

For example, if MinGW is installed in the `C:\MinGW` directory, enter:

    set PATH=C:\MinGW\bin;%PATH%

Note - If you choose to set the `JAVA_HOME` variable and MinGW `PATH` each time you run the development kit, place the appropriate `JAVA_HOME` variable and MinGW `PATH` commands in a batch file.

##

Installed Directories and Files

A development kit binary bundle installs the subdirectories and files described in TABLE 2-1. A development kit source bundle installs all the subdirectories and files described in TABLE 2-1, plus the source subdirectories and files described in TABLE 2-2.

### Directories and Files Installed From All Bundles

These files and directories are installed by the development kit under the root installation directory, `C:\JCDK3.0.2_ConnectedEdition`, or in the directory that you specified during installation.

TABLE 2-1 Directories and Files Installed From All Bundles
Directory or File | Description
--- | ---
`COPYRIGHT-software.html` | The copyright file for the Java Card 3 platform.
`COPYRIGHT-docs.html` | The copyright file for the documentation of the Java Card 3 platform.
`RELEASENOTES.html` | The release notes for this Java Card 3 platform development kit.
`document.css` | The style sheet for the HTML documentation.
`platform.properties` | Specifies properties of the Java Card 3 platform RI that are used by the tools.
`api_export_files\` | Contains `java`, `javacard`, and `javacardx` directories of API export files.
`bin\` | Contains all shell scripts and batch files (including the `cjcre.exe` binary executable) used in running the tools.
`docs\` | Contains the following: `api` folder - The Javadoc tool files for the RI API in HTML format. `JCDevKitUG-Connected-3_0_2.pdf` - This user’s guide. `UserGuide_html` folder - The HTML version of this user’s guide. `apduio` folder - The Javadoc tool files for the publicly available APDU I/O client classes.
`legal\` | Contains three files: `TechnologyEvaluationLicense.txt` - License for the Java Card 3 platform. `THIRDPARTYREADME.txt` - License for the Jetty HTTP Server. `Distribution_ReadME.txt` - Describes the terms and conditions for redistribution of the Java Card development kit.
`lib\` | Contains all Java programming language JAR files and `config` files required for the tools: `ant-contrib-1.0b3.jar` `api_classic.jar` `api_connected.jar` asm-all-3.1.jar bcel-5.2.jar `commons-cli-1.0.jar` `commons-codec-1.3.jar` `commons-httpclient-3.0.jar` `commons-logging-1.1.jar` config.properties `jcapt.jar` jctasks.jar nbtasks.jar nbutils.jar romizer.jar system.properties tools.jar
`Uninstaller\` | Contains the file `uninstaller.jar` to safely uninstall this development kit.
`samples\classic_applets` | Contains the sample HelloWorld classic applet application adapted to run on the Connected Edition.
`samples\extended_applets` | Contains the sample extended applet application.
`samples\keystore` | Contains keystore and other certificate files for use by the samples provided in this release. These keystore and other certificate files are for demonstration purposes only and cannot be used for developing deployable applications.
`samples\web` | Contains the sample web application.

### Subdirectories and Files Installed in the `src` Directory

The `src` directory is installed only from a source bundle and contains the source code for the Java Card API, the romized applications, the development kit tools, and the Java Card virtual machine.

TABLE 2-2 describes the contents of the subdirectories and files installed under the `src` directory.

TABLE 2-2 Contents of the `src` Directory
Directory or File | Description
--- | ---
`build.xml` | Resource file for rebuilding the development kit source bundle.
`apiImpl.jar` |
`bat.template` |
`crypto.jar` |
`api\` | Sources for the Java Card API version 3.0.2 in the following subdirectories: `com\sun` `java` `javacard` `javacardx` `javax` `org\mortbay`
`romized_apps\` | Sources for the CardManager servlet.
`tools\` | Sources for development kit tools.
`vm\` | Sources for the Java Card virtual machine in the following subdirectories and file: `c` - C programming language sources. `h` - Header files for the C programming language sources. `lib` - System and internal web configuration files `ignore.list` - List of classes ignored by the ROMizer

##

Uninstall the Development Kit

To uninstall the development kit, Version 3.0.2, run the Uninstaller tool found in your development kit at Uninstaller\uninstaller.jar. Do not change the location of this tool. Before running the Uninstaller, it is advisable to exit all development kit tools and the NetBeans IDE. Files under the control of your OS will not be uninstalled using the Uninstaller.

In the Uninstaller’s dialog box, selecting the check box or not will have the same result, the development kit directory that the Uninstaller is in will be deleted, including the Uninstaller itself, see FIGURE 2-1.

FIGURE 2-1 Uninstalling the Development Kit

You can also uninstall a development kit for any Java Card Platform release by simply deleting all its directories and files from your hard drive.

##

Install and Setup the NetBeans IDE

The NetBeans IDE, version 6.8, is required to run the samples. It is also recommended as your development environment, although alternatively, the development kit tools can be used from the command line.

To use the Java Card platform-specific plugin in the NetBeans IDE, you must add and configure the Java Card Platform.

### Installing the NetBeans IDE

1. Go to `http://www.netbeans.org`.

2. Download version 6.8.

Earlier versions of the NetBeans IDE and the plugin will not work with version 3.0.2 of the development kit. Within version 6.8 of the NetBeans IDE, the Java Card platform-specific plugin might already be installed. Check the installed plugins list and, if the Java card plugins are not installed, locate them on the NetBeans IDE update center and install them into the NetBeans IDE.

### Setting Up the Java Card Platform

1. In the NetBeans IDE, version 6.8, go to `Tools > Java Platforms` and click `Add Platform`.

You setup the Java Card Platform as you would any other Java Platform. If the Java Card Platform does not appear on the list of platform types, you might need to exit the NetBeans IDE and restart it.

2. Select `Java Card Platform` and click `Next`.

3. Navigate to and choose the directory where you installed the Java Card Platform development kit and click `Next`.

In the documentation for the development kit this directory is referred to as JC_CONNECTED_HOME.

4. Click `Finish`.

5. Click `Close`.

Once the installation is complete, there will be a new node, `Java Card Runtimes`, in the `Services` window. If the `Services` window is not already displayed, choose `Window`, then choose `Services` to activate it.

6. Confirm `Java Card Platform` node is listed in `Services` window below the `Java Card Runtimes` node.

7. Confirm the Default Device instance is listed in the `Services` window below the `Java Card Platform``` node.

8. In the `Tools > Plugins` dialog box, confirm the `Available Plugins` Tab lists the Java Card platform-specific plugin.

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