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:


Install and Setup the Development Kit

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


procedure icon  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.


Installation 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.


procedure icon  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:

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:

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.


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:

C:\MinGW\bin;
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


dialog box for uninstaller

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.


procedure icon  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.


procedure icon  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.


install Java Card platform dialog box

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.