Starting the Java Card Runtime Environment
Description: This document describes how to use the development kit for the Java Card 3 Platform, Connected Edition, Version 3.0.2, to develop applet applications, web applications, servlets, and extended applets
Date: December 2009

C H A P T E R 5

Starting the Java Card Runtime Environment

The Connected Edition reference implementation is written in the Java and C programming languages and is called the C Java Card Runtime Environment (Java Card runtime environment). It is a simulator that can be built with a pre-built ROM mask, much as a Java Card technology-based implementation. It has the ability to simulate persistent memory (EEPROM) as well as to save and restore the contents of EEPROM to and from disk files. The Java Card runtime environment performs I/O via a socket interface, simulating the interaction with a card reader or host machine implementing HTTP(S) communication with the card reader or host machine.

The Java Card runtime environment is supplied by the development kit as the pre-built executable, `cjcre.exe`. The executable, `cjcre.exe`, is run from the command line.

This chapter includes the following sections:

- Starting cjcre.exe from the Command Line

- Java Card Runtime Environment Configuration Files

- Adding Proprietary Packages

##

Starting `cjcre.exe` from the Command Line

The Java Card runtime environment can be run from the command line by using the following command and options:

JC_CONNECTED_HOME`\bin\cjcre.exe` [options]

### `cjcre.exe` Command Line Options

The following command line options are listed in order of their expected frequency of use (most frequently used to less frequently used):

- `-config` config file

Sets a new configuration file. The default is `lib\config.properties.`

- `-contactedport` portnumber

Sets the port used to simulate the contacted interface for APDU. The default value for `-contactedport` is 9025.

- `-contactedprotocol` protocol

Sets the APDU protocol on this port, either `T=0` or `T=1`. The default value for the `-contactedprotocol` is `T=1`.

- `-contactlessport` port-number

Port number used to simulate contactless interface. Default is 9026. The protocol, T=CL, cannot be changed.

- -`corsize` size

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`).

- `-D`name=value

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.

- `-debug <yes|true|no|false>`

Runs `cjcre` in debug mode if you specify `yes` or `true`. Otherwise, the default is `no` and `cjcre` will not be run in debug mode. The values `yes` and `true` are equivalent. The values `no` and `false` are equivalent.

- `-debugport` portnumber

Sets the debug port where the Debug proxy communicates. Valid only when -`debug` is set to `yes`. The default value for `-debugport` is 7019.

- `-e2pfile` filename

Supplies the file name in which the EEPROM image is stored.

- `-e2psize` size

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`.

- `-enableassertions`

Enables Java code assertions (the assert keyword in Java code).

- `-exactlogger`

Displays only the log messages that match the level set by the `-loggerlevel` option.

- `-help` [`copyright`]

Prints help and copyright messages.

- `-httpport` portnumber

Sets the HTTP port number on which `cjcre` will be listening. The default value for `-httpport` is 8019.

- `-loggerlevel` <`none|fatal|error|warn|info|verbose|debug|all`>

Sets the type of log messages output. All log messages up to the specified level are displayed.

- `-ramsize` size

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`.

- `-resume`

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. However, the debug related options (`-debug`, `-debug`port, and `-suspend`) must be specified along with `-resume` to resume the VM in debug mode. The range is 256 bytes to 8K.

- `-suspend <yes|true|no|false>`

Suspends the threads at `cjcre` startup if set to `yes` or `true`. The default is `yes`. The values `yes` and `true` are equivalent. However, `yes` and `true` are valid only when `-debug` is also set to `yes` or `true`. The values `no` and `false` are equivalent.

- `-version`

Displays version information.

- `-X`name=value

Sets a single configuration property such as:
`-Xmyproperty=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. These are visible using `JCRuntime.getConfigProperty()`.

##

Java Card Runtime Environment Configuration Files

If you installed the development kit source bundle, the configuration files for the Java Card runtime environment (`config.properties` and `system.config)` files are located in the `lib` folder. These configuration files contain internal configuration information that must not be changed unless specified. Java Card runtime environment execution requires properly configured `config.properties` and `system.config` files. Incorrect changes to these files will prevent execution of the Java Card runtime environment. See Chapter 12 for details on configuring the Java Card runtime environment.

If you installed the development kit binary bundle, you cannot change the configuration files for the Java Card runtime environment.

##

Adding Proprietary Packages

If you installed the development kit source bundle, you can add proprietary packages to the ROM mask for the Java Card runtime environment by building a custom `cjcre.exe`. See Chapter 13 for additional information and procedures.

If you installed the development kit binary bundle, you cannot add proprietary packages.

Copyright © 2009 Sun Microsystems, Inc. All rights reserved.