Converting and Exporting Java Class Files

C H A P T E R 5

This chapter describes how to use the Converter tool, including the input files it can process and the output it produces. How to work with export files is also described.

The Converter takes as input the class files that make up a Java programming language package. The Converter verifies that class files comply to limitations described in Section 2.2, “Java Card Platform Language Subset” in the Virtual Machine Specification, Java Card Platform, Version 3.0.1, Classic Edition.

The Converter can output a CAP file, a Java Card Assembly file, or an export file. The CAP file is a JAR-format file which contains the executable binary representation of the classes in a Java package. 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, Classic Edition. 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 manifest file and its contents, see Chapter 7.

For more information on the Java Card Assembly file, see Appendix A and Chapter 10. For more information on export files, see Using Export Files.

You are responsible for the consistency of your input data. This means that:

all input class files are compatible with each other.

export files of imported packages are consistent with class files that were used for compiling the converting package.

The Converter generates the following output files:

A CAP file for the Java Card 3 Platform, Classic Edition

A Java Card Assembly file

An export file

If the package to be converted contains remote classes or interfaces or if the -debug option is specified, the Converter generates a CAP file suitable for version 2.2 or greater of the Java Card platform. Otherwise, the Converter generates files that can also be used by version 2.1 of the Java Card platform. To create a CAP file compatible with version 2.1 of the Java Card platform, you must also use export files for Java Card API packages from the Java Card development kit 2.1.x.

If you are converting more than one package with interdependencies, convert the packages in two passes. First, generate only the export files, then, after that, convert the required CAP or Java Card Assembly files. The Converter tool cannot convert more than one package at a time.

If you have a source release, you may choose to convert packages that import other packages. If you are creating Java Card Assembly files to generate a mask, then the major and minor version number of the imported packages must agree with the version number of the package that imports them. Please see Version Numbers for Processed Packages for more information.

If you have a source release, you can localize locale-specific data associated with the Converter. For more information, see Chapter 14.

Setting Java Compiler Options

Before you use the Converter tool, be sure to compile your Java code properly.

For the most efficient conversion, compile your class files with the Java SDK compiler’s -g command line option. The -g option causes the compiler to generate the LocalVariableTable attribute in the class file. The Converter uses this attribute to determine local variable types. If you do not use the -g option, the Converter attempts to determine the variable types on its own. This is expensive in terms of processing and might not produce the most efficient code.You must also compile your class files with the -g option if you want to generate a debug component in the CAP file by using the Converter’s -debug option.

Do not compile with the -O option. The -O option is not recommended on the Java compiler command line, for these reasons:

this option is intended to optimize execution speed rather than minimize memory usage. Minimizing memory usage is much more important in the Java Card environment.

the LocalVariableTable attribute will not be generated.

Running the Converter

You invoke the Converter at the command line as follows (see TABLE 5-4 for a description of the arguments):

converter.bat [options] package-name package-aid major-version.minor-version

Note - The file to invoke the Converter is a batch file (converter.bat) that must be run from a working directory of JC_CLASSIC_HOME\bin in order for the code to execute properly.

The Converter command line options described in detail in TABLE 5-4 and allow you 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 the default.).

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

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.

Subset checking - Checks for unsupported Java features in class files.

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

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 Using Export Files).

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 JCVM specification.

Optimization - Optimizes the bytecode.

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.

Before writing the export and JCA files, the Converter determines the output file path. The Converter assumes the output files are written into the directory: 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.

