Running the Converter

To run the Converter:

Invoke the Converter by enter the following at the command line:

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

Note:

The converter.bat file used to invoke the Converter is a batch file that you must 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 Table 5-1 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 looks 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). It 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, and 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 class root directory specified by the -classdir option. Users can specify a different root_dir by using the -d option.

Table 5-1 Converter Command Line Arguments

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 looks 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` is 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 looks for the export file in the `exportpath`.
`-exportpath` list-of-directories	Specifies the root directories in which the Converter looks 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-dir`/`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

To use delimiters with command line options:

Add a double quote (") around command line option arguments that contain a space symbol.

In the following sample command line, the converter checks 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.

To use a command configuration file:

Enter the command line arguments and options in a text-format configuration file.
Use double quote (") delimiters for the command line options that require arguments in 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
Specify the configuration file in the command line when you run the Converter.
The syntax to specify a configuration file is:

converter –config configurationfile name

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

Java Card: 3 Platform Development Kit User Guide, Classic Edition

Expand | Collapse

Previous Page Top of Page Next Page

Running the Converter

Using Delimiters with Command Line Options

Using a Command Configuration File

Table of Contents

Java Card: 3 Platform Development Kit User Guide, Classic Edition