The midp Command

midp — device emulator and Java™ programming language interpreter for the Mobile Information Device Profile (MIDP).

Synopsis

Description

The midp command runs a device emulator and executes bytecodes that have been created by the compiler, javac, and preverified by the preverify utility. The midp_g command is a version of the midp command built with debug capabilities. Unless otherwise noted, running the midp or midp_g command displays a device skin.

MIDP is part of the Java 2 Platform, Micro Edition (J2ME™). MIDP was initially defined in the Mobile Information Device Profile for the J2ME Platform [JSR-000037], and refined in the Mobile Information Device Next Generation [JSR-000118]. For more information on the JSRs, see http://www.jcp.org/jsr/tech/j2me.jsp

Applications that the midp command runs are called MIDlets. When one or more MIDlets are packaged as a unit for download onto a device, the bundle is called a MIDlet suite. The midp command can run MIDlets and MIDlet suites.

In addition to running MIDlets and MIDlet suites, the midp command manages MIDlet suites. It can download and install them on the emulator, list the MIDlet suites installed on the emulator, remove a MIDlet suite from the emulator, and so on.

The behavior of the emulator during MIDlet execution is controlled by configuration files:

Where midpInstallDir is the directory where MIDP is installed. The files are property files that use a colon to separate the property name from its value:

TABLE 2 Properties in the `internal.config` File
Property Name	Type	Default Value	Description
system.jam_space	integer	4194304	Amount of space to reserve for MIDlet Suites. This includes storage of the MIDlet Suites themselves as well as any RMS storage. The value is specified in bytes.
system.i18n.lang	String	en	Default language for I18N processing.
system.i18n.encoding	String	ISO8859_1	Default encoding for I18N processing.
system.display.double_buffered	boolean	true	Whether to use double buffering when writing to the graphics display.
system.display.screen_depth	integer	4	Number of bits to use for each color. The maximum number of colors is 2 to the power of this number. Set to 1, 2, 4 or 8 for 2, 4, 16 or 256 colors respectively.
system.display.visual_type	String	""	Visual class of window. Value can be one of: `StaticGray` `GrayScale` `StaticColor` `PseudoColor` `TrueColor` `DirectColor` This property is valid only on the Solaris™ Operating Environment (OE).
com.sun.midp.midlet.platformRequestCommand	String	""	Command spawned when the method `MIDlet.platformRequest` is called. The command should take a single argument, a URL; it will be given the URL passed to the `MIDlet.platformRequest` method.
com.sun.midp.io.http.proxy	String	""	Host and port of the HTTP proxy in the format of host:port. The value of this property is also used to tunnel HTTPS connections.
com.sun.midp.io.http.force_non_persistent	boolean	false	Force all connections to be non persistent.
com.sun.midp.io.http.max_persistent_connections	integer	1	Maximum number of persistent connections allowed at any given time.
com.sun.midp.io.http.persistent_connection_linger_time	Integer	60000	Number of milliseconds an unused persistent connection should remain in the connection pool.
com.sun.midp.io.http.inputBufferSize	integer	256	The size, in bytes, of the input buffer. There is an input buffer for every connection.
com.sun.midp.io.http.outputBufferSize	integer	2048	The size, in bytes, of the output buffer. There is an output buffer for every connection.
com.sun.midp.lcdui.eventHandler	String	com.sun.midp.lcdui.DefaultEventHandler	The name of the class that handles events.
com.sun.midp.lcdui.inputMethodHandler	String	com.sun.midp. lcdui.i18n. DefaultInput MethodHandler_ locale	The name of the class to handle input. The default input handler uses the value of the `microedtion.locale` attribute to determine the correct class name.
com.sun.midp.midlet.scheduler	String	com.sun.midp.midlet.Scheduler	The name of the class used to schedule MIDlets.
com.sun.midp.graphicalmanager	String	com.sun.midp.dev.Manager	The name of the class used to manage MIDlet Suites in the device emulator’s graphical user interface.
com.sun.midp.midletsuite.installer	string	com.sun.midp.midletsuite.Installer	Name of the class used to install MIDlet suites.

