## Appendix B

## Command Line Reference

This appendix describes how to operate the J2ME Wireless Toolkit from the command line and details the steps required to build and run an application. It also describes the J2ME Wireless Toolkit certificate manager utility, called MEKeyTool, and the MIDlet signing utility, called JAD Tool (Java Application Descriptor Tool).

## B.1 Prerequisites

Before building and running an application from the command line, verify that you have a version no earlier than 1.4.2 of the J2SE SDK. Run the `jar.exe` command (make sure the command is in your PATH) and then run `java -version` at the command line to verify that the version of the J2SE SDK that is actually being used is 1.4.2.

For more examples, see the files `build.bat` and `run.bat` in the `bin` directories of the demonstration applications. You can find these files under the
{toolkit}`\apps\<demo>\bin` directory where {toolkit} is the installation directory of the J2ME Wireless Toolkit and `<demo>` is the name of one of the demo applications.

## B.2 The Development Cycle

For a full description of developing MIDP applications, see Chapter 2, “Developing MIDlet Suites.” This section describes how to accomplish each of the steps in the development cycle from the command line.

### B.2.1 Build

Using KToolbar, building a project is a single step. Behind the scenes, however, there are actually two steps. First, Java source files are compiled into Java class files. Next, the class files are preverified, which means they are prepared for the CLDC KVM.

Use the `javac` compiler from the J2SE SDK to compile Java source files. You can use the existing J2ME Wireless Toolkit project directory structure. You’ll need to use the `-bootclasspath` option to tell the compiler to use the MIDP APIs, and you’ll use the `-d` option to tell the compiler where to put the compiled class files.

The following example shows how you could compile a MIDP 2.0 application, taking source files from the `src` directory and placing the class files in the `tmpclasses` directory. Newlines have been added for clarity.

    javac
      -bootclasspath ..\..\lib\cldcapi10.jar;..\..\lib\midpapi20.jar
      -d tmpclasses
      src\*.java

If you want to use the optional APIs that are supported by the toolkit, add their JAR files to the `-bootclasspath` option.

For more information on `javac`, consult the J2SE documentation.

The next step is to preverify the class files. In the `bin` directory of the J2ME Wireless Toolkit lives a handy utility called `preverify`. The syntax for the preverify command is as follows:

    preverify [options] <files | directories>

Some of the options are as follows:

`-classpath` <classpath>

Specify the directories or JAR files (given as a semicolon-delimited list) from which classes are loaded.

`-d` <output directory>

Specify the directory into which the preverifier should output classes. This directory must exist before preverifying. If this option is not used, the preverifier places the classes in a directory called output.

Following the example for compiling, use the following command to verify the compiled class files. As before, newlines have been added for clarity.

    preverify
      -classpath ..\..\lib\cldcapi10.jar;..\..\lib\midpapi20.jar
      -d classes
      tmpclasses

As a result of this command, preverified class files are placed in the `classes` directory. If your application uses WMA, MMAPI, or other versions of CLDC or MIDP, be sure to include the relevant `.jar` files in the classpath.

### B.2.2 Package

To package a MIDlet suite, you must create a manifest file, an application JAR, and finally, a MIDlet suite descriptor.

Create a manifest file containing the appropriate attributes as specified in the MIDP specification. You can use any text editor to create the manifest file. A manifest might have the following contents, for example:

    MIDlet-1: My MIDlet, MyMIDlet.png, MyMIDlet
    MIDlet-Name: MyMIDlet
    MIDlet-Vendor: My Organization
    MIDlet-Version: 1.0
    MicroEdition-Configuration: CLDC-1.0
    MicroEdition-Profile: MIDP-2.0

Create a JAR file containing the manifest as well as the suite’s class and resource files. To create the JAR file, use the `jar` tool that comes with the J2SE SDK. The syntax is as follows:

    jar cfm <file> <manifest> -C <class_directory> . -C <resource_directory> .

The arguments are as follows:

<file>: The JAR file to create.

<manifest>: The manifest file for the MIDlets.

<class_directory>: The directory containing the application’s classes.

<resource_directory>: The directory containing the application’s resources.

For example, to create a JAR file named `MyApp.jar` whose classes are in the `classes` directory and resources are in the `res` directory, use the following command:

    jar cfm MyApp.jar MANIFEST.MF -C classes . -C res .

Create a JAD file containing the appropriate attributes as specified in the MIDP specification. You can use any text editor to create the JAD file. This file must have the extension `.jad`.

Note – You need to set the `MIDlet-Jar-Size` entry to the size of the JAR file created in the previous step.

