Release Notes

[Skip TOC]

Table of Contents

Introduction

New Features

System Requirements

Release Contents

Installation

Accessibility Features

Known Bugs and Issues

Introduction

MIDP (Mobile Information Device Profile) is part of the Java™ 2 Platform, Micro Edition (J2ME™). MIDP is built on top of the Connected Limited Device Configuration (CLDC) and defines the Java application environment for mobile information devices (MIDs), such as mobile phones and personal digital assistants (PDAs). This product, the MIDP Reference Implementation is for developers who will be porting MIDP to mobile information devices.

The MIDP Reference Implementation, Version 2.0 FCS, implements the specification from the Mobile Information Device Profile 2.0 [JSR-000118]. The MIDP 2.0 specification is based on the MIDP 1.0 specification and provides backward compatibility with MIDP 1.0 so that MIDlets written for MIDP 1.0 can execute in MIDP 2.0 environments. For detailed information on both MIDP specifications, see http://jcp.org.

MIDP runs a device emulator on your desktop system. An application that runs in a MIDP environment (whether in an emulator or on a device) is called a MIDlet. One or more MIDlets packaged together for distribution are called a MIDlet suite.

New Features

Compared to MIDP 1.0, the MIDP Reference Implementation, Version 2.0 FCS, has the following new features:

• Sound — the Audio Building Block from the Mobile Multimedia API (JSR-000135)
• Security for MIDlet suites — a notion of trust for MIDlet suites, and security domains to protect security-sensitive APIs from untrusted MIDlet suites
• Games API — a series of classes that enable the development of rich gaming content for wireless devices
• Additional LCDUI components — new components include a spacer (a blank, non-interactive item used to help position other items), a custom item (customizable item that can introduce new visual and interactive elements into a form), and so on.
• Additional LCDUI features — new features include the ability to add abstract commands to alerts and items, a full-screen mode for the Canvas class, vibrate, and so on.
• Additional network protocols — networking support, although still based on the Generic Connection framework from the Connected Limited Device Configuration, contains more predefined protocols:
  • Comm
  • Datagram
  • HTTP
  • HTTPS
  • Socket
  • Server Socket
  • SSL
• Push functionality — ability to launch a MIDlet in response to an incoming message.

System Requirements

The supported platform for this release is Microsoft Windows 2000. Systems running the Solaris™ Operating Environment (OE) and the Linux operating system are not officially supported. This section details the hardware and software requirements for the supported and unsupported systems:

• Microsoft Windows 2000
• Solaris Operating Environment
• Linux

The hardware requirements are:

• Pentium II-based PC
• 128 MB memory
• 100 MB free disk space
• Sound device for audio playback
• RS-232 serial cable for testing the serial connection
  

The software requirements are:

• All current critical updates to Microsoft Windows 2000
• Java Development Kit (JDK™), no earlier than version 1.3.x

In addition, the build environment requires:

• A system locale based on the ISO 8859-1 (Latin-1) character set
• Cygwin 1.3.11
• CLDC, Version 1.0.4 (See Installing MIDP for information on where to install this on your system, if it is not already installed.)

The MIDP Reference Implementation was tested on a Gateway PII, 350 MHz system with 128 MB RAM and a Creative Audio PCI (ES1371/ES1373) sound card running Windows 2000.

Solaris Operating Environment

The hardware requirements are:

• Ultra™ 1 workstation
• 128 MB memory
• 200 MB swap
• 100 MB free disk space
• Sound device for audio playback
• RS-232 serial cable for testing the serial connection

The software requirements are:

• JDK, no earlier than version 1.3.x
• Solaris OE (SPARC^® Platform Edition), Version 2.5 or later
• SUNWcsu — Core operating system software

In addition, the build environment requires:

• CLDC, Version 1.0.4
• GNU Make, Version 3.74
• Zip utility
• Solaris OE Software:
  • SUNWbtool — Software development utilities
  • SUNWtool — Programming tools
  • SUNWsprot — Tools bundled with the Solaris OE

The MIDP Reference Implementatnion was tested on a Sun Ultra 2 workstation running Solaris 8 (2.8) with 1024 MB of RAM and a CS4231 sound device.

Linux

The hardware requirements are:

• Pentium-II based PC
• 128 MB memory
• 200 MB swap
• 100 MB free disk space
• Sound device for audio playback
• RS-232 serial cable for testing the serial connection

The software requirements are:

• Red Hat Linux distribution, Version 7.2, x86 release
• JDK, no earlier than version 1.3.x

In addition, the build environment requires:

• CLDC, Version 1.0.4 (See Installing MIDP for information on where to install this on your system, if it is not already installed.)
• gcc-2.95.3 or gcc-3.03 (C compiler)

The MIDP Reference Implementation was tested on a Dell PIII 733 MHz system with 256 MB RAM running Linux RedHat 7.2 (kernel version 2.4.7-10). The sound system consists of a Creative SoundBlaster Live! sound card with the Creative EMU10K1 PCI Audio Driver, version 0.6, 16:53:07 Aug 22 2000.

Release Contents

Unzipping the distribution creates the directory midp2.0-FCS with the subdirectories:

• appdb — Information for the device emulator, such as a keystore
• bin — Executables
• build — Compilation tools
• classes — Class files
• docs — Documentation included with this release
• example — Example MIDlets
• lib — Default configuration files
• src — Source code
• tools — Source for supporting build tools

Installation

See Installing MIDP for installation instructions.

Accessibility Features

The following keys can be used instead of the mouse to operate the graphical user interface (GUI) of the device emulator:

Button	Button Function	Keyboard Equivalent
Up, down, left, and right navigation buttons	To navigate (move the highlight on the screen), and for game controls (up, down, left, and right)	Arrow keys
Select button	To make a choice (for example, to choose an element from a list), and for game controls (select/fire)	Enter key
End Call button	To exit a MIDlet	F10 key
Clear button	To remove the character to the left of the cursor in a text box or text field (Press and hold to remove all the text.)	Backspace key
Left soft button	To select any command assigned to the left soft button (the command label will be at the bottom left corner of the emulator's screen)	F1 key
Right soft button	To select any command assigned to the right soft button (the command label will be at the bottom right corner of the emulator's screen)	F2 key
Standard phone keypad: Numbers 0-9 Pound (#) function key (also used as a space) Star (*) function key (also used as mode shift)	To enter letters, numbers, and other supported characters; also to enter game controls, as shown in the following figure:	The corresponding letter, number, #, *, shift, and space keys

In addition, the HTML documentation is accessible.

Known Bugs and Issues

• API Usage Issues
• Software Limitations
• Documentation Issues
• Software Bugs

API Usage Issues

The MIDP 2.0 Specification warns that blocking the commandAction method of the CommandListener interface might block the virtual machine (VM). The specification provides this warning because it requires the event handler to process an event to completion before moving on to the next one. If an application blocks the event thread, the user will not be able operate the MIDlet and will think that the VM is hung. (Note that the VM might appear to be hung but, if there are multiple threads, the other threads are still running.)

As a practical matter, it is most important to heed the warning against calling blocking methods when you are considering calling security-sensitive APIs. Merely updating a Displayable or moving from one screen to another is unlikely to cause a problem. When you use security-sensitive APIs the system might need to ask the user to grant a permission. Because the permission request is done on a new screen, a permission request is a new event. The event thread cannot process that permission-request event, however, because it is blocked waiting for the security-sensitive call to complete. The event thread is deadlocked.

The correct way to perform blocking operations, such as calls to use the network, is to spawn a new thread. When it is run in a new thread, the blocking call no longer blocks the event thread. The event thread is free to process the next event. Using the example in the previous paragraph, that next event could be a permission request. The MIDlet avoided the deadlock.

The following example shows how to correctly spawn the thread that makes blocking calls:

public void commandAction(Command c, Displayable s) {
    synchronized (this) {
        currentCommand = c;
        new Thread(this).start();
    }

    // Let the run method get into its synchronized block.
    try {
        Thread.sleep(1);
    } catch (InterruptedException e) {
        // ignore
    }
}
  
public void run() {
    synchronized (this) {
        if (currentCommand == exitCommand) {
            destroyApp(false);
            notifyDestroyed();
        } else if (currentCommand == goCommand) {
            // Make a network connection
            ...
        }
    }
}

Note that making blocking calls in a separate thread was good practice in MIDP 1.0.x releases too. In those release, however, making calls to access the network did not require permission from the user. As a result, they did not cause deadlocks.

Software Limitations

• When building the MIDP Reference Implementation on the Solaris OE, the directory /usr/bin must appear before /usr/ucb on your PATH environment variable. If they are in the reverse order, the build environment tries to use the tr command from the /usr/ucb directory and the build fails with the error message,

  No rule to make target `obj/lcWi'

• Running MIDlets from the classpath (that is, using the -Xdescriptor option) is no longer a feature of the MIDP Reference Implementation on any platform. MIDlets must be packaged into a Java Archive (JAR) and Java Application Descriptor (JAD) file pair and downloaded from a URL. You can run a packaged MIDlet with the device emulator's graphical user interface (install the MIDlet suite, if necessary, then launch it), or with the command line (using the midp command's -autotest, -transient, or, if the MIDlet suite is installed, the -run switch). See Using MIDP for more information.
   
• Using comm network connections can be a problem on Linux systems because the default permissions on the serial port do not allow access to regular users. A workaround is to become super user and change the permissions on the device before using the serial port. The command, as super user, is:

  % chmod 666 /dev/ttyS0

  Another solution is to update the configuration file that controls these permissions, /etc/security/console.perms. See your Linux documentation for more information.
   
• There could be a mismatch between the number of serial ports assumed by the MIDP Reference Implementation and the number available on your system. The MIDP Reference Implementation expects two ports. It gets this number from the microedition.commports parameter in the midpInstallDir\lib\system.config file. You can change this value permanently by editing the file. You can also set the value on the command line using the -D argument, as shown in the following example. The example, which is for a Unix^® system, has the MIDP executable run with no serial ports:
  

  % midp -Dmicroedition.commports=0

  See Using MIDP for more information on setting attribute values.

Documentation Issues

Appendix C, "Reference Documentation for com.sun.midp.ssl," in Porting MIDP has two links that are redirected to the search page at docs.sun.com^SM. The following list shows those URLs, along with alternative links you can use instead.

• http://docs.iplanet.com/docs/manuals/security/sslin/index.htm – The substitute URL is http://docs.sun.com/source/816-6156-10/index.html.
• http://docs.iplanet.com/docs/manuals/security/pkin/index.htm – The substitute URL is http://docs.sun.com/source/816-6154-10/index.html.

Software Bugs

The following table shows the bug numbers and synopses of bugs that were open at this release:

Copyright © 2002 Sun Microsystems, Inc. All rights reserved.