Creating and Validating Application Modules
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 7

Creating and Validating Application Modules

This chapter describes creating and validating a Java Card technology-based application module with the Packager tool (Packager). See Chapter 3 to better understand the role and relationship between the Packager and the other development kit tools used in developing applications for the Java Card 3 platform.

This chapter contains the following sections:

- Packager Operation

- Running the Packager From the Command Line

##

Packager Operation

When creating an application module, the Packager takes a specified folder containing the files for the application module, validates the input files and creates the application module archive file. If a web application contains JAR files in the `lib` directory, the Packager creates a corresponding library module in the application module.

Each application module can have a descriptor as a part of the `MANIFEST.MF` file that specifies application module declarative items. In cases where an application module has a descriptor, the descriptor information must be validated and preserved.

### Options

The following are options of the Packager:

- Modules can be passed to the Packager as paths to directories containing the corresponding structure.

- Manifest files with information contained in an input module folder are preserved without change.

### Basic Packaging Sequence

The Packager creates an application module JAR file from input by performing the following actions:

1. Input files are extracted into a `temp` folder under a folder named either with the input file name or a name specified as a command line parameter.

2. Application module file types are checked and the application module type is determined.

3. A type entry is added to the application module.

4. The application module is placed under the `temp` folder.

If an optional keystore file is specified in the command line parameter, verified information from it is added to the resulting application module.

5. The entire contents are grouped together to create the final application module JAR file.

#### Use Cases

TABLE 7-1 provides a description of the possible Packager input files and corresponding output conditions.

TABLE 7-1 Packager Tool Input Files and Expected Output
Input | Expected Output
A valid JAR file | A valid application module JAR file
A malformated JAR file | Packager warns the user and exits
Files of the same type | A valid application module JAR file
Files of different types | Packager warns the user and exits
Files of the same type but the type contradicts the passed `--type` argument | Packager warns the user and exits

### Signing

The Packager can invoke the appropriate tools automatically to sign the application module JAR file. See create Subcommand. For information about creating a custom keystore that can be used to sign the application module JAR file, see Chapter 12. External signing tools can also be used to sign the modules if the user knows about those tools.

#### Use Cases

TABLE 7-2 provides a description of the possible Packager signing input and corresponding output conditions

TABLE 7-2 Packager Tool Signing Results
Input | Expected Output
Valid keystore passed | Application module JAR file is signed successfully
Invalid keystore passed or invalid keystore username or password | Packager warns the user and exits

##

Running the Packager From the Command Line

The command line interface for the Packager has the following syntax:

    packager.bat subcommand [options] module-or-folder

The following is a list of the available subcommands for the Packager:

- create Subcommand

- validate Subcommand

- copyright Subcommand

- help Subcommand

### `create` Subcommand

Creates the application module or library from a given module or folder.

#### `create` Subcommand Format

The following is an example of the `create` subcommand format:

    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] [--keepproxysource directory]
    --useproxyclass classpath [--nowarn] module-file-or-folder

#### `create` Subcommand Options

TABLE 7-3 identifies the `create` subcommand options and provides their descriptions.

TABLE 7-3 `create` Subcommand Options
Options | Description
--- | ---
`-A` alias or `--alias` alias | Application signing attribute, where alias is the name used to retrieve the key from the keystore.
`-c` or `--compress` | Optional. If specified, the tool compresses the output application module file with DEFLATE algorithm. Otherwise creates an uncompressed application module file.
`-`C command-options-file or `--`commandoptionsfile command-options-file | Optional. Specifies a file containing command line options.
-e path-of-export-files or `--exportpath` path-of-export-files | Specifies the export files path. System’s `api_export` files are implicitly loaded.
`-f` or `--force` | Optional. If specified, overwrite the output file. See --force Option Behavior.
    -k directory
or --keepproxysource directory | Optional. Cannot be used with `-useproxyclass`. Creates the proxy source files and other stub files in the specified directory.
`-K` keystore-file or `--keystore` keystore-file | Required only when the `--sign` option is specified. Application signing attribute, where keystore-file is the path and filename where the private keys are stored. A key utility (such as the JDK keytool) must be used to create and maintain this file. See Chapter 12, Creating a Custom Keystore.
-n or --nowarn | Suppresses the warning messages.
`-o` file-name or `--out` file-name | Specifies the output application module file where file-name is the name of the output file.
-P key-password or --passkey key-password | Application signing attribute, where key-password is the password for the private key.
-p package-AID-for-classic-lib or --packageaid package-AID-for-classic-lib | Specifies the package AID in //AID/<RID>/<PIX> format for `classic-lib`. Ignored if type is not classic-lib.
`-s` or `--sign` | Optional. 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.
`-S` keystore-password or `--storepass` keystore-password | Application signing attribute, where keystore-password is the password for the keystore.
`-t` file-type or `--type` file-type | Specifies the application module file type, where file-type can be `web`, `extended-applet`, `classic-applet`, `classic-lib`, or `extension-lib.` The default value is `web`.
-u classpath or --useproxyclass classpath | Specifies the user-supplied proxy classes (these proxy classes are not generated by Converter).