For example, a JAD file might have the following contents:

    MIDlet-Name: MyMIDlet
    MIDlet-Vendor: My Organization
    MIDlet-Version: 1.0
    MIDlet-Jar-URL: MyApp.jar
    MIDlet-Jar-Size: 24601

### B.2.3 Run

You can run the emulator from the command line. The J2ME Wireless Toolkit’s `bin` directory contains the command `emulator`. The syntax for the `emulator` command is as follows:

    emulator [options]

The general options are:

`-help`: Display a list of valid options.

`-version`: Display version information about the emulator.

`-Xquery`: Print emulator skin information on the standard output stream and exit immediately. The information includes the skin name, screen size, and other capabilities.

Options that pertain to running MIDlet suites are:

`-Xdevice:`<skin_name>: Run an application on the emulator using the given skin name. For a list of skin names, see Chapter 4, “Using the Emulator.”

`-Xdescriptor:`<jad_file>: Run an application locally using the given JAD file.

`-classpath` <classpath>: Specify the classpath for libraries required to run the application. Use this option when running an application locally.

`-D` <runtime_property>: Set the HTTP and HTTPS proxy servers. Valid properties include:

`com.sun.midp.io.http.proxy=<`proxy host`>:<`proxy port`>`

`-Xjam:<`command`>=<`application`>`: Run an application remotely using the Application Management System (AMS) to run using OTA provisioning. If no application is specified with the argument, the graphical AMS is run.

`install=<`jad_file_url`> | force | list | storageNames|`

Install the application with the specified JAD file onto a device.

`run=[<`storage_name`> | <`storage_number`>]`

Run a previously installed application. The application is specified by its valid storage name or storage number.

`remove=[<`storage_name`> | <`storage_number`> | all]`

Remove a previously installed application. The application is specified by its valid storage name or storage number. Specifying `all`, all previously installed applications are removed.

`transient=<`jad_file_url`>`

Install, run, and remove the application with the specified JAD file. Specifying `transient` causes the application to be installed and run and then removed three times.

### B.2.4 Debugging

You can use the following options with the emulator for debugging and tracing.

`-Xverbose:`<trace_options>

Display trace output, as specified by a list of comma-separated options:

`class` : trace class loading

`gc` : trace garbage collection

`all` : use all tracing options

`-Xdebug`

Enable runtime debugging. The `-Xrunjdwp` option must also be used.

`-Xrunjdwp:`<debug_settings>

Start a JDWP debug session, as specified by a list of comma-separated debug settings. The `-Xdebug` option must also be used. Valid debug settings include:

`transport=`<transport_mechanism>

The transport mechanism used to communicate with the debugger. The only transport mechanism supported is `dt_socket`.

`address=`<host:port>

The transport address for the debugger connection. You can omit providing a host. If host is omitted, localhost is assumed to be the host machine.

`server=`{y|n}

Start the debug agent as a server. The debugger must connect to the port specified. The possible values are `y` and `n`. Currently, only `y` is supported (the emulator must act as a server).

## B.3 Launching Toolkit GUI Components

The components of the J2ME Wireless Toolkit can all be launched from the command line. Each component is in the toolkit’s `bin` directory.

TABLE 12 – Toolkit component commands
Command | Description
--- | ---
`DefaultDevice` | Pops up a dialog that allows you to choose the default emulator skin
`ktoolbar` | Launches KToolbar
`prefs` | Launches the toolkit preferences
`utils` | Launches the toolkit utilities window

## B.4 Setting Emulator Preferences

You can change the emulator preferences from the command line by using the `-Xprefs` option for the `emulator` command. The format is as follows:

`-Xprefs:<`filename`>`

The filename you provide should be the full path name of a property file whose values override the values in the preferences dialog box. The property file can contain the following properties:

