Tools Guide

Building an implementation of the Java Wireless Client software with the target all produces applications intended only for engineers who are porting Java Wireless Client to a new platform, or who are testing that port. The applications are unsupported. See the Build Guide for build instructions and the Porting Guide for porting instructions.

This chapter describes how to use the unsupported applications. It contains the following sections:

• Using the OTA Installer
• Running an Installed MIDlet
• Using the Native AMS
• Listing Installed MIDlet Suites
• Removing an Installed MIDlet Suite
• Emulating the Graphical AMS of a MIDP Phone

---

Using the OTA Installer

The graphical OTA installer is an installer used by end users. When an end user selects a link to a JAD or JAR file, the MIDlet-suite discovery application starts the installer. However, for developers and systems integrators, Java Wireless Client software provides a shell script, called installMidlet, that runs the OTA Installer MIDlet from the command line and bypasses the discovery application. The script is located in the installDir/midp/bin directory.

The following summarizes the command line for the installMidlet script:

installMidlet url [urlLabel]

• url

The HTTP or HTTPS URL of a JAD or a JAR file. The MIDlet suite is installed from this URL.

• urlLabel

Optional label for the URL. The installer displays the label in the progress form.

The Java Wireless Client software OTA Installer only uses the HTTP and HTTPS protocols to install MIDlet suites.

---

Running an Installed MIDlet

The example code that runs a MIDlet from an installed MIDlet suite is runMidlet. The runMidlet application is located in InstallDir/midp/bin directory. The application is compiled from the runMidlet.c file in the installDir/midp/src/ams/example/jams/native/targetPlatform directory. Note that when you build the Java Wireless Client software with debugging, the application's name is runMidlet_g.

The following summarizes the command line for the runMidlet application:

runMidlet [vmArgs] [-debug] [-loop] [-classpathext path] suiteID    [MIDletClassName [arg0 [arg1 [arg2]]]]

The runMidlet application takes the following arguments:

• vmArgs

Arguments that are recognized by the virtual machine (VM), such as
-DSystemPropertyName, -int, and -comp. See your Connected Limited Device Configuration (CLDC) documentation for more information.

• -debug

Starts the VM suspended in debug mode and waits for the debugger to connect. The internal system property VmDebuggerPort determines which port the VM uses to listen for debug commands.

• -loop

Runs the MIDlet in a loop until system shuts down.

• -classpathext path

Appends path to the classpath passed to the VM. The VM can then access classes from path as if they were ROMized.

• suiteID

A unique integer identifying the MIDlet suite and assigned to it when it was installed.

• MIDletClassName

The name of the MIDlet that the system runs in a loop until the system shuts down. If this argument is not provided and the suite has multiple MIDlets, runMidlet uses the first MIDlet from the suite.

• arg0 arg1 arg2

Arguments passed to the MIDlet.

Using runMidlet on a Windows/i386 Platform

Using runMidlet on a Windows/i386 platform differs from running on other platforms. Keep these following things in mind when using runMidlet:

• Start runMidlet from the directory InstallDir\build_output\midp\bin\platform.

build_output is the directory where you write the output from your Java Wireless Client software build process.

• To start the Application Manager, invoke runMidlet with no arguments. Do this instead of running usertest.
• You can also use runMidlet to install applications from URLs or files, to run tests, or perform other functions. For a brief description of the syntax and examples of runMidlet, use the help option:

$ runMidlet help 

• Use the tck option runMidlet instead of running autotest.
• Use the install option of runMidlet instead of installMidlet.

1. Change directory to InstallDir\build_output\midp\bin\platform.

In the above, platform is your Windows target platform, for example, i386.

2. Type runMidlet.exe manager

---

Using the Native AMS

The example code that runs a MIDlet from an installed MIDlet suite using the Native AMS API is runNams. To build this application, Java Wireless Client must be built with USE_NATIVE_AMS=true and USE_MULTIPLE_ISOLATES=true.

The CLDC HI software must be built with ENABLE_ISOLATES=true. runNams is compiled from the runNams.c file in the InstallDir/midp/src/ams/example/nams/native/share directory. When you build the Java Wireless Client software with debugging, the application's name is runNams_g.

The four options of runNams have the following syntax:

• runNams [vmArgs] -namsTestService
• runNams [vmArgs] -runMainClass mainClass [args]
• runNams [vmArgs] -runMidlet suiteID [MIDletClassName [args]]
• runNams [vmArgs] -jamsTestMode suiteID [MIDletClassName [args]]

