Using Export Files
A Java Card technology-based 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. You can use this package's export file 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 Verifying CAP and Export Files.
Figure 5-1 illustrates how an applet package is linked with the java.lang
, the javacard.framework
and javacard.security
packages through their export files.
You can use the -exportpath
command option and the exportPath
JSON field 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-1 Calls Between Packages Go Through The Export Files
![Description of Figure 5-1 follows Description of Figure 5-1 follows](img/jcugc_dt_008_exportfiles.png)
Description of "Figure 5-1 Calls Between Packages Go Through The Export Files"
Specifying an Export Map
By specifying an export map, you can request the Converter to convert a package by using the tokens in the pre-defined export file of the package that is being converted. There are two distinct cases when using the -exportmap
flag:
-
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 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 the Java Card Platform Virtual Machine Specification, Classic Edition, Version 3.1).
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.
To specify an export map:
Viewing an Export File as Text
The exp2text
tool is provided to allow you to view any export file in text format. The file to invoke exp2text
is a batch file (exp2text.bat
) that must be run from a working directory of JC_HOME_TOOLS\bin
in order for the code to execute properly.
To view an export file as text:
- Enter the following command (see Table 5-4 for a description of the options):
exp2text.bat
[options] package-name
Table 5-4 exp2text Command Line Options
Option | Description |
---|---|
|
Specifies the root directory where the program looks for the export file. |
|
Specifies the root directory for output. |
|
Prints help message. |