TABLE 13 – Emulator Preferences Properties List
Property Name | Property Description and Legal Values
--- | ---
`http.version` | Network Configuration > HTTP Version Value: HTTP/1.1 | HTTP/1.0
`http.proxyHost` | Network Configuration > HTTP Address Value: hostname
`http.proxyPort` | Network Configuration > HTTP Port Value: integer
`https.proxyHost` | Network Configuration > HTTPS Address Value: hostname
`https.proxyPort` | Network Configuration > HTTPS Port Value: integer
`kvem.memory.monitor.enable` | Monitor > Enable memory monitor Value: true | false
`kvem.netmon.comm.enable` | Monitor > Enable Comm monitoring Value: true | false
`kvem.netmon.datagram.enable` | Monitor > Enable Datagram monitoring Value: true | false
`kvem.netmon.http.enable` | Monitor > Enable HTTP monitoring Value: true | false
`kvem.netmon.https.enable` | Monitor > Enable HTTPS monitoring Value: true | false
`kvem.netmon.socket.enable` | Monitor > Enable Socket monitoring Value: true | false
`kvem.netmon.ssl.enable` | Monitor > Enable SSL monitoring Value: true | false
`kvem.profiler.enable` | Monitor > Enable profiling Value: true | false
`netspeed.bitpersecond` | Performance > bits/sec combo box Value: integer
`netspeed.enableSpeedEmulation` | Performance > Enable network throughput emulation Value: true | false
`screen.graphicsLatency` | Performance > Graphics primitives latency Value: integer
`screen.refresh.mode` | Performance > Display refresh (radio button) Value: default | immediate | periodic
`screen.refresh.rate` | Performance > Display refresh (slider) Value: integer
`vmspeed.bytecodespermilli` | Performance > Enable VM speed emulation (check box) Value: integer
`vmspeed.enableEmulation` | Performance > Enable VM speed emulation (slider) Value: true | false
`storage.root` | Storage > Storage root directory Value: String (relative path to appdb)
`storage.size` | Storage > Storage size Value: integer
`mm.control.capture` | MMedia > Audio Capture Value: true | false
`mm.control.midi` | MMedia > MIDI tones Value: true | false
`mm.control.mixing` | MMedia > Audio Mixing Value: true | false
`mm.control.record` | MMedia > Audio Record Value: true | false
`mm.control.volume` | Value: true | false
`mm.format.midi` | MMedia > MIDI format Value: true | false
`mm.format.video` | MMedia > Video format Value: true | false
`mm.format.wav` | MMedia > WAV Audio format Value: true | false
`wma.client.phoneNumber` | WMA > Phone Number of Next Emulator Value: integer
`wma.server.firstAssignedPhoneNumber` | WMA > First Assigned Phone Number Value: integer
`wma.server.percentFragmentLoss` | WMA > % Random Message Fragment Loss Value: integer
`wma.server.deliveryDelayMS` | WMA > Message Fragment Delivery Delay (ms) Value: integer

## B.5 Using Security Features

The full spectrum of the J2ME Wireless Toolkit’s security features are also available from the command line. You can adjust the emulator’s default protection domain, sign MIDlet suites, and manage certificates.

### B.5.1 Changing the Emulator’s Default Protection Domain

To adjust the emulator’s default protection domain, use the following option with the `emulator` command:

`-Xdomain <`domain_type`>`

Assigns a security domain to the MIDlet suite. Domain types include `untrusted`, `trusted`, `minimum`, and `maximum`.

### B.5.2 Signing MIDlet Suites

`JadTool` is a command-line interface for signing MIDlet suites using public key cryptography according to the MIDP 2.0 specification. Signing a MIDlet suite is the process of adding the signer certificates and the digital signature of the JAR file to a JAD file.

`JadTool` only uses certificates and keys from J2SE keystores. J2SE provides `keytool`, the command-line tool to manage J2SE keystores.

`JadTool` is packaged in a JAR file. To run it, open a command prompt, change the current directory to {toolkit}`\bin`, and enter the following command:

    java -jar JADTool.jar <command>

The commands are as follows:

`-help`

Print the usage instructions for JADTool.

`-addcert -keystore` <keystore> `-alias <`alias`> -storepass` <password>
`[-certnum` `<`number`>]` `[-chainnum` `<`number`>]` `-inputjad` <input_jadfile> `-outputjad` <output_jadfile>

Add the certificate of the key pair from the given keystore to the JAD file. The default keystore is {toolkit}`\appdb\_main.ks`.

`-addjarsig -jarfile` <jarfile> `-keystore` <keystore> `-alias` `<`alias`>` `-storepass` <password> `-keypass` <password> `-inputjad` <input_jadfile> `-outputjad` <output_jadfile>

Add the digital signature of the given JAR file to the specified JAD file. The default value for `-jarfile` is the `MIDlet-Jar-URL` property in the JAD file. The default ME keystore is {toolkit}`\appdb\_main.ks`.

`-showcert` `[([-certnum` `<`number`>]` `[-chainnum` `<`number`>])` `|-all` `[-encoding` `<`encoding`>]` `-inputjad` `<`filename`>`

Display the list of certificates in the given JAD file.

The default value for:

`-encoding` is `UTF-8`

