Command Line Reference

C H A P T E R 4

The commands in this chapter are located in ToolkitHome\bin.

4.1 Emulator

The emulator simulates a device on your desktop computer. It is a convenient way to see how your application performs in a mobile environment and gives you a tight development cycle that is entirely contained on your desktop computer.

The emulator does not represent a specific device, but it provides correct implementations of its supported APIs.

You can run the emulator only from command line in the Prototype Release. The emulator executable is located at ToolkitHome\bin\emulator.exe.

4.1.1 Emulator Skin

A skin is a thin layer on top of the emulator implementation that provides it with a certain appearance, screen characteristics, and input controls. The Sun Java Wireless Toolkit for Sprint Titan Platform comes with skins that represent different kinds of devices.

TABLE 4-1 Emulator Skins
Name	Screen Size	Printable Area	Colors
DefaultColorPhone	240 x 320	240 x 320	4096
SunVGA	640 x 480	640 x 480	16,777,216

4.1.2 Emulator Controls

The DefaultColorPhone skin emulates a mobile phone inside a standard desktop window. You can use the mouse to click the buttons to press them, or you can use keyboard shortcuts. Keyboard keys 0 through 9 correspond to the emulator's 0 through 9 buttons. Other keyboard shortcuts are listed in the following table.

TABLE 4-2 Emulator Keys and Keyboard Equivalents
Emulator Button	Keyboard Key
Left soft button	F1
Right soft button	F2
Backspace button	Backspace
Select button	Enter
Arrow buttons	Arrow keys
Pound button (#)	Subtract key (-)
Asterisk button ()	Multiply key ()

4.1.3 Running the Emulator

To run the emulator type: emulator options

The general options are as follows are shown in TABLE 4-3.:

TABLE 4-3 General Options
`help`	Display a list of valid options.
`version`	Display version information about the emulator.
`Xquery`	Print device information on the standard output stream and exit immediately. The information includes the device name, screen size, and other capabilities.

TABLE 4-4 lists options that pertain to running MIDlet suites:

TABLE 4-4 Emulator Syntax
-Xdevice:device-name	Run an application on the given device.
-Xdescriptor:jad-file	Run an application locally using the given JAD file.
-Xjam:command=application	Run an application remotely using the Application Management Software (AMS) to run using over-the-air (OTA) provisioning. If no application is specified with the argument, the graphical AMS is run. The commands are as follows:
	install=jad-file-url
		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` removes all previously installed applications.
-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 device must act as a server).

Example

This example describes how to install an application on a device.

1. Run application remotely:

emulator -Xjam:install=http://server.com/yourMIDlet.jad

2. Check available devices:

emulator -Xquery

You see output beginning with:

# List of supported devices

device.list: DefaultColorPhone1, SunVga1

uei.version: 1.0.1

3. Select your desired device from device.list and add it to the emulator command.

emulator -Xdevice:SunVga1
-Xjam:install=http://server.com/yourMIDlet.jad

Your application is installed on the device you specified.

4.2 JadTool

JadTool is intended 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 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 ToolkitHome\bin, and enter the following command:

jadtool.exe command

The possible commands shown in TABLE 4-5:.

TABLE 4-5 JadTool Command Options
-help	Prints the usage instructions for JadTool.
-addcert -alias alias [-keystore keystore] [-storepass password] [-certnum number] [-chainnum number] [-encoding encoding] -inputjad input-file -outputjad output-file
	Adds the certificate of the key pair from the given keystore to the JAD 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.

The default values are shown in :

TABLE 4-6 JadTool Option Defaults
-encoding	UTF
-jarfile	`MIDlet-Jar-URL` property in the JAD file
-keystore	ToolkitHome`\appdb\keystore.ks`
-certnum	1
-chainnum	1

4.3 MEKeyTool

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.

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

mekeytool -command

TABLE 4-7 lists the command keywords.

TABLE 4-7 MEKeyTool Command Keywords
-help	Prints the usage instructions for MEKeyTool.
-import -alias alias [-keystore JCEkeystore] [-storepass storepass] -domain domain-name	Imports a public key into the ME keystore from the given JCE keystore using the given Java Cryptography Extension keystore password.
-list	Lists the keys in the ME keystore, including the owner and validity period foreach.
-delete (-owner owner \| -number key-number)	Deletes a key from the given ME keystore with the given owner.

4.4 Location Feed Tool

Location Feed tool is a command-line tool intended for simulating a geographical location of the emulator. Simulated location can be obtained via APIs provided by JSR177.

The tool supports the following sources of location data:

an XML file containing a list of coordinates.

a text file containing a log of NMEA GPS receiver

live data from NMEA GPS receiver (serial or bluetooth)

To run the tool, open a command prompt, change the current directory to ToolkitHome\bin, and type the following command:

location-feed.exe command

TABLE 4-8 lists the command keywords.

TABLE 4-8 Location Feed Tool Commands
xml [file]	feed location data with a fixed speed from XML file.
nmea-file [file]	feed location data with a fixed speed from text file containing NMEA location data.
serial-gps [port]	feed GPS receiver data from a serial port [port], for example, COM11. For a bluetooth GPS receiver supporting Serial Port Profile, it should be first mapped to the operating system's serial port.

4.5 WMA Tool

WMA tool is a command-line tool for sending and receiving SMS messages. It is possible to exchange SMS messages with the emulator and between two instances of WMA tool. To run the tool, open a command prompt, change the current directory to ToolkitHome\bin, and enter the following command:

wmatool.exe command

TABLE 4-9 list the command keywords.

TABLE 4-9 WMA Tool Commands
smsreceive	Receive the SMS message. The tool will display all received SMS messages.
smssend [target phone number] [target port] [message]
	Sends SMS message to the specified phone number and port.

4.6 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

TABLE 4-10 wscompile Options
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

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

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

TABLE 4-11 Feature Options
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 -d generated config.xml