TABLE 3 Properties in the `system.config` File
Property Name	Type	Default Value	Description
microedition.configuration	String	CLDC-1.0	Version number of the underlying J2ME platform configuration. When there are multiple configurations, they will be separated by blanks (Unicode `x20`)
microedition.encoding	String	ISO-8859-1	Current character encoding
microedition.hostname	String	““	Name of the host platform
microedition.profiles	String	MIDP-2.0	List of version numbers of supported J2ME platform profiles; profiles are separated by blanks (Unicode `x20`)
microedition.locale	String	““	Current locale for I18N support.
microedition.platform	String	j2me	Current host platform.
com.sun.midp.io.j2me.comm.buffersize	Integer	256	The size, in bytes, of the input buffer. Each comm connection has an input buffer.
com.sun.midp.io.j2me.socket.buffersize	Integer	0	The size, in bytes, of the input buffer. Each socket connection has an input buffer.
javax.microedition.io.Connector.protocolpath	String	com.sun.cldc.io	Package prefix used to find protocols The protocol class name will be protocolPath`.j2me.`protocol`. Protocol.class`.

To permanently change a property value, edit the appropriate file. To temporarily change a property value, use the -D command-line option to the midp command.

Options

Running the tool without options launches the device emulator’s graphical user interface.

Specifies the directories, zip files, and JAR files to search for Java class files. This argument is passed to CLDC.

Overrides the value of property set in the configuration file. This argument is passed to CLDC.

Specifies the amount of memory to be set aside for the heap, specified as number of bytes (such as 65536), number of kilobytes (such as 128k) or number of megabytes (such as 1M). This argument is passed to CLDC.

The minimum heap required to run the midp executable when there are no applications installed on the emulator is 32k. (When applications are installed, the minimum amount varies but is never lower than 32k.)

Repeatedly installs, runs, and removes the first MIDlet from the MIDlet suite described by the Java application descriptor (JAD) file at the descriptorURL location. (The JAD file specifies the location of its corresponding JAR file.)

This command installs the MIDlet suite into domain. If domain is not provided the domain maximum is used. The command removes the MIDlet suite when it gets a 404 code from the server.

Starts the MIDP executable in debug mode. The portNumber should be the number of the port on which the KVM debug proxy expects the debugger to be running. See the KVM documentation for more information on this and other options that are available for a MIDP executable in debug mode.

Prints text to standard output that describes the options to the midp command and exits.

-install [ -force ] [ -domain domain ] [ -removeRMS ] descriptorURL

Installs the MIDlet suite represented by the JAD file at descriptorURL location. This command installs the MIDlet suite into domain. If domain is not provided, and the suite is unsigned, the default domain, untrusted, is used.

Using -removeRMS removes any persistent data written by any previous versions of the MIDlet suite. This option only has an affect if the installation is overwriting an existing installation of the MIDlet suite.

Using -force has the MIDP Reference Implementation runtime ignore any overwrite errors that occur during the installation.

Prints information to standard output on the installed MIDlets, including their names, vendors, descriptions, storage names, sizes, original locations (URLs), and lists of MIDlets.

Removes the installed MIDlet suite identified by the given suitenumber or storagename, or removes all MIDlet suites.

Runs the installed MIDlet suite that is identified by suitenumber or storagename. The suitenumber is the number displayed by the -list option to the midp command, and storagename is the name displayed by the -storageNames option to the midp command.

If suitenumber or storagename identifies a MIDlet suite that contains multiple MIDlets, MIDletName can specify a particular MIDlet in the suite to run.

Prints to standard output the storage names of the installed MIDlet suites. Storage names of MIDlets are implementation dependent.

-transient [ -force ] [ -domain domain ] [ -removeRMS ]
descriptorURL [ MIDletName ]

Downloads, installs, runs, and removes the MIDlet suite represented by the JAD file at the descriptorURL location. This command installs an unsigned MIDlet suite into domain. If domain is not provided for an unsigned MIDlet suite, the default, untrusted, is used.

If the JAD file at descriptorURL describes a MIDlet suite that contains multiple MIDlets, MIDletName can specify a particular MIDlet in the suite to run.

Using -force has the MIDP Reference Implementation runtime ignore any overwrite errors that occur during the installation.

Returns the version of the MIDP Specification with which this release is compliant, the version of the MIDP implementation, and the version of the configuration (CLDC) with this release.

Examples

Installing a MIDlet Suite

The following example installs the same unsigned MIDlet suite, but assigns it to the trusted domain:

Listing Installed MIDlet Suites

The following example lists the MIDlet suites installed on the device emulator. It shows the command being run on an emulator that has one MIDlet suite installed.

Running an Installed MIDlet Suite

The following example runs the MIDlet suite listed in the previous example. It provides the number associated with the MIDlet.

Appendix C