Running the Converter

To run the Converter (use the .sh extension for the shell scripts file in Unix/Linux-like systems and use the .bat extension for batch script files in Windows systems):

1. For the compact mode, enter either of the following commands at the command line to invoke the Converter:

   converter.[sh | bat] [options] package-name package-AID major-version.minor-version

   Or

   converter.[sh | bat] -config <filename>

2. For the extended mode, enter the following command at the command line to invoke the Converter:

   converter.[sh | bat] -config <filename.json>

3. For showing the usage, enter either of the following commands at the command line to invoke the Converter:

   converter.[sh | bat] -help

   Or

   converter.[sh | bat] -help JSON

Note:

The converter.[sh | bat] file used to invoke the actual Converter directly from your working directory is a batch/script file only. If you have added JC_HOME_TOOLS\bin to your PATH you can call it directly, if not, you must precede it with JC_HOME_TOOLS\bin.

The Converter command line options described in the table below 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 pre-defined export files of the packages being converted. The Converter looks for the export files 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 outputs one or more of the following files:

  • CAP file

  • JCA file

  • EXP export file

• Identify that a 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.).

• Specify a list of file paths from where the static resources are loaded by the Converter, if any.

• Specify the target Java Card platform version on which the CAP file generated should be loaded, if it is not the newest released version of the Java Card platform.

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

1. Loads the packages - If the exportmap option is set for any of the packages, the Converter loads that package from the export path (see Specifying an Export Map). It loads the class files of the Java packages and creates a data structures to represent these packages.
2. Subset checking - Checks for unsupported Java features in class files.
3. Conversion - Checks for consistency between the applet AIDs, package AIDs, CAP file AID (if present), and the imported package AIDs.
4. Reference Checking - Checks that all references are valid, internal referenced items are defined in the packages belonging to the CAP file, 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 export files, 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.

5. Optimization - Optimizes the byte code.
6. Generates output - Builds and outputs one EXP export file for each package and one JCA file for each package, checks for each package version in the export file against the version specified in the command line or in the config file. If the -exportmap option is used for a specific package in the command line or config file, the export file specified in the command line for that package must represent the same version as that of the package. The converter does not support upgrading the export file version.

   Before writing the export files 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 | root_dir\package_dir\javacard ]

   By default, the root_dir is the class root directory specified by the -classdir option. You can specify a different root_dir by using the -d option.

   The Converter generates only one CAP file. In the compact mode, the CAP file contains only one package and it is written to the path mentioned into the preceding example [root_dir/package_dir/javacard | root_dir\package_dir\javacard ]. In the extended mode, the CAP file contains one or more packages and it is written into the following directory:

   [ output_dir/CAP_name/javacard | output_dir\CAP_name\javacard ]

   By default, the output_dir is the directory where the JSON configuration file, which used in the extended mode, is located. You can specify a different output_dir by defining a value for the outputDir field in the JSON configuration file.

Table 4-2 Converter Command Line Arguments

Option	Description
-help	Prints help message.
-help JSON	Prints a JSON definition file (schema), for the JSON configuration file to be used in extended mode. The JSON schema contains all of the fields that can be defined, the hierarchy of fields, field types, field descriptions, optionality, sample values, default values, and descriptions. The schema can be used (using various tools) for validating configuration files used for generating extended CAP files.
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 colon (:) for Unix/Linus OS or the semicolon (;) for Windows OS. 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	Indicates that the converted code is intended to be used to create a binary 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. This option can be used in conjunction with -out CAP, only if -debug is selected, to typically generate a CAP with debug component and use it to debug platform classes. Such CAP is not intended to be loaded on a platform and will fail verification if it contains native methods.
-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]	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).
-resourcepath <id1>:<resource_path1>,<id2>:<resource_path2>,...	Specifies the list of static resources that can be loaded into the CAP file that is generated by the Converter (in the compact mode). The entries in the list are delimited by the "," character. Each entry in the list contains two parameters delimited by the ":" character. The first parameter is an integer representing the id of the static resource and the second parameter is the path to the file, which has the actual binary content for the static resource. The path must be a valid path to a file on the disk for which the Converter should have read access.
-target <platform version>	Specifies the Java Card platform version on which the CAP file that is generated by the Converter (in the compact mode) is loaded. If -target is not specified, the default value would be the latest release version, that is, 3.2.0. Other valid values for -target are 3.0.4, 3.0.5, and 3.1.0. If you omit the -target option or if you are using a target greater than 3.0.5, the 2.3 version CAP files are generated. Otherwise, 2.2 or 2.1 version CAP files are generated, depending on the used features (debugging or RMI). Additionally, for the current release, the platform's api_export_files directory is not required to be given in the -exportpath option, it is chosen automatically based on the -target option.