| Development Kit User's Guide |     |
| 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:
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 Process of Generating Application Modules From Classic Applets
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:
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.
TABLE 9-1 identifies the normalize subcommand options and provides their descriptions.
| |
|
|---|---|
(Optional) This the default setting and does not have to be explicitly set. Specifies the output directory that contains the export file. |
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
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
The copyright subcommand displays the detailed copyright notice. There are no options associated with this 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.
The following command displays summary help about the Normalizer:
normalizer.bat help
The following command displays help about the normalize subcommand:
normalizer.bat help normalize
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.
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:
When a package is used as a mask, restrictions on native methods are relaxed.
When the Converter runs, it performs the conversion process in the following sequence:
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 .
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.
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:
During package reimplementation, the API of the package (exportable classes, interfaces, fields and methods) must remain exactly the same.
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).
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.1_ConnectedEdition\api_export_files\javalang\javacard for the export file lang.exp .
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.)
By default, the converter invokes the off-card verifier for every input EXP file and on the output CAP and EXP files.
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.
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.
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 .
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.
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
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.
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.
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
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
| Development Kit User's Guide | May 2009 | |
Copyright © 2009 Sun Microsystems, Inc. All rights reserved.