Backwards Compatibility for Classic Applets
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 9

Backwards Compatibility for Classic Applets

This chapter describes how to generate application modules for classic applets by using the Normalizer tool (Normalizer). These application modules contain classic CAP files and provide backwards compatibility for the Java Card 3 platform by enabling classic applets to run on Connected Edition and Classic Edition cards.

This chapter contains the following sections:

- Generating Application Modules From Classic Applets

- Converting Class Files to CAP Files

##

Generating Application Modules From Classic Applets

Developers use the Normalizer to generate application modules for applets created for previous version of the Java Card platform. The Normalizer can generate application module from existing modules when there is no source is available. These application modules contain CAP files and are downloadable on both the Java Card 3 platform Classic Edition and Connected Edition cards.

The output from the tool is a classic module that contains the class files, the CAP components of the CAP file, SIO proxies for classic SIOs (if used), and associated classic application descriptors. The input to the tool must be classic CAP files and associated EXP files. If the input files are not classic CAP files, the normalization will fail. See Appendix A for a description of the application module and library formats supported by the Java Card 3 platform card manager. FIGURE 9-1 illustrates the process of generating application modules from classic applets and deploying them on both the Java Card 3 platform Classic Edition and Connected Edition cards.

FIGURE 9-1 Generating Application Modules From Classic Applets

### Running the Normalizer From the Command Line

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

    normalizer.bat subcommand [options]

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

- `normalize` - Creates the package class files

- `copyright` - Displays detailed copyright notice

- `help` - Displays information about the Normalizer command

#### `normalize` Subcommand

Use the `normalize` subcommand and its options to create the package class files. Options are used with the `normalize` subcommand to specify input files, export paths, export file names, and output directories.

##### `normalize` Subcommand Options

TABLE 9-1 identifies the `normalize` subcommand options and provides their descriptions.

TABLE 9-1 `normalize` Subcommand Options
Option | Description
--- | ---
`-`C command-options-file or `--`commandoptionsfile command-options-file | Optional. Specifies a file containing command line options.
`-i` file or `--in` file | Specifies the input CAP file name.
`-k` or `--keepall` | Specifies the directory to keep class files, proxy classes, and CAP components. The output format is as follows: <`directory`> / <`application classes`> / `proxy`/ `[proxy classes]` / `javacard`/ `*.cap`
`-p` path or `--exportpath` path | Specifies the path of the export files used by the tool.
`-f` file or `--exportfile` file | Specifies the name of the export file.
`-o` directory or `--out` directory | (Optional) This the default setting and does not have to be explicitly set. Specifies the output directory that contains the export file.

##### `normalize` Subcommand Format

The following is the format of the `normalize` subcommand. Options in the subcommand are used in the sequence that are presented in TABLE 9-1. In this format example, an input file and an output directory are specified as options:

    normalizer.bat normalize  --in file --exportpath path --out directory

##### `normalize` Subcommand Example

The following is an example of the `normalize` subcommand in which an input file (myCAP.cap) is specified as an option:

    normalizer.bat normalize -i myCAP.cap

#### `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 Normalizer command. Options are used with the `help` subcommand to specify the information that is displayed about each sub-command.

##### Normalizer Summary Help

The following command displays summary help about the Normalizer:

    normalizer.bat help

##### `normalize` Subcommand Help

The following command displays help about the `normalize` subcommand:

    normalizer.bat help normalize

##

Converting Class Files to CAP Files

This section describes using the Converter tool (Converter) provided for the Connected Edition as a stand-alone tool. When run as a stand-alone tool, the Converter can take class files from `javac` and convert them into CAP files that can be loaded by the Connected Edition platform.

Note - If you are developing a classic applet application you want to deploy using the classic development kit, create your CAP file as described in this chapter. Then you can take your CAP file to the classic development kit to deploy it on the classic Java Card VM.

The Converter is part of the Developer Kit tool chain and is also used by the Normalizer to create application modules for classic applets. The Normalizer can generate application module from existing modules when there is no source is available. See Chapter 9 for a description of using the Normalizer to create application modules from classic applets.

The CAP file is a JAR-format file which contains the executable binary representation of the classes in a Java package. The CAP file also contains a manifest file that provides human-readable information regarding the package that the CAP file represents. For more information on the CAP file and its format, see Chapter 6 of the Virtual Machine Specification, Java Card Platform, Version 3.0.1, Connected Edition.

When running the Converter as a stand-alone tool, developers can use the command line options described in TABLE 9-2 to:

- Specify the root directory where the Converter looks for classes.

- Specify the root directories where the Converter looks for export files.

- Use the token mapping from a pre-defined export file of the package being converted. The Converter will look for the export file in the export path.

- Set the applet AID and the class that defines the install method for the applet.

- Specify the root directories where the Converter outputs files.

- Specify that the Converter output one or more of the following:

- CAP file

- JCA file

- EXP export file

- Identify that the package is used as a mask.

When a package is used as a mask, restrictions on native methods are relaxed.

- Specify support for the 32-bit integer type.

