13 Command Line Reference

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=http://www.myserver.com/apps/MyApp.jad
         -Xdevice:JavaMEPhone2

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:

-Xprofile:[system=<y|n>], file=filename.prof

For example:

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

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.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
   src\*.java

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:

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

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

13.6.1 Change the 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. 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:

installdir\runtimes\cldc-hi\appdb

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.4\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:

username\keystore.ks

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