Running the Mobile Information Device Profile


MIDP Configuration Files

Starting with the MIDP 1.0.3 release, environment variables have been replaced by a configuration file mechanism that makes it easy to modify the runtime behavior of the reference implementation executable. The configuration mechanism also makes it easier for platform developers to identify and port specific components in the system, which will have fixed capabilities when ported to a particular device; for example, in the development environment multiple color depths are supported, but on a physical device perhaps only grey scale is actually supported.

The following table documents the configurable features in this release along with the default values and a short description of the variable. For more detailed information on specific parameters see the MIDP Porting Guide. To set these properties temporarily, use the '-D' command-line option. To change them permanently, modify the files internal.config and system.config located in build/share/lib.

Configuration File Parameters

Option Type Default Description
System Properties ( $(MIDP_HOME)/lib/system.config )
microedition.configuration string CLDC-1.0 Version number of underlying J2ME Configuration.
microedition.profiles string MIDP-1.0 Version number of J2ME Profiles.
microedition.locale string en_US Current locale for I18N support.
microedition.platform string j2me Current host platform.
Implementation Properties ( $(MIDP_HOME)/lib/internal.config
system.jam_space integer 1000000 Amount of space to reserve for JAM and RMS storage.
system.display.double_buffered boolean true If true use double buffering when writing to the graphics display.
system.display.screen_depth integer 8 Flag set to 1, 2, 4, or 8 for 2, 4, 16, or 256 colors.
system.i18n.lang string en Default language for I18N processing.
system.i18n.encoding string ISO8859_1 Default encoding for I18N processing.
system.display.slow_time_interval integer -1 Slow down graphic repaints to device like speeds. (microseconds)
system.display.debug_screen string NULL Debug frame on X Windows.
system.display.visual_type string TrueColor Use full X visual characteristics.
system.throttle_per_milli integer 50 bytecodes per milliseconds Slow down virtual machine to device like speeds.(microseconds)
com.sun.midp.io.enable_extra_protocols boolean false If set extra protocols may be available via Connector.open. e.g. CLDC reference implementation datagram, socket and serversocket sample protocols, or the MIDP experimental https protocol handler.
com.sun.midp.midlet.scheduler string com.sun.midp.midlet.Scheduler Default MIDlet scheduler class.
com.sun.midp.midletsuite.installer string com.sun.midp.midletsuite.Installer Default MIDlet installer class.
com.sun.midp.lcdui.eventHandler string com.sun.midp.lcdui.DefaultEventHandler Default event handler class.
com.sun.midp.lcdui.skin string classes/icons/skin.gif Alternate graphic image to use as phone skin on J2SE platform.
com.sun.midp.lcdui.inputHandler string com.sun.midp.lcdui.DefaultInputMethodHandler Default input handler class. (com.sun.midp.lcdui.i18n.DefaultInputMethodHandler_ prefix is used to locate microedition.locale specific input handlers)
com.sun.midp.io.http.proxy string NULL The value of the http proxy server, which can be used to redirect an HTTP request through a firewall-enabled proxy server. e.g. webcache:8080
com.sun.midp.io.http.max_persistent_connections integer 4 The value of the maximum persistent connections, that the connection pool can have opened at any one time. e.g. for the palm 1
com.sun.midp.io.http.force_non_persistent boolean false If true do NOT use persistent connection pool (always close connection). If false use persistent connection pool (up to maximum connections).

Command Line Arguments

The midp executable can be launched to simply run individual MIDlets or suites of MIDlets using various command line switches to the midp command.

Usage: midp [<options>] [-Xdescriptor <filename>] <class>
         Run a MIDlet from the classpath.
          -Xdescriptor: Get the MIDlet properties from this file

   or  midp [<options>]
         Run the Graphical MIDlet Suite Manager.

   or  midp [<options>] -Xdescriptor <filename>
         Select a MIDlet to run from a local MIDlet suite descriptor.

   or  midp [<options>] -autotest <descriptor URL> [<MIDlet name>]
         Install, run, and remove an application repeatedly.

   or  midp [<options>] -transient <descriptor URL> [<MIDlet name>]
         Install, run, and remove an application.

   or  midp [<options>] -install [-force] <descriptor URL>
         Install a MIDlet suite using the URL of a descriptor.
          -force: Force the operation and ignore any overwrite errors

   or  midp [<options>] -run (<suite number> | <storage name>)
           [<name of MIDlet to run>]
         Run an installed MIDlet suite.

   or  midp [<options>] -remove (<suite number> | <storage name> | all)
         Remove an installed MIDlet suite. To clean up RMS space used when
         running a MIDlet from the classpath, use the storage name
         "run_by_class_storage_".

   or  midp [<options>] -list
         List the installed MIDlet suites by number and name.

   or  midp [<options>] -storageNames
         List the just storage names of the installed MIDlet suites,
         one per line.

where suite number is a suite number displayed by the list command,

and storage name is the unique name a suite is stored by,

and options include:
    -version    Show version info and exit
    -help       Show this message and exit
    -classpath <path>  directories and zip files to search for classes
    -D<property>=<value> Override configuration file settings

and these debugging options:
    -heapsize <size> (e.g. 65536 or 128k or 1M)

Tracing Options

The MIDP executable can be built with tracing capability turned on. (Refer to the configuration option INCLUDEDEBUGCODE in Configuration Options or Build Commands).
If the MIDP executable is built with tracing capability turned on, these additional midp options are available:

 
    -traceallocation
    -tracegc
    -tracegcverbose
    -traceclassloading
    -traceclassloadingverbose
    -traceverifier
    -tracestackmaps
    -tracebytecodes
    -tracemethods
    -tracemethodsverbose
    -tracestackchunks
    -traceframes
    -traceexceptions

Using HTTPS Protocol

New with this release is the addition of the HTTPS protocol. By default, the MIDP executable does NOT support this protocol. To enable the new protocol, follow these steps:

Rebuild the MIDP executable with HTTPS enabled. This will increase the size of the MIDP executable by approximately 100Kb.
Note that you MUST use the MIDP release for the platform you build on. For example, you will not be able to build an HTTPS enabled binary for Linux using the Win32 source release.

 gnumake INCLUDE_HTTPS=true clean all

Edit the MIDP Configuration File, internal.config. You must set the property com.sun.midp.io.enable_extra_protocols to true.

vi lib/internal.config

Examples

Prebuilt example Jar and Jad files are included in the MIDP 1.0.3 release, in midp1.0.3/example/. To run them, execute the following commands in the midp1.0.3/ directory.

A single MIDlet can be launched from any class in CLASSPATH that extends the MIDP MIDlet class. The midp executable will supply a basic application management container that will walk the MIDlet through a typical lifecycle where a MIDlet is constructed and destroyed.

Simple command line:

 bin/midp -classpath example/pushpuzzle.jar example.pushpuzzle.PushPuzzle

A MIDlet suite is started when a descriptor file is provided which identifies several MIDlets available within the user's CLASSPATH. During development it is often easiest to deal with class files in a separate directory rather than within the final packaged Jar file. (After compiling and preverify operations are run from the sample makefile, the classes and icons are available in the classes directory).

Launch with a descriptor file:

 bin/midp -classpath classes -Xdescriptor example/games.jad

When the application is fully deployed the application management software includes the ability to fetch a remote descriptor file and the Jar file indicated within that descriptor file.

Fetch a remote descriptor file:

 bin/midp -transient http://sample.host.com/j2me/midp/games.jad

The application management software can also fetch a remote descriptor file and the associated Jar file and install them on the local host. It may then be run locally.

Install a MIDlet suite described by a remote descriptor file :

 bin/midp -install http://sample.host.com/j2me/midp/games.jad

List locally installed MIDlet suites.

 bin/midp -list

Run a specific MIDlet from the first a locally installed MIDlet suite listed.

 bin/midp -run 1 wormgame

Remove the first locally installed MIDlet suite listed.

 bin/midp -remove 1

An alternative to using the above commands to run the example MIDlets is to use gnumake to automate it. To do this, change to your build/platform directory and type any of the following:

gnumake run_games
gnumake run_demos
gnumake run_manyballs
gnumake run_auction
gnumake run_pushpuzzle
gnumake run_stock
gnumake run_photoalbum

Running Example Programs

The sample programs included in the MIDP workspace can be used for demonstration purposes or for simple functional regression testing. The current sample code is not necessarily appropriate for instructional purposes or as coverage tests for the full MIDP specification.

MIDlet sample code:

  • Imaging functions

    The photoalbum test MIDlet shows the use of loading and displaying images.

    To run the photo album, execute the following command in the midp1.0.3/ directory:

    ./bin/midp -classpath example/photoalbum.jar -descriptor example/photoalbum.jad
    
  • Networking functions

    The stock MIDlet is meant to serve as a simple example of fetching live data from an Internet-accessible website. It shows how to use the network support to send and receive the appropriate HTTP headers in a live example.

User Interface sample code:

  • PushPuzzle demo game

PushPuzzle is a simple game that lets the user manipulate objects on a small display screen. This MIDlet exercises the low level drawing primitives as well as some of the high level Command functions. It is also integrated with the RecordStore facility to remember the user's current level and high score.

Note: The PushPuzzle game also uses a Zip file of its own to contain the various mazes for each level of the game. It must be included on the command line in the classpath argument.

To run the PushPuzzle game MIDlet, execute the following command in the midp1.0.3/ directory:

bin/midp -classpath example/pushpuzzle.jar example.pushpuzzle.PushPuzzle

Debugging and Problem Reporting

Previously, it was difficult to determine what exactly was going on in a MIDlet. A debug session usually entailed inserting copious System.out.println()'s into the Java code to find out where the program was going wrong.

Now, with the MIDP 1.0.3 release, debugging a MIDlet has become much easier. The MIDP now supports source-level debugging of MIDlets. The MIDP 1.0.3 release uses the same debugging architecture provided with the CLDC 1.0.3. (Please refer to the CLDC reference documentation for a thorough description of the new debugging architecture.)

To debug the PushPuzzle game MIDlet:

  1. Build the MIDP executable with source-level debugging support:
    gnumake ENABLE_DEBUGGER=true clean all
  2. Make the PushPuzzle game w/ debugging information:
    gnumake ENABLE_DEBUGGER=true pushpuzzle
  3. Start the MIDP executable in "debug" mode. The MIDP will wait for a connection from the KVM debug proxy on the localhost at port 2800.
    bin/midp -debugger -port 2800 \ -classpath example/pushpuzzle.jar example.pushpuzzle.PushPuzzle
  4. Start the KVM debug proxy. This will connect to the MIDP virtual machine running on the localhost at port 2800. It will wait for a connection from the Java debugger at port 5000. Please refer to the KVM documentation for a complete description of the command-line parameters for the KVM debug proxy.
    java -classpath bin/kdp.jar kdp.KVMDebugProxy -l 5000 \ -p -r localhost 2800 -cp classes.zip:pushpuzzle.jar
  5. Connect to the KVM debug proxy from any JPDA compliant Java debugger. (Some examples are jdb, Forte for Java, JBuilder, Code Warrior, Visual Cafe, etc..) You will need to setup the debugger to attach to a already running VM on the localhost at port 5000. Once the debugger is attached, set any breakpoints and then start the program execution. NOTE: If the MIDP source code is accessible to the debugger (and if the debugger's sourcepath is set up properly) it is possible to step through the MIDP Java code as well.

Reporting Problems

Ideally, all reported problems are easily reproduced on the current release.

Report all platform and variant information, if not built on the standard platform.

If possible submit the bug with a script or code fragment that demonstrates the problem.

Please send any comments, bugs, questions or general feedback to the MIDP support alias at: midp-comments@sun.com


Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, California 94303, U.S.A. All rights reserved. This product is distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers. Sun, Sun Microsystems, the Sun Logo, Java, and the Java Coffee Cup Logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Federal Acquisitions: Commercial Software -- Government Users Subject to Standard License Terms and Conditions. DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.