TABLE 5-4 Converter Command Line Argumentss
Option	Description
`-help`	Prints help message.
package-name	Fully-qualified name of the package to convert.
package-aid	5- to 16-decimal, hex or octal numbers separated by colons. Each of the numbers must be byte-length.
major-version minor-version	User-defined version of the package.
`-applet` AID class_name	Sets the default applet AID and the name of the class that defines the applet. If the package contains multiple applet classes, this option must be specified for each class.
`-classdir` root-directory-of-class hierarchy	Sets the root directory where the Converter will look for classes. If this option is not specified, the Converter uses the current user directory as the root.
`-d` root-directory-for-output	Sets the root directory for output.
`-debug`	Generates the optional debug component of a CAP file. If the `-mask` option is also specified, the file `debug.msk` will be generated in the output directory. Note - To generate the debug component, you must first compile your class files with the Java compiler’s `-g` option.
`-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`.
`-exportpath` list-of-directories>	Specifies the root directories in which the Converter will look for export files. The separator character for multiple paths is the semicolon (`;`). If this option is not specified, the Converter sets the export path to the Java `classpath`.
`-i`	Instructs the Converter to support the 32-bit integer type.
`-mask`	Cannot be used with `-out` [CAP]. Indicates this package is for a mask, so restrictions on native methods are relaxed. If you have a source release, you can specify this option to generate a mask out of this package using `maskgen`.
`-nobanner`	Suppresses all banner messages.
`-noverify`	Suppresses the verification of input and output files. For more information on file verification, see Verification of Input and Output Files.
`-nowarn`	Instructs the Converter not to report warning messages.
`-out` [CAP] [EXP] [JCA]	Cannot be used with `-mask`. Instructs the Converter to output the CAP file, and/or the export file, and/or the Java Card Assembly file. By default (if this option is not specified), the Converter outputs a CAP file and an export file.
`-v`, `-verbose`	Enables verbose output. Verbose output includes progress messages, such as “opening file”, “closing file”, and whether the package requires integer data type support.
`-V`, `-version`	Prints the Converter version string.
`-sign`	Specifies to sign the output CAP file
`-keystore` value	Keystore to use in signing
`-storepass` value	Keystore password
`-alias` value	Keystore alias to use in signing
`-passkey` value	Alias password
`-useproxyclass`	Cannot be specified with `keepproxysource`. Builds CAP files as usual in the specified output directory using the existing class files of the application and existing class files of the associated proxy sub-package. New proxy classes are not created. Provides a way for the application developer to build a CAP file with customized proxy files. This option requests the converter to take the class files of the application package and the class files of the co-located proxy sub-package to build a new CAP file. The classes in the application package are converted into new `.cap` components. New descriptors are created. Dynamically-loaded-classes attributes need to be recomputed based on the new Proxy class file names.
`-usecapcomponents`	Specifies that the converter retain the specified user supplied CAP components instead of generating them in the final CAP bundle. The input format is as follows: `<application classes directory>` `/ <application classes>` `/ javacard/ *.cap`
`-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).

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_CLASSIC_HOME\api_export_files, and current directories.

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

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 <configuration file name>

The <configuration file name> 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_CLASSIC_HOME\api_export_files" 	MyWallet 0xa0:0x00:0x00:0x00:0x62:0x12:0x34 1.0

File Naming for the Converter

This section describes the names of input and output files for 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, Classic 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 the 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.

Suppose, for example, you wish to convert the package java.lang. If you use the
-classdir flag to specify the root directory as C:\mywork, the command line will be:

converter -classdir C:\mywork java.lang <package_aid> 		<package_version>

where <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:\mywork\java\lang.

Output File Naming Conventions

The name of the CAP file, export file, and the Java Card Assembly 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 above example, the output files are written by default to the directory C:\mywork\java\lang\javacard.

The -d flag allows you to specify a different root directory for output.

In the above example, if you use the -d flag to specify the root directory for output to be C:\myoutput, the Converter will write the output files to the directory C:\myoutput\java\lang\javacard.

When generating a CAP file, the Converter creates a Java Card Assembly file in the output directory as an intermediate result. If you do not want a Java Card Assembly file to be produced, omit the option -out JCA. The Converter deletes the Java Card Assembly file at the end of the conversion.

Verification of Input and Output Files

By default, the Converter invokes the Java Card technology-based off-card verifier (“Java Card 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 does 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.

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. (See Running the Converter and TABLE 5-4.)

Using 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. The Converter also tries to load the shareable interface class files being imported from that package.

For more information on export files, see Chapter 12.

FIGURE 5-6 illustrates how 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 and the shareable interface class files. The path consists of a list of root directories in which the Converter looks for export files and shareable interface class 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 relative directory path that matches the package name. The shareable interface class files are located in the relative directory path that matches the package name.

For example, to load the export file of the package java.lang, if you have specified
-exportpath as c:\myexportfiles, the Converter searches the directory
c:\myexportfiles\java\lang\javacard for the export file lang.exp.

FIGURE 5-6 Calls Between Packages Go Through The Export Files

This figure was explained before the caption.

Specifying an Export Map

You can request the Converter to convert a package using the tokens in the pre-defined export file of the package that is being converted. Use the -exportmap command option to do this.

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, Classic Edition).

For example, if you have developed a package and would like to reimplement a method (package reimplementation) or upgrade the package by adding new API elements (new exportable classes or new public or protected methods or fields to already existing exportable classes), you must use the -exportmap option to preserve binary compatibility with already existing packages that use your package.

The Converter loads the pre-defined export file in the same way that it loads other export files.

Viewing an Export File as Text

The exp2text tool is provided to allow you to view any export file in text format (see TABLE 5-5 for a description of the options).

exp2text.bat [options] package-name

Note - The file to invoke exp2text is a batch file (exp2text.bat) that must be run from a working directory of JC_CLASSIC_HOME\bin in order for the code to execute properly.

TABLE 5-5 `exp2text` Command Line Options
Option	Description
`-classdir` input-root-directory	Specifies the root directory where the program looks for the export file.
`-d` output-root-directory	Specifies the root directory for output.
`-help`	Prints help message.

If you have a source release, you can localize locale-specific data associated with the exp2text tool. For more information, see Chapter 14.