`-jarfile` is the `MIDlet-Jar-URL` property in the JAD

`-keystore` is `%HOMEPATH%\.keystore`

`-certnum` is 1

`-chainnum` is 1

### B.5.3 Managing Certificates

`MEKeyTool` manages the public keys of certificate authorities (CAs), making it functionally similar to the `keytool` utility that comes with the J2SE SDK. The keys can be used to facilitate secure HTTP communication over SSL (HTTPS).

Before using `MEKeyTool`, you must first have access to a Java Cryptography Extension (JCE) keystore. You can create one using the J2SE `keytool` utility; see http://java.sun.com/j2se/1.4/docs/tooldocs/win32/keytool.html for more information.

To run `MEKeyTool`, open a command prompt, change the current directory to `{`toolkit`}\bin`, and enter the following command:

    mekeytool.exe <command>

The commands are as follows:

`-help`

Print the usage instructions for MEKeyTool.

`-import -alias <`alias`> [-keystore <`JCEkeystore`>] [-storepass <`storepass`>] -domain <`domain_name`>`

Import a public key into the ME keystore from the given JCE keystore using the given JCE keystore password. The default ME keystore is {toolkit}`\appdb\_main.ks` and the default JCE keystore is {user.home}`\.keystore`.

`-list`

List the keys in the ME keystore, including the owner and validity period for each. The ME keystore is {toolkit}`\appdb\_main.ks`.

`-delete (-owner <owner> | -number <key number>)`

Delete a key from the given ME keystore with the given owner. The ME keystore is {toolkit}`\appdb\_main.ks`.

Note – The J2ME Wireless Toolkit contains an ME keystore called `_main.ks,` which is located in the `appdb` subdirectory. This keystore includes all the certificates that exist in the default J2SE keystore, which comes with the J2SE SDK installation.

## B.6 Using the Stub Generator

J2ME Clients can use the Stub Generator to access web services. The wscompile tool generates stubs, ties, serializers, and WSDL files used in JAX-RPC clients and services. The tool reads a configuration file, which specifies either a WSDL file, a model file, or a compiled service endpoint interface.

The syntax for the stub generator command is as follows:

    wscompile [options] configuration_files

### B.6.1 Options

TABLE 14 – Options for the wscompile Command
Option | Description
--- | ---
`-d` <output directory> | specify where to place generated output files
`-f:`<features> | enable the given features
`-features:`<features> | same as`-f:`<features>
`-g` | generate debugging info
`-gen` | same as `-gen:client`
`-gen:client` | generate client artifacts (stubs, etc.)
`-httpproxy:`<host>:<port> | specify a HTTP proxy server (port defaults to 8080)
`-import` | generate interfaces and value types only
`-model` <file> | write the internal model to the given file
`-O` | optimize generated code
`-s` <directory> | specify where to place generated source files
`-verbose` | output messages about what the compiler is doing
`-version` | print version information
`-cldc1.0` | Set the CLDC version to 1.0 (default) (float and double become String)
`-cldc1.1` | Set the CLDC version to 1.1 (float and double are ok)
`-cldc1.0info` | Show all CLDC 1.0 info/warning messages.

Note – Exactly one `-gen` option must be specified. The `-f` option requires a comma-separated list of features.

TABLE 15 lists the features (delimited by commas) that can follow the `-f` option. The wscompile tool reads a WSDL file, compiled service endpoint interface (SEI), or model file as input. The Type of File column indicates which of these files can be used with a particular feature.

TABLE 15 – Command Supported Features (-f) for wscompile
Option | Description | Type of File
--- | --- | ---
`explicitcontext` | turn on explicit service context mapping | WSDL
`nodatabinding` | turn off data binding for literal encoding | WSDL
`noencodedtypes` | turn off encoding type information | WSDL, SEI, model
`nomultirefs` | turn off support for multiple references | WSDL, SEI, model
`novalidation` | turn off full validation of imported WSDL documents | WSDL
`searchschema` | search schema aggressively for subtypes | WSDL
`serializeinterfaces` | turn on direct serialization of interface types | WSDL, SEI, model
`wsi` | enable WSI-Basic Profile features (default) |
`resolveidref` | Resolve `xsd:IDREF` |
`nounwrap` | No unwrap. |

    wscompile -gen -d generated config.xml

wscompile -gen -f:nounwrap -O -cldc1.1 -d generated config.xml

| J2ME Wireless Toolkit User's Guide J2ME Wireless Toolkit 2.2

Copyright © 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to the license terms.