A P P E N D I X B

Command Line Reference

This appendix describes how to operate the Sun Java^TM Wireless Toolkit for CLDC from the command line and details the steps required to build and run an application. It also describes the Sun Java^TM Wireless Toolkit for CLDC certificate manager utility, called MEKeyTool, and the MIDlet signing utility, called JadTool (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 Java SE software development kit. Make sure the jar command is in your path. To find the version of the development kit, run the jar command and then run java -version at the command line.

For more examples, see the files build.bat and run.bat in the bin directories of the demonstration applications. You can find these files in:

Windows:	toolkit`\apps\`demo`\bin`
Linux:	toolkit`/apps/`demo`/bin`

toolkit is the installation directory of the Sun Java^TM Wireless Toolkit for CLDC 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. This section describes how to accomplish each of the steps in the development cycle from the command line.

B.2.1 Build

In the user interface, 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 Java SE development kit to compile Java source files. You can use the existing Sun Java^TM Wireless Toolkit for CLDC 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.

Windows

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

Linux

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 Java SE documentation.

The next step is to preverify the class files. In the bin directory of the Sun Java^TM Wireless Toolkit for CLDC 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 target directory for the 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 are added for clarity.

Windows

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

Linux

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 file, 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 Java SE software development kit. The syntax is as follows:

jar cfm file manifest -C class-directory . -C resource-directory .

The arguments are as follows:

file - JAR file to create.

manifest - Manifest file for the MIDlets.

class-directory - Directory containing the application's classes.

resource-directory - 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 Sun Java^TM Wireless Toolkit for CLDC's bin directory contains the command emulator. The syntax for the emulator command is as follows:

emulator options

The general options are as follows:

-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 as follows:

-Xdevice:skin-name - Run an application on the emulator using the given skin name. For a list of skin names, see Section 4.1, Emulator Skins.

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

-Dcom.sun.midp.io.http.proxy - Set the HTTP and HTTPS proxy servers at run time. For example:

-Dcom.sun.midp.io.http.proxy=proxy-host:proxy-port

-Dcom.sun.midp.midlet.platformRequestCommand - Specify the browser to use when applications call a URL. For example:

-Dcom.sun.midp.midlet.platformRequestCommand=browser

A sample call might look like:

emulator -Dcom.sun.midp.midlet.platformRequestCommand=firefox -Xjam:install=URL-to-app-using-platformRequest-method

If you want to use the same browser every time, you can add the following line to toolkit/lib/system.config:

com.sun.midp.midlet.platformRequestCommand: browser

Windows: In Windows, if this parameter is not specified, the default browser is used.

Linux: For Linux, this parameter is required because Linux systems do not usually have a default browser. If it is missing, nothing happens when an application tries to open a URL.

-Xjam:command=application - Run an application remotely using the Application Management Software (AMS) to run using OTA provisioning. If no application is specified with the argument, the graphical AMS is run. The commands are as follows:

install=jad-file-url | force | list | storageNames|

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

Also

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, as follows:

gc - Trace garbage collection

class - Trace class loading

all - Use all tracing options

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

-Xrunjdwp:debug-settings - Start a Java debug wire protocol session, as specified by a list of comma-separated debug settings. The -Xdebug option must also be used. Valid debug settings include the following:

transport=transport-mechanism - Transport mechanism used to communicate with the debugger. The only transport mechanism supported is dt_socket.

address=host:port - 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} - Starts 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 Sun Java^TM Wireless Toolkit for CLDC can all be launched from the command line. Each component is in the toolkit's bin directory.

TABLE B-1 Toolkit Component Commands
Command	Description
`DefaultDevice`	Displays a dialog that allows you to choose the default emulator skin
`ktoolbar`	Launches the user interface.
`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

Provide a filename that is the full path name of a property file whose values override the values in the preferences dialog box. The property file can contain the properties described in the following table.

TABLE B-2 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 Sun Java^TM Wireless Toolkit for CLDC'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 is also capable of signing payment update (JPP) files.

JadTool only uses certificates and keys from Java SE platform keystores. Java SE software provides keytool, the command-line tool to manage Java SE platform 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

Prints the usage instructions for JADTool.

-addcert -alias alias [-keystore keystore] [-storepass password] [-certnum number] [-chainnum number] [-encoding encoding] -inputjad | inputjpp input-file -outputjad | outputjpp output-file

Adds the certificate of the key pair from the given keystore to the JAD file or JPP file.

-addjarsig -jarfile jarfile -keystore keystore -alias alias -storepass password -keypass password -inputjad input-jadfile -outputjad output-jadfile

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

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

Displays the list of certificates in the given JAD file.

-addjppsig -alias alias -keypass password [-keystore keystore] [-storepass password] [-encoding encoding] -inputjpp filename -outputjpp filename

Adds a digital signature of the input JPP file to the specified output JPP file.

The default value are as follows:

-encoding - UTF-8

-jarfile - MIDlet-Jar-URL property in the JAD file

-keystore - %HOMEPATH%\.keystore

-certnum - 1

-chainnum - 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 Java SE 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 keystore. You can create one using the Java SE keytool utility.

Windows

http://java.sun.com/javase/6/docs/technotes/tools /windows/keytool.html

Linux

http://java.sun.com/javase/6/docs/technotes/tools /solaris/keytool.html

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

Windows:	toolkit`\bin\mekeytool.exe -`command
Linux:	toolkit`/bin/mekeytool -`command

The command keywords follow. Note that while MEKeyTool runs from the installation directory, the default keys and keys you create will reside in your personal directory, workdir\appdb.

-help

Prints the usage instructions for MEKeyTool.

-import -alias alias [-keystore JCEkeystore] [-storepass storepass] -domaindomain-name

Imports a public key into the ME keystore from the given JCE keystore using the given Java Cryptography Extension keystore password. The default ME keystore is workdir\appdb\_main.mks and the default Java Cryptography Extension keystore is user.home\.keystore.

-list

Lists the keys in the ME keystore, including the owner and validity period for each. The ME keystore is workdir\appdb\_main.mks.

-delete (-owner owner | -number key-number)

Deletes a key from the given ME keystore with the given owner. The ME keystore is workdir\appdb\_main.mks.

Note - The Sun Java^TM Wireless Toolkit for CLDC contains an ME keystore called _main.mks, which is located in the appdb subdirectory. This keystore includes all the certificates that exist in the default Java SE platform keystore, which comes with the Java SE SDK installation.

B.6 Using the Stub Generator

Mobile clients can use the Stub Generator to access web services. The wscompile tool generates stubs, ties, serializers, and WSDL files used in Java API for XML (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 B-3 Options for the `wscompile` Command
Option	Description
`-d` output directory	Specifies where to place generated output files
`-f:`features	Enables the given features
`-features:`features	Same as `-f:`features
`-g`	Generates debugging info
`-gen`	Same as `-gen:client`
`-gen:client`	Generates client artifacts (stubs, etc.)
`-httpproxy:`host:port	Specifies a HTTP proxy server (port defaults to 8080)
`-import`	Generates interfaces and value types only
`-model` file	Writes the internal model to the given file
`-O`	Optimizes generated code
`-s` directory	Specifies where to place generated source files
`-verbose`	Outputs messages about what the compiler is doing
`-version`	Prints version information
`-cldc1.0`	Sets the CLDC version to 1.0 (default). Float and double become String.
`-cldc1.1`	Sets the CLDC version to 1.1 (float and double are OK)
`-cldc1.0info`	Shows all CLDC 1.0 information and warning messages.

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

TABLE B-4 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 B-4 Command Supported Features ( `-f` ) for `wscompile`
Option	Description	Type of File
`explicitcontext`	Turns on explicit service context mapping	WSDL
`nodatabinding`	Turns off data binding for literal encoding	WSDL
`noencodedtypes`	Turns off encoding type information	WSDL, SEI, model
`nomultirefs`	Turns off support for multiple references	WSDL, SEI, model
`novalidation`	Turns off full validation of imported WSDL documents	WSDL
`searchschema`	Searches schema aggressively for subtypes	WSDL
`serializeinterfaces`	Turns on direct serialization of interface types	WSDL, SEI, model
`wsi`	Enables WSI-Basic Profile features (default)
`resolveidref`	Resolves `xsd:IDREF`
`nounwrap`	No unwrap.

Example

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