- Enable generation of debugging information.

- Turn off verification (the default of input and output files. Verification is default.

### Conversion Process Sequence

When the Converter runs, it performs the conversion process in the following sequence:

1. Loads the package.

If the `exportmap` option is set, the converter loads the package from the export path (see Specifying an Export Map). Loads the class files of the Java package and creates a data structure to represent the package.

2. Subset checking.

Checks for unsupported Java features in class files.

3. Conversion.

Checks for consistency between the applet AIDs and the imported package AIDs.

4. Reference Checking.

Checks that all references are valid, internal referenced items are defined in the package, import items are declared in the export files (see Loading Export Files).

5. The Converter creates the `JcImportTokenTable` to store tokens for import items (class, methods, and fields).

If the Converter only generates an export file, it does not check private APIs and byte code. Also included is a second round of subset checking that operations do not exceed the limitations set by the Virtual Machine Specification, Java Card Platform, Version 3.0.1, Connected Edition.

6. Optimization.

Optimizes the bytecode.

7. Generates output.

Builds and outputs the EXP export file and the JCA file, checks the package version in the export file of the current package against the package version specified in the command line. If the `-exportmap` option is used in the command line, the export file specified in the command line must represent the same version as that of the package. The converter does not support upgrading the export file version.

8. Before writing the export and JCA files, the Converter determines the output file path.

The Converter assumes the output files are written into the director: root_dir`\`package_dir`\javacard.` By default the root_dir is the classroot directory specified by `-classdir` option. Users can specify a different root_dir by using `-d` option.

### Specifying an Export Map

You can request that the Converter convert a package using the tokens in a pre-defined export file of the package being converted. Use the `-exportmap` command option to do this. The Converter loads the pre-defined export file in the same way that it loads other export files.

There are two distinct cases when using the `-exportmap` flag is desired:

- When the minor version of the package is the same as the version given in the export file (this case is called package reimplementation).

During package reimplementation, the API of the package (exportable classes, interfaces, fields and methods) must remain exactly the same.

- When the minor version increases (package upgrading).

During a package upgrade, changes that do not break binary compatibility with preexisting packages are allowed (See “Binary Compatibility” in Section 4.4 of the Virtual Machine Specification, Java Card Platform, Version 3.0.1, Connected Edition).

For example, you must use the `-exportmap` option to preserve binary compatibility with already existing packages that use the package when reimplementing a method (package reimplementation) in an existing package or upgrading an existing package by adding new API elements (new exportable classes or new public or protected methods or fields to already existing exportable classes).

### Loading Export Files

A Java Card technology-based export file (export file) contains the public API linking information of classes in an entire package. The Unicode string names of classes, methods and fields are assigned unique numeric tokens.

Export files are not used directly on a device that implements a Java Card virtual machine. However, the information in an export file is critical to the operation of the virtual machine on a device. An export file is produced by the Converter when a package is converted. This package's export file can be used later to convert another package that imports classes from the first package. Information in the export file is included in the CAP file of the second package, then is used on the device to link the contents of the second package to items imported from the first package.

During the conversion, when the code in the currently-converted package references a different package, the Converter loads the export file of the different package. An applet package is linked with the `java.lang`, the `javacard.framework` and `javacard.security` packages via their export files.

You can use the `-exportpath` command option to specify the locations of export files. The path consists of a list of root directories in which the Converter looks for export files. Export files must be named as the last portion of the package name followed by the extension `.exp`. Export files are located in a subdirectory called `javacard`, following the Java Card platform’s directory naming convention.

For example, to load the export file of the package `java.lang`, if you specify
`-exportpath` as `c:\myexportfiles`, the Converter searches the directory
`JCDK3.0.2_ConnectedEdition\api_export_files\java\lang\javacard` for the export file `lang.exp`.

### Creating a `debug.msk` Output File

If you select the `-mask` and `-debug` options, the file `debug.msk` is created in the same directory as the other output files. (Refer to converter Command Options.)

### Verification of Input and Output Files

By default, the converter invokes the off-card verifier for every input EXP file and on the output CAP and EXP files.

- If any of the input EXP files do not pass verification, then no output files are created.

- If the output CAP or EXP files do not pass verification, then the output EXP and CAP files are deleted.

If you want to bypass verification of your input and output files, use the `-noverify` command line option. Note that if the converter finds any errors, output files will not be produced.

### File and Directory Naming Conventions

This section describes the naming conventions used for the input and output files of the Converter, and gives the correct location for these files. With some exceptions, the Converter follows the Java programming language naming conventions for default directories for input and output files. These naming conventions are also in accordance with the definitions in Section 4.1 of the Virtual Machine Specification, Java Card Platform, Version 3.0.1, Connected Edition.

#### Input File Naming Conventions

The files input to the Converter are Java class files named with the `.class` suffix. Generally, there are several class files making up a package. All class files for a package must be located in the same directory under the root directory, following the Java programming language naming conventions. The root directory can be set from the command line using the `-classdir` option. If this option is not specified, the root directory defaults to be the directory from which the user invoked the Converter.

For example, the following command line would be used to convert the package `java.lang`, use the `-classdir` flag to specify the root directory as `C:\mywrk`:

    converter -classdir C:\mywrk java.lang package_AID package_version

In the example, package_AID is the application ID of the package and package_version is the user-defined version of the package. The Converter will look for all class files in the `java.lang` package in the directory `C:\mywrk\java\lang`.

#### Output File Naming Conventions

The name of the CAP file, export (EXP) file, and the Java Card Assembly (JCA) file must be the last portion of the package specification followed by the extensions `.cap`, `.exp`, and `.jca`, respectively. By default, the files output from the Converter are written to a directory called `javacard`, a subdirectory of the input package's directory. In the previous example, the output files are written by default to the directory `C:\mywrk\java\lang\javacard`.

The `-d` flag is used to specify a different root directory for output.

In the previous example, using the `-d` flag to specify the root directory for output to be `C:\myoutput` would cause, the Converter to write the output files to the directory `C:\myoutput\java\lang\javacard`.

When generating a CAP file, the Converter creates a JCA file in the output directory as an intermediate result. If you do not want a JCA file to be produced, do not use the option `-out` `JCA.`The Converter deletes the JCA file at the end of the conversion when the option `-out` `JCA` is not used.

### Running the Converter From the Command Line

The command line interface for running the Converter takes one of the following forms:

    converter.bat options package_name  package_aid  major_version.minor_version

or

    converter.bat -config filename

Use the `-config` subcommand and the associated configuration file to provide the options and parameters to the Converter. See Using a Command Configuration File.

#### `converter` Command Options

Use the `converter` command options to specify input files, an export path, an export map, names, and output directories.

TABLE 9-2 identifies the `converter` command options and provides their description.

TABLE 9-2 `converter` Command Options
Option | Description
--- | ---
`-classdir` root- directory-of-class-hierarchy | Specifies the root directory where the Converter looks for classes.
:`-keepproxysource` directory | Cannot be used with `-useproxyclass`. Creates the proxy source files and other stub files in the specified directory. The Converter also builds CAP files as usual in the specified output directory. Supports customizing the proxy files generated by the Converter. Requests the Converter retain the intermediate proxy class source code in the specified directory and the source code of the associated stub classes representing the dependent external classes using the hierarchical directory structure of the Java package name(s).
`-usecapcomponents` component | :User-supplied cap components
`-useproxyclass` classpath | User-supplied proxy classes (proxy classes not generated by converter)
`-i` | Specifies support the 32-bit integer type.
`-exportpath` list-of-directories | Specifies the root directories where the Converter looks for export files.
`-exportmap` | Uses the token mapping from the pre-defined export file of the package being converted. The converter will look for the export file in the exportpath.
`-applet` AID class-name | Sets the applet AID and the class that defines the install method for the applet.
`-d` root-directory-for-output | Specifies the root directories where the Converter outputs the files.
`-out [CAP] [EXP] [JCA]` | Specifies that the Converter output the `CAP` file, and/or the `JCA` file, and/or the `EXP` export file.
`-V` or `-version` | Displays the Converter version number.
`-v` or `-verbose` | Enables verbose output.
`-help` | Displays the contents of this table.
`-nowarn` | Instructs the Converter to not report warning messages.
`-mask` | Identifies this package is used for a mask. Restrictions on native methods are relaxed.
`-debug` | Enables generation of debugging information.
`-nobanner` | Suppresses standard output messages.
`-noverify` | Turns off verification. Verification is default.
`-sign` | Signs the output CAP file.
`-keystore` keystore | Specifies the keystore to use in signing.
`-storepass` storepass | Specifies the keystore password.
`-alias` alias | Specifies the keystore alias to use in signing.
`-passkey` passkey | Specifies alias password.

#### Using a Command Configuration File

Instead of entering all of the command line arguments and options on the command line, you can include them in a text-format configuration file. This is convenient if you frequently use the same set of arguments and options.

The syntax to specify a configuration file is:

    converter -config filename

The filename argument contains the file path and file name of the configuration file.

You must use double quote (“) delimiters for the command line options that require arguments in the configuration file. For example, if the options from the command line example used in Using Delimiters with Command Line Options were placed in a configuration file, the result would look like this:

    -exportpath ".\export files;.;%JC_CONNECTED_HOME%\
    api_export_files" MyWallet 0xa0:0x00:0x00:0x00:0x62:0x12:0x34 1.0

#### Using Delimiters with Command Line Options

If the command line option argument contains a space symbol, you must use delimiters with this argument. The delimiter is a double quote (“ ”).

In the following sample command line, the Converter will check for export files in the `.\export` files, `%`JC_CONNECTED_HOME`%\api_export_files`, and current directories.

    converter -exportpath ".\export files;.;%JC_CONNECTED_HOME%\
    api_export_files" MyWallet 0xa0:0x00:0x00:0x00:0x62:0x12:0x34 1.0

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