##### `--force` Option Behavior

The `--force` option causes the output file to be overwritten.

#### `create` Subcommand Examples

Two examples are provided, an example of the output option and an example of the signing option.

##### Output Option Example

The following is an example of the `create` subcommand with the output option:

    packager.bat create -o mymodule.jar -t web -c c:\mymodulefolder

In this command line example, the Packager performs the following tasks:

1. Extracts the contents of `mymodulefolder` directory to a temporary folder under the subdirectory `mymodulefolder`.

2. Creates corresponding Web Application Module object and performs validation and canonicalization of all xml descriptors.

3. Creates a `META-INF/MANIFEST.MF` file with required information (such as application name).

4. Compresses the contents of the temporary folder to `c:\temp\mymodule.jar`.

##### Signing Option Example

The following is an example of the `create` subcommand with the output option:

    packager.bat create -o mymodule.jar -t web --sign --keystore
    c:\mykeystore\c.keystore --storepass demo --keypass mykey
    --alias jckey -c c:\mymodulefolder

in addition to those tasks described in the previous example, the Packager in this command line example signs the application using the keystore from c:\mykeystore\c.keystore by performing the following:

- Provides the password (`demo`) for the `mykeystore` keystore.

- Provides the password (`mykey`) for the private `c.keystore` key.

- Provides the name (jckey) required to retrieve the key from the keystore.

### `validate` Subcommand

Validates an application module.

#### `validate` Subcommand Format

The following is the `validate` subcommand format:

    packager.bat validate [-e | --exportpath path-of-export-files]
    [--type type] [-x | --exportfile files-to-export]
    module-file-name | module-directory-name

#### `validate` Subcommand Options

The `validate` subcommand has the options described in TABLE 7-4.

TABLE 7-4 `validate` Subcommand Options
Options | Description
--- | ---
`-e` or `--exportpath` path-of-export-files`` | Specifies the path to use for the files to be exported.
module-file-name|module-directory-name | Specifies the module’s file or directory.
`-t` or `--type` | Specifies the type of application module or group to be validated. The type can be web, extended-applet, classic-applet, classic-lib, or extension-lib.
`-x` or `--exportfile` files-to-export | Specifies the files to use for the export.

#### `validate` Subcommand Example

The following is an example of the `validate` subcommand:

    packager.bat validate -t web myapp.war

In this command line example, the Packager performs the following tasks:

1. Extracts the contents of `myapp.war` application module to a temporary folder.

2. Validates the contents of the descriptors.

3. Validates that the classes specified in the descriptors actually exist in the application module.

4. Cross validates the descriptors.

5. Displays results of validation.

### `copyright` Subcommand

Displays the detailed copyright notice.

#### `copyright` Subcommand Format

The following is an example of the `copyright` subcommand format:

    packager.bat copyright

#### `copyright` Subcommand Options

There are no options for the `copyright` subcommand.

#### `copyright` Subcommand Example

The following is an example of the `copyright` subcommand:

    packager.bat copyright

### `help` Subcommand

Prints information about using subcommands.

#### `help` Subcommand Format

The following is an example of the `help` subcommand format:

    packager.bat help subcommand

#### `help` Subcommand Options

While there are no options for the `help` subcommand, it does accept a topic attribute consisting of a specific subcommand name for which detailed information is displayed.

#### `help` Subcommand Example

The following is an example of the `help` subcommand:

    packager.bat help validate

### Use Cases

TABLE 7-5 provides use cases for the command line arguments and describes the expected output for each.

TABLE 7-5 Use Cases for Command Line Arguments
Input | Expected Output
--- | ---
Valid arguments are passed for all specified types (`web`, `extended-applet`, `classic-applet`, `extension-lib, or classic-lib`), `-o` specified. | Valid application module of corresponding type is created.
Valid arguments are passed for all specified types (`web`, `extended-applet`, `classic-applet, extension-lib, or classic-lib`), `-o` not specified. | Packager performs xml validation. No application module is created.
The same name is specified for several application modules using the filename argument. | Error message and modules are renamed automatically.
`-f` is specified, descriptors contain unsupported tags. | Warns developer, cuts out unsupported tags.
`-s` is specified, valid signing related arguments passed. | Signs the resulting JAR file.

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