vmArgs is the same as for runMidlet.

The options are as follows:

• -namsTestService runs the NAMS Test Service. To use this mode, you must change MIDP_DIR/src/ams/nams/lib.gmk in the following way: $(NAMS_DIR)/i3test/com/sun/midp/main/NamsTestService.java must be included instead of a stubbed out version of this file. Please refer to the comments in lib.gmk. For all other modes, the stubbed out version of this file must be included.

In this mode, runNams will listen on a socket (port 13322) for incoming connections and execute the given commands (it can create and start, destroy, pause, resume and switch a midlet to foreground).

• -runMainClass runs an alternate main class.
• -runMidlet runs a MIDlet using the NAMS API "regular" mode, allowing you to run a MIDlet in a non-AMS isolate.
• -jamsTestMode runs a MIDlet in the AMS isolate using the JAMS mode API. This mode should only be used to run the i3test framework and AutoTester. For executing other MIDlets, use -runMidlet.

The suiteID argument is exactly the same as for runMIDlet.

Listing Installed MIDlet Suites

When you use a native application management system (AMS), the listMidlets example code lists the installed MIDlets. This example code is not available for the Java platform AMS.

The listMidlets application is located in the InstallDir/midp/bin directory. The listMidlets application is compiled from the listMidlets.c file in the
InstallDir/midp/src/ams/example/nams/native/targetPlatform directory.

The listMidlets command takes no arguments:

$ listMidlets

When no MIDlet suites are installed, the example displays:

** No MIDlet Suites installed on phone

If MIDlet suites are installed, the listing displays the following information (the number in square brackets is the MIDlet suite number):

[1]

	Name: HelloMIDlet

	Vendor: HelloMIDlet

	Version: 1.0

	Description: (null)

	Security Domain: operator

	Verified: false

	Suite ID: 2

	JAD URL: http://host.sun.com/HelloMIDlet.jad

	JAR URL: http://host.sun.com/HelloMIDlet.jar

	Size: 2K

Removing an Installed MIDlet Suite

When you use a native AMS, use the removeMidlet application to remove an installed MIDlet suite. This example code is not available for the Java platform AMS.

The removeMidlet application is located in the InstallDir/midp/bin directory. The removeMidlet application is compiled from the removeMidlet.c file in the

InstallDir/midp/src/ams/example/nams/native/targetPlatform directory.

The following summarizes the command line for the removeMidlet application:

$ removeMidlet ( suiteID | all )

• suiteID

Unique integer given to the MIDlet suite when it was installed. Integers are displayed by the listMidlet example. See Using the Native AMS for information.

• all

Requests that all MIDlet suites be removed.

---

Using the Java Programming Language AMS

The following utilities for working with MIDlets are available only when building with the Java language AMS (that is, when setting the build flag USE_NATIVE_AMS=false):

• listMidlets.sh
• removeMidlet.sh

Listing an Installed MIDlet Suite

The listMidlets.sh application is located in the InstallDir/midp/bin directory. To list an installed MIDlet suite under the Java programming language AMS, type the command as shown below. There are no arguments to the listMidlets.sh command.

$ listMidlets.sh

This returns a list of currently installed Midlet suites.

Removing an Installed MIDlet Suite

The removeMidlet.sh application is located in the InstallDir/midp/bin directory. To remove a MIDlet suite under the Java programming language AMS, type the command as shown below.

$ removeMidlet.sh ( suiteID | all )

• suiteID

The unique integer assigned to a MIDlet suite when it was installed. It must be provided for a specific MIDlet suite to be removed.

• all

Requests that all MIDlet suites be removed.

---

Emulating the Graphical AMS of a MIDP Phone

Java Wireless Client software provides a graphical AMS that emulates the user interface on a MIDP phone. Use the usertest shell script located in the installDir/midp/bin directory to run the graphical application manager MIDlet. The usertest script takes no arguments. The following summarizes its command line:

$ usertest

The usertest script interacts differently with the standard logging service than the other executables described in this chapter. The default implementation of the logging and tracing utility prints log data to stdout. As a result, the other executables (such as autotest, described in Chapter 7) display log or trace output on the terminal in which you started them. Alternatively, you can pipe the output to a file, as you would for any application.

Tools Guide

05-2007

Copyright © 2007, Sun Microsystems, Inc. All rights reserved. SUN PROPRIETARY/CONFIDENTIAL.