Skip Headers
Oracle® Java Micro Edition Software Development Kit Developer's Guide
Release 3.3 for NetBeans on Windows
  Go To Table Of Contents
Go To Index


13 Command Line Reference

This topic describes how to operate the Oracle Java ME SDK from the command line and details the command line tools required to build and run an application.

13.1 Run the Device Manager

The device manager is a component that runs as a service. It detects devices (real or emulated) that conform to the Unified Emulator Interface Specification (, version 1.0.2. The Device Manager automatically restarts every time you use the SDK. You can manually launch the device manager from a script or a command line.


To see a log of activities, launch the device manager with the -XenableOutput option.

13.2 Manage Device Addresses (device-address)

installdir\bin\device-address is a tool for viewing, adding, and removing devices that the SDK is not able to discover automatically. The Microsoft device emulator is an example of such a device. The syntax is:

Table 13-1 Device Address Commands

Command Action

add address_type address

Add the specified address.

del address_type address

Delete the specified address.


List all addresses.

list address_type

List the addresses of the specified type.

For example, the following command adds a device:

installdir\bin\device-address.exe add ip

13.3 Emulator Command Line Options

You can launch the emulator independent of the GUI using bin\emulator. The syntax is as follows:

emulator options

The general options are as follows:

Table 13-2 Emulator Commands

Command Action

-classpath path

-cp path

Specifies a search path for application classes. The path consists of directories, ZIP files, and JAR files separated by semicolons.

-D property=value

Sets a system property value.


Display a list of valid options.


Display version information about the emulator.


Run an application on the emulator using the given device instance name.


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

This is a simple example of running the emulator from the command line:

emulator.exe -Xdescriptor:C:\Java_ME_platform_SDK_3.3\apps\Games\dist\Games.jad -Xdevice:JavaMEPhone2

13.3.1 MIDlet Options

Options for running MIDlets in the emulator are as follows:

  • -Xautotest:JAD-file-URL

    Run in autotest mode. This option installs a MIDlet suite from a URL, runs it, removes it, and repeats the process. The purpose is to run test compatibility kits (TCKs) with the emulator, using a test harness such as JT Harness or Java Device Test Suite (JDTS).

    For example:

    emulator -Xautotest:http://localhost:8080/test/getNextApp.jad

    Given the above command, -Xautotest causes the emulator to repeatedly install, run, and remove the first MIDlet from the MIDlet suite provided through the HTTP URL. When the emulator starts, it queries the test harness, which then downloads and installs the TCK MIDletAgent.

  • -Xdescriptor:jad-file

    Install a MIDlet, run it, and uninstall it after it finishes.

  • -Xdomain:domain-name

    Set the MIDlet suite's security domain.

The Xjam argument runs an application remotely using the Application Management Software (AMS) to run over-the-air (OTA) provisioning. If no application is specified with the argument, the graphical AMS is run.

  • -Xjam[:install=<JAD-file-url> |force|list|storageNames| run=[<storageNames>|<StorageNumber>]|remove=[<storage name>|<storage number> | all]]

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

    • force. If an existing application has the same storage name as the application to be installed, force removes the existing application before installing the new application.

    • list. List all the applications installed on the device and exit. The list is written to standard output before the emulator exits.

    • storageNames. List all applications installed on the device. The list is written to standard output before the emulator exits. Each line contains one storage name in numerical order. The list contains only the name so the order is important. For example the first storage name must be storage number 1.

  • -Xjam:run=[<storage-name> | <storage-number>]

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

  • -Xjam:remove=[<storage-name> | <storage-number> | all]

    Remove a previously installed application. The application is identified by its valid storage name or storage number. If all is supplied, all previously installed applications are removed.

  • -Xjam:transient=jad-file-url

    If specified, transient is an alias for installing, running, and removing the application with the specified JAD file.

  • -Xprofile[:system=<y/n>, file=file]

    Profile the application's CPU usage.

    • system. Whether to profile system classes. Default value is n (only user classes are profiled).

    • file. CPU profiler snapshot is stored to the specified file, %d in file name is replaced by snapshot number. If not specified, profiler data is not stored to a file, it is passed to a connected profiler if one is present.

This example illustrates OTA installation:

emulator -Xjam:install=

The above command returns the ID of the installed application. When you obtain the ID you can run it with: emulator=Xjam:run=ID

See "Emulator Command Line Options" and "Debugging and Tracing Options."

13.3.2 CDC Options

The following options apply to CDC projects.

  • -Xmain:main-class-name

    Run the main method of a Java class, as in Java SE.

  • -Xxlet:classpath=class-path, class=fully-qualified-name,[arg=argument]*

    Run an Xlet application.

See "Emulator Command Line Options" and "Debugging and Tracing Options."

13.3.3 Debugging and Tracing Options

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

  • -Xdebug

    Enable runtime debugging. The -Xrunjdwp option must be called to support -Xdebug.

  • -Xrunjdwp:debug-settings

    Start a Java debug wire protocol session, as specified by a list of comma-separated debug settings. Both -Xrunjdwp and -Xdebug must be called.

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

    • suspend={y|n} - The possible values are y and n.

      When suspend is set to n, the application starts immediately and the debugger can be attached at any time during its run.

      When suspend is set to y, the application does not start until a debugger attaches to the debugging port and sends a resume command, so an application can be debugged from the very beginning.

This example shows debugging:

emulator.exe -Xdevice:JavaMEPhone1 -Xdebug -Xrunjdwp:transport=dt_socket,suspend=n, server=y,address=51307 -Xdescriptor:..\apps\Games\dist\Games.jad -Xdomain:maximum

With the emulator running you can attach a debugger.

  • To attach a graphical debugger from NetBeans, select Debug > Attach Debugger.

  • A sample command would be:

    jdk/bin/jdb -connect com.sun.jdi.SocketAttach:hostname=localhost,port=51307

13.3.4 Command Line Profiling

To add profiling to an emulator session, use:


For example:

emulator.exe -Xdevice:JavaMEPhone1 
-Xdescriptor:"C:\username\My Documents\NetBeansProjects\Games\dist\Games.jad" -Xprofile:file=C:\temp\

When you launch the emulator and profile an application from the command line the data profile you save has a different format than .nps files created with the Profile option in the NetBeans IDE.

Files created from the command line should be given the extension .prof to distinguish them from IDE profiler files.

To view .prof files in the IDE, select Profile > Java ME > Import CPU Profiler Snapshot.... Your file is displayed in a tab labeled with the name of the file containing the snapshot.

When the file is loaded in the IDE you can export the data in .nps form, using the Export to... feature as described in "Collecting and Saving Profiler Data in the IDE," Step 5. These files can be loaded using Profile > Java ME > Import CPU Profiler Snapshot....

13.4 Build a Project from the Command Line

In the user interface, building a project is a single step. Behind the scenes, however, there are 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 VM. See the following topics:

13.4.1 Check Prerequisites

Before building and running an application from the command line, verify that the jar command is in your path. To find the version of the development kit, run java -version at the command line.

13.4.2 Compile Class Files

Use the javac compiler from the Java SE development kit to compile Java source files. You can use the existing Oracle Java ME SDK project directory structure. Use the -bootclasspath option to tell the compiler to use the MIDP APIs, and use the -d option to tell the compiler where to put the compiled class files.

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

javac -target 1.3 -source 1.3 
   -bootclasspath ..\..\lib\cldc_10.jar;..\..\lib\midp2.1.jar
   -d tmpclasses

For more information on javac, consult the Java SE documentation.

13.4.3 Preverify Class Files

The next step is to preverify the class files. The bin directory of the Oracle Java ME SDK includes the preverify utility. The syntax for the preverify command is as follows:

preverify files | directories

Some of the options are as follows:

Table 13-3 Options to preverify Command

Name Description

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

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

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.

13.5 Packaging a MIDlet Suite (JAR and JAD)

To package a MIDlet suite manually you must create a manifest file, an application JAR file, and finally, a MIDlet descriptor (also known as a Java Application Descriptor or JAD).

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. For example, a manifest might have the following contents:

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

Create a JAR file containing the manifest and the suite's classes 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:

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.


You must 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

13.6 Command Line Security Features

The full spectrum of the Oracle Java ME SDK'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.

13.6.1 Change the Default Protection Domain

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


Assigns a security domain to the MIDlet suite. Enter an appropriate security domain as described in "Security Domains." For example, -Xdomain:maximum.

13.6.2 Sign MIDlet Suites (jadtool)

jadtool is a command-line interface for signing MIDlet suites using public key cryptography according to the MIDP 2.1 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 installdir\bin, and enter the following command:

jadtool command

The commands are as follows:

  • -help

    Prints the usage instructions for jadtool.

  • -addcert -alias key alias[-storepass password] [-keystore keystore] [-certnum number] [-chainnum number] [-encoding encoding] -inputjad filename -outputjad filename

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

  • -addjarsig [-jarfile filename] -keypass password -alias key alias -storepass password] [-keystore keystore] [-chainnum number] [-encoding encoding] -inputjad filename -outputjad filename

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

  • -showcert [<[-certnum number] [-chainnum number]> |[-all]] [-encoding encoding] -inputjad filename

    Displays information about certificates in JAD files.

The default values are as follows:

  • -encoding - UTF-8

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

  • -keystore - $HOME\.keystore

  • -certnum - 1

  • -chainnum - 1

13.6.3 Manage Certificates (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 purpose of the keys is 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 (found in the \bin directory for your JDK).

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

installdir\bin\mekeytool.exe -command

The command keywords follow.

The Oracle Java ME SDK contains a default ME keystore named _main.ks, which is located in:


This keystore includes all the certificates that exist in the default Java SE platform keystore that comes with the Java SE installation.

Also, each emulator instance has its own _main.ks file located in username\javame-sdk\3.3\work\devicename\appdb. If you do not specify a value for MEkeystore, a new key is added to the default ME key for this emulator instance.

If you do not specify a value for -keystore, the default keystore is used:


  • -help

    Prints the usage instructions for MEKeyTool.

  • -import -alias alias [-keystore JCEkeystore][-MEkeystore filename] [-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. and the default Java Cryptography Extension keystore is username\.keystore.

  • -list [-MEkeystore filename]

    Lists the keys in the ME keystore, including the owner and validity period for each.

  • -delete (-owner owner | -number key-number)[-MEkeystore filename]

    Deletes a key from the given ME keystore with the given owner.

13.7 Generate Stubs (wscompile)

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, that 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 13-4 lists the wscompile options:

Table 13-4 wscompile Options

Option Description


Same as -gen:client


Generates client artifacts (stubs, etc.)


Generates interfaces and value types only

-d output directory

Specifies where to place generated output files


Enables the given features


Generates debugging info


Same as -f:features


Specifies a HTTP proxy server (port defaults to 8080)

-model file

Writes the internal model to the given file


Optimizes generated code

-s directory

Specifies where to place generated source files


Outputs messages about what the compiler is doing


Prints version information


Sets the CLDC version to 1.0 (default). Float and double become String.


Sets the CLDC version to 1.1 (float and double are OK)


Shows all CLDC 1.0 information and warning messages.


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

Table 13-5 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 is used with a particular feature.

Table 13-5 Command Supported Features (-f) for wscompile

Option Description Type of File


Turns on explicit service context mapping



Turns off data binding for literal encoding



Turns off encoding type information

WSDL, SEI, model


Turns off support for multiple references

WSDL, SEI, model


Turns off full validation of imported WSDL documents



Searches schema aggressively for subtypes



Turns on direct serialization of interface types

WSDL, SEI, model


Enables WSI-Basic Profile features (default)



Resolves xsd:IDREF



No unwrap.



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