| Development Kit User's Guide |     |
| A P P E N D I X C |
Development Kit Tool Commands |
This appendix provides a quick reference to the following commands used to run the Development Kit tools:
Use the apdutool.bat command from the JC_CONNECTED_HOME directory to send APDU commands to cjcre.exe where they are processed and returned to the APDU tool. The APDU tool displays both the command and response APDU commands on the console. See Chapter 10 for detailed information about the APDU tool.
The APDU tool is run from the command line using the following syntax:
apdutool.bat [-t0] [-verbose] [-nobanner] [-noatr] [-o outputFile] [-h hostname] [-p port] [-s serialPort] [-version] [inputFile ...]
Options for the apdutool.bat command include the following:
Displays descriptive text during operation.
Suppresses all banner messages.
Suppresses outputting an ATR (answer to reset).
Specifies an output file. If an output file is not specified with the -o option, output defaults to standard output.
Specifies the host name on which the TCP/IP socket port is found. See the -p portNumber option.
Specifies a TCP/IP socket port other than the default port (9025)
Specifies that the serial port is used for communication, rather than a TCP/IP socket port. For example, serialPort can be COM1 .
To use this option, the javax.comm package must be installed on your system.
If you enter the name of a serial port that does not exist on your system, the APDU tool will respond by printing the names of available ports.
Outputs the version information.
Allows you to specify the input script or scripts.
Displays online documentation for the apdutool.bat command. To get help for the APDU tool, run bin/apdutool.bat -help on the command line.
Use the cjcre.exe command to run the reference implementation (RI). The RI is a pre-built executable located in JC_CONNECTED_HOME \bin . See Chapter 5 for detailed information about the RI.
Assuming that JC_CONNECTED_HOME \bin is on your path, the following syntax is used to run the RI:
cjcre.exe [options]
Options must follow the cjcre.exe command on the command line. Valid cjcre.exe command options used in the command line consist of one or more of the following:
Sets a new configuration file. The default is lib/config.properties.
Sets the port used to simulate the contacted interface for APDU. The default value for -contactedport is 9025.
Sets the APDU protocol on this port, either T=0 or T=1 . The default value for the -contactedprotocol is T=1 .
Port number used to simulate contactless interface. Default is 9026. The protocol, T=CL, cannot be changed.
Sets the Clear On Reset (COR) memory size in which a portion of RAM is dedicated to COR memory. The range of values that the Java Card runtime environment can accept from the command line is 2K to 8K . The default value is 4K . size is set as a value in bytes ( 2345 ) or kilobytes ( 2K ).
Supplies a system property (such as -D myproperty = myvalue ). System properties set in this manner can be retrieved using the API’s System.getProperty("myproperty") method. A maximum of 50 -D properties can be passed in the command line.
Sets the debug port where the Debug proxy communicates. The default value for -debugport is 7019.
Supplies the file name in which the EEPROM image is stored.
Configures the amount of EEPROM used. size is set as a value in bytes ( 2345 ), kilobytes ( 32K ), or megabytes ( 4M ). The specified size is rounded up to a multiple of 4. For example, a size specified at 253, is rounded up to 256.
The range of values that the Java Card runtime environment can accept from the command line is 1M to 32M . The default value used is 4M . The value required to run the samples is between 2M and 32M .
Enables Java code assertions (the assert keywork in Java code).
Prints help and copyright messages.
Sets the HTTP port number on which cjcre will be listening. The default value for -httpport is 8019.
Sets the type of log messages output. All log messages up to the specified level are displayed.
Valid when -debugger is specified. Will not suspend threads at cjcre startup.
Configures the amount of RAM used. size is set as a value in bytes ( 2345 ), kilobytes ( 32K ), or megabytes ( 4M ).
The range of values that the Java Card runtime environment can accept from the command line is 64K to 32M . The default value used is 1M . The value required to run the samples is between 128K and 32M .
Restores the VM state from the previously saved EEPROM image and continues VM execution. When -resume is specified, other options such as -ramsize and -e2psize are ignored and the corresponding values are obtained from the EEPROM image.
Sets a single configuration property such as: -Xmyproperty=myvalue
Displays only the log messages that match the level set by the -loggerlevel option.
The Converter generates SIO proxy for the CAP file and adds it to the JAR created by the Normalizer. The CAP files are not changed by the Converter.
When the Normalizer is run, it automatically calls the Converter. A developer only needs to run the Converter as a separate operation when the Normalizer is not run. 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 file to provide all options and parameters to the Converter.
Use the following converter command options to specify input files, an export path, an export map, names, and output directories:
Specifies the root directory where the Converter looks for classes.
Specifies support the 32-bit integer type.
Specifies the root directories where the Converter looks for export files.
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.
Sets the applet AID and the class that defines the install method for the applet.
Specifies the root directories where the Converter outputs the files.
Specifies that the Converter output the CAP file, and/or the JCA file, and/or the EXP export file.
Displays the Converter version number.
Displays the contents of this table.
Instructs the Converter to not report warning messages.
Identifies this package is used for a mask. Restrictions on native methods are relaxed.
Enables generation of debugging information.
Suppresses standard output messages.
Turns off verification. Verification is default.
Keystore alias to use in signing.
Use the Debugger tool’s functionality, by starting the debugproxy ( debugproxy.bat ), attaching a Java technology enabled IDE to it, and then starting cjcre with the -debugger option. This tool is located in the JC_CONNECTED_HOME \bin directory. See Chapter 11 for detailed information about the Debugger tool.
The Debugger is run from the command line using the following syntax:
debugproxy.bat options filelocation
When starting debugproxy, include the -c (or --classpath ) option in the command to specify the path of the class files to be debugged. The debugproxy needs to know the location of class files being debugged.
The following is an example of a command that starts debugproxy and specifies myapp.war as the location of the class files to be debugged:
debugproxy.bat -c myapp.war
Use the installer.bat command to run the Off-Card installer. The Installer is a command-line tool that performs various card-management tasks such as loading or unloading an application, creating instances, and listing available applications. This tool is located in the JC_CONNECTED_HOME \bin directory. See Chapter 8 for detailed information about the Installer tool.
The Off-Card installer is run from the command line using the following syntax:
installer.bat subcommand [options] [arguments]
Each subcommand can take one or more options or arguments that must follow the subcommand but can be in any order. Some options might require a value. Command-line arguments are not bound to any particular option.
Subcommands for the Off-Card installer include the following:
The load subcommand can have one or more options and arguments.
Options must follow the subcommand on the command line. Valid load options include the following:
Specifies the location of the on-card installer where oncard installer - url represents the complete URL of the on-card installer.
Specifies the module name on the card, where module-or-library-name represents the name of the module or library.
Optional. Used when authentication is required. Specifies the password for the user set by the --user or -u subcommand, where password represents the required user password.
Specifies the name of the properties file that contains the BASE64 encoded certificate and signature, where signature-file represents the file name. This file is a simple properties file setting the following properties:
Specifies the type of file being loaded, where file-type represents one of the following values:
Optional. Used if authentication is required to access the card manager, where user-id represents the user name.
The load subcommand must include the application-module or library file name as an argument following the appropriate options.
installer.bat load -c oncard installer -url [-s signature-file] -t file-type -n module-or-library-name [-v] [-u user-id -p password] application-module (or library-file)
The following is an example of the installer load subcommand:
installer.bat load -c http://localhost:8019/cardmanager -s mysig.properties -n calc -t web Calculator.war
The create subcommand can have one or more options but has no arguments.
Options must follow the subcommand on the command line. Valid create options include the following:
Specifies the name of the applet loaded by load command, where applet-name-or-id represents the applet name.
Specifies the location of the on-card installer, where on-card installer url represents the complete URL.
Optional. Specifies the parameters (printable hex string) that will be passed to the install method of a classic or extended applet.
For web applications, the context name is used to create the web application. If none is specified, then the default Web-Context-Path from JCRD is used.
For Applet applications, this is the instance id for applet. If none specified, then a new instance id is created based on the aid of that applet.
The option must include the module-or-library-name . module-or-library-name represents the name of the module or library loaded by the load command.
Optional. Used when authentication is required. Sets the password for the user specified by the --user or -u subcommand.
Optional. If authentication is required to access the card manager, the user-id represents the user name.
installer.bat create -c oncard installer -url -n module-or-library-name [-a applet-name-or-id] [-d install-parameters][-i instance-name] [-v] [-u user-id -p password]
The following is an example of the installer create subcommand:
installer.bat create -c http://localhost:8019/cardmanager -n calc -i /MyCalc
The delete subcommand can have one or more options but no arguments.
Options must follow the subcommand on the command line. Valid delete options include the following:
Specifies the location of the on-card installer, where oncardinstaller - url represents the complete URL.
Instance name of the application or multiple instances of applications that need to be deleted, where name represents the instance name of the application.
Optional. Used when authentication is required. password is for the user specified by either the --user or -u subcommand.
Optional. Used if authentication is required to access the card manager. user-id represents the user name.
installer.bat delete -c oncardinstaller -url -i instance-name [-u user-id -p password]
The following is an example of the installer create subcommand:
installer.bat delete -c http://localhost:8019/cardmanager -i /MyCalc
The unload subcommand can have one or more options but no arguments.
Options must follow the subcommand on the command line. Valid unload options include the following:
Specifies the location of the on-card installer, where oncardinstaller - url represents the complete URL.
The option must include the module-or-library-name . module-or-library-name represents the name of the module or library loaded by the load command.
(Optional) Forces an attempt to delete any instances before unloading.
Optional. Used when authentication is required. password is for the user specified by either the --user or -u subcommand.
Optional. Used if authentication is required to access the card manager. user-id represents the user name.
installer.bat unload -c oncardinstaller -url -n module-or-library-name [-f] [-u user-id -p password]
The following is an example of the installer unload subcommand:
installer.bat unload -c http://localhost:8019/cardmanager -n calc
The list subcommand can have one or more options but no arguments.
Options must follow the subcommand on the command line. Valid list options include the following:
Specifies the location of the on-card installer, where oncardinstaller - url represents the complete URL.
Optional. Displays complete details of the application-modules, instances, and libraries.
Optional. Used when authentication is required. password is for the user specified by either the --user or -u subcommand.
Optional. Used if authentication is required to access the card manager. user-id represents the user name.
installer.bat list -c oncardinstaller -url [-d] [-v] [-u user-id -p password]
The following is an example of the installer list subcommand that displays summary information about application-modules, instances, and, libraries:
installer.bat list -c http://localhost:8019/cardmanager
The following is an example of the installer list subcommand that displays detailed information about application-modules, instances, and, libraries.
installer.bat list -d -c http://localhost:8019/cardmanager
Causes the installer to display summary or detailed information about one or more installer subcommands.
There are no options, but the help subcommand accepts a topic attribute of a specific subcommand name for which detailed information is displayed.
The following is an example of the help subcommand format:
installer.bat help subcommand
The following is an example of the help subcommand:
installer.bat help list
The Java Card 3 platform Compiler tool ( javacardc.bat ) is used by developers to compile the source code of Java Card 3 platform applications outside of an IDE. See Chapter 6 for detailed information about the Compiler tool.
The following is an example of the Compiler tool command format:
javacardc.bat [ options ] [ sourcefiles ] [ @list_files ]
In addition to the following Java Card 3 platform specific options, all standard javac options for JDK 1.6 can be used:
Generate only some debugging info.
Output messages about what the compiler is doing.
Output source locations where deprecated APIs are used.
Specify where to find user class files and annotation processors.
Specify where to find user class files and annotation processors.
Specify where to find input source files.
Override location of bootstrap class files.
Override location of installed extensions.
Override location of endorsed standards path.
Control whether annotation processing and/or compilation is done.
Names of the annotation processors to run; bypasses default discovery process.
Specify where to find annotation processors.
Specify where to place generated class files.
Specify where to place generated source files.
Specify whether or not to generate class files for implicitly referenced files.
Specify character encoding used by source files.
Provide source compatibility with specified release.
Generate class files for specific VM version.
Print a synopsis of standard options.
Options to pass to annotation processors.
Print a synopsis of nonstandard options.
Pass flag directly to the runtime system.
Use the normalizer.bat command to run the Normalizer tool to generate application modules from applets created for previous version of the Java Card platform. 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 required), 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.
Assuming that JC_CONNECTED_HOME \bin is on your path, use the following syntax to run the Normalizer:
normalizer.bat subcommand [options]
A subcommand must be the first argument on the command line after the normalizer.bat command. Valid subcommands for the normalizer.bat command can be any one of the following:
There are no options for the copyright subcommand.
The normalize subcommand creates the package class files. Options are used to specify input files, export paths, export file names, and output directories.
Specifies the input CAP file name.
Specifies the path of the export files used by the tool.
(Optional) This the default setting and does not have to be explicitly set. Specifies the output directory that contains the export file.
normalizer.bat normalize --in file --out directory
The following is an example of the normalize normalize subcommand:
normalizer.bat normalize -i myCAP.cap
Options are used to display summary information about the Normalizer subcommands and specific information about individual Normalizer sub-commands.
The following command displays summary help about the Normalizer tool:
normalizer.bat help
The following command displays help about the normalize subcommand:
normalizer.bat help normalize
Use the packager.bat command to run the Packager tool for creating signature information from application modules and for validating application modules. The Packager tool is located at JC_CONNECTED_HOME \bin . See Chapter 7 for detailed information about the Packager tool.
Assuming that JC_CONNECTED_HOME \bin is on your path, use the following syntax to run the packager:
packager.bat subcommand [options] module-or-folder
A subcommand must be the first argument on the command line after the packager.bat command. Valid subcommands for the packager.bat command can be any one of the following:
Can have one or more options. See create Subcommand and Options for the list of valid options.
Can have one option. See validate Subcommand for the list of valid options.
Use help sub-command to get more details on each sub-command
For example, to display detailed help about the create sub-command:
$>packager.bat help create
Options must follow the subcommand on the command line. Valid create subcommand options are as follows:
Application signing attribute, where alias is the name used to retrieve the key from the keystore.
(Optional) If specified, the Packager tool compresses the output Java Card 3 platform application with a deflate algorithm. If not specified, the Packager creates an uncompressed JAR file.
(Optional) If specified, sets the export files path. System’s api_export files are implicitely loaded.
(Optional) If specified, descriptors or application module assembly problems are automatically corrected when possible.
Application signing attribute, where keystore-file is the path and filename where private keys are stored. A key utility such as the JDK keytool must be used to create and maintain this file.
Suppress the warning messages.
Where file-name specifies the name of the output file.
(Optional) If specified, sets the package AID in //aid/<RID>/<PIX> format for classic-lib . Ignored if type is not classic-lib .
Application signing attribute. Where key-password is the password for the private key.
Specifies that the Packager sign the application. If --sign is specified, --keystore keystore-file , --storepass keystore-password , --passkey key-password, and --alias alias are required.
Application signing attribute, where keystore-password is the password for the keystore.
Where file-type is one of the following:
packager.bat create --out file-name [--type file-type] [--exportpath path-of-export-files] [--packageaid package-AID-for-classic-lib] [--sign --storepass keystore-password --passkey key-password --alias alias] [--compress] [--force] [--nowarn] module-or-folder
The following is an example of the packager create subcommand:
packager.bat create -o mymodule.jar -t web -c c:\mymodulefolder
The validate subcommand has a single option -t (or --type) that specifies the type of application module to be validated.
packager.bat validate [--type web |classic-lib | classic-applet | extension-lib | extended-applet] module-file-name (or module-directory-name)
The following is an example of the packager validate subcommand:
packager.bat validate -t web myapp.war
There are no options for the copyright subcommand.
The following is an example of the copyright subcommand format:
packager.bat copyright
The following is an example of the copyright subcommand:
packager.bat copyright
There are no options, but the help subcommand accepts a topic attribute of a specific subcommand name for which detailed information is displayed.
The following is an example of the help subcommand format:
packager.bat help subcommand topic
The following is an example of the help subcommand:
packager.bat help validate
Use the ROMizer tool to create a ROM image used in building a custom Java Card runtime environment ( cjcre.exe ). See Chapter 13 for detailed information about the ROMizer tool.
Use the following command format to run the ROMizer tool:
romizer.bat [ options ] api jar file path
Options that can be used in the romizer.bat command include:
Optional. Output file name. Default is ROMJava.c
Optional. File where the initial EEPROM image is stored. Default is cjcre.eeprom.
Optional. The file contains a list of applications in separate lines.
The format of each line in the apps-list-file is:
application-file -t type-of-application -s signature-file -n name
In the previous format example, the following parameters are used:
romizer.bat --out MyROMJava.c --e2pfile my.eeprom yourapi.jar
romizer.bat ..ıib\api_connected.jar
romizer.bat yourapi.jar
romizer.bat -a myapps.list yourapi.jar
In the example, the contents of myapps.list might be in the form of:
helloworld1.war -t web -s helloworld1.signature -n hello1
helloworld2.eap -t extended-applet -s helloworld2.signature -n hello2
| Development Kit User's Guide | May 2009 | |
Copyright © 2009 Sun Microsystems, Inc. All rights reserved.