MIDP

In the previous section, you looked at the functionality of the CLDC, although most of what you reviewed was more about the limitations of the configuration in comparison to J2SE. Also, you might have noticed the omission of some of the things you really need to build an application, such as any form of user interface. These components are device-specific, so it's up to a device category's profile to implement them. This typifies the role of the profile: to add category-specific components on top of a configuration.

The most popular profileand the only one really useful for your purposesis MIDP, which targets MIDs (Micro Information Devices).

Since MIDP is all about MIDs, take a look at what the profile defines them to be.

Target Devices

MIDs aren't the most capable of computers, and I'm probably using the term computer a little loosely here. MIDs are highly portable, uncoupled devices that always compromise functionality for form.

The MIDP specifications reflect this by setting a lowest-common-denominator target platform that can be met by a broad range of handheld devices, especially mobile phones.

The MIDP sets target characteristics that MIDs should (and generally do) meet. There are both hardware and software specifics, both of which I will discuss in more detail in just a moment.

Target Hardware Environment

As you can see in the following list, the characteristics of the target devices are extremely limited. The screens are tiny, the memory is forgettable, and the CPUs move about as fast as I do on a Monday morning.

However, it's important to remember that these characteristics are the minimum target. Many devices dramatically exceed these specifications. Much larger, color screens; more RAM; better input; and next-generation networking are becoming common on an ever-increasing range of devices. Games on the higher-end devices can be downright sexy.

Even on low-end hardware, you can still make some great games; it's just a bit more of a challenge. In later sections, I'll also cover how to develop a game that can adapt itself to take advantage of additional hardware functionality, if available.

The recommended minimum MIDP device characteristics are

• Display

  • 96 x 54 pixels with 1 bit of color with an aspect ratio (pixel shape) of approximately 1 to 1

• Input types

  • One-handed keyboard or keypad (like what you see on a typical phone)

  • Two-handed QWERTY keyboard (resembling a PC keyboard)

  • Touch screen

• Memory

  • 128 KB of non-volatile memory for MIDP components

  • 8 KB of non-volatile memory for application- generated persistent data

  • 32 KB of volatile memory for the Java heap (run-time memory)

• Networking

  • Two-way wireless, possibly intermittent, connectivity

  • Usually quite limited bandwidth

Target Software Environment

As with the target hardware environment, the software that controls MIDs can vary significantly in both functionality and power. At the higher end of the market, MIDs are not dissimilar to small PCs. At the low end, however, some components you would consider fundamental to the concept of a computer aren't available, such as a file system.

Due to this variety, the MIDP specifications mandate some basic systems software capabilities. The following list shows the most relevant of these capabilities.

• Memory

  • Access to a form of non-volatile memory (for storing things like player name and high scores)

• Networking

  • Sufficient networking operations to facilitate the communications elements of the MIDP API

• Graphics

  • Ability to display some form of bitmapped graphics

• Input

  • A mechanism to capture and provide feedback on user input

• Kernel

  • Basic operational operating system kernel capable of handling interrupts, exceptions, and some form of process scheduling

MIDP Applications

A Java program written to be executed on a MID is called a MIDlet. (Who comes up with these names? I would prefer to call it something cooler, like a microde or a nanogram hmm, no, that sounds like a really tiny telegram.)

The MIDlet is subject to some rules regarding its run-time environment and packaging. I'll cover each of these rules in a bit more detail in the next few sections.

Run-Time Environment

It is the role of the device's built-in application manager to start the MIDlet. It's important to know that your application has access to only the following resources:

• All files contained within the application's JAR file

• The contents of the MIDlet descriptor file

• Classes made available as part of the CLDC and MIDP libraries

From this list, you can start to see the structure of a typical MIDlet game package. Most importantly, the JAR file should contain all the classes required to run the application, along with all the resources, such as image files and level data. You can also set application execution options as properties within the plain text MIDlet descriptor file.

Suite Packaging

As I just mentioned, a MIDlet application typically takes the form of a JAR file. This archive should contain all of the class and resource files required for your application. It should also contain a manifest file with the name manifest.mf.

The manifest, stored inside the JAR file, is simply a text file containing attribute value pairs (separated by a colon). Table 2.3 lists all of the types of required and optional attributes included in a manifest file.

Table 2.3. MIDlet JAR Manifest Attributes

Attribute	Description
Required Attributes
MIDlet-Name	Descriptive name of the MIDlet suite.
MIDlet-Version	Version number of the MIDlet suite.
MIDlet-Vendor	The owner/developer of the application.
MIDlet-<n>	The name, icon filename, and class of each of the MIDlets in the suite. For example: MIDlet-1: SuperGame,/supergame.png,com.your.SuperGame MIDlet-2: PowerGame,/powergame.png,com.your.PowerGame
MicroEdition-Profile	The name of the profile required to execute the MIDlets in this suite. The value should be exactly the same as the value of the system property microedition.profiles. For MIDP version 1, use MIDP-1.0.
MicroEdition-Configuration	The name of the configuration required to run the MIDlets in this suite. Use the exact name contained in the system property microedition.configuration, such as CLDC-1.0.
Optional Attributes
MIDlet-Icon	Name of a PNG image file that will serve as a cute little picture identifying this MIDlet suite.
MIDlet-Description	Text describing the suite to a potential user.
MIDlet-Info-URL	URL pointing to further information on the suite.
MIDlet-Jar-URL	The URL from which the JAR can be downloaded.
MIDlet-Jar-Size	Size of the JAR in bytes.
MIDlet-Data-Size	Minimum number of bytes of non-volatile memory required by the MIDlet (persistent storage). The default is zero.

In the case where your manifest file contains information on multiple MIDlets (a MIDlet suite), you should use the MIDlet-<N> attributes to specify information on each of the individual MIDlets within the package. Typically, though, your package will only have one application so this isn't too much of a concern.

Of course, you can add your own attributes to the manifest file. The only rule is that they cannot begin with the MIDlet- prefix. Also keep in mind that attribute names must match exactly, including case.

You might also wonder what the point of the MIDlet-Jar-URL attribute is. Given that the manifest file has to be included within a JAR, you might rightly ask, why bother having a URL to go and download a JAR when you obviously must have the JAR to know the URL in the first place? The answer is, you don't need to bother having this attribute in your manifest fileit's intended for use in the application descriptor (JAD) file reviewed later in this section. The attribute is in the list because the manifest file also serves as the default for any attributes not contained within the JAD. The creators of the specifications for MIDP elected to create a single set of attributes for both the manifest and JAD files. A reasonable thing to do, but it still left me confused the first time I read the specifications.

The following is an example of a manifest file:

MIDlet-Name: Super Games

MIDlet-Version: 1.0

MIDlet-Vendor: Your Games Co.

MIDlet-1: SuperGame,/supergame.png,com.your.SuperGame

MIDlet-2: PowerGame,/powergame.png,com.your.PowerGame

MicroEdition-Profile: MIDP-1.0

MicroEdition-Configuration: CLDC-1.0

Application Descriptors (JADs)

Transferring large amounts of data around mobile networks is a bit like trying to send an encyclopedia via carrier pigeon (otherwise known as CPIP). For this reason, a descriptor file is available to allow users to view the details of a MIDlet JAR without actually having to download the whole thing.

The application descriptor file, or JAD, serves this purpose. It contains essentially the same attributes as those in the manifest, and it naturally exists independent of the JAR file. Figure 2.6 shows the relationship between all the components of a MIDlet suite and a JAD file.

There is a close link between the JAD and the manifest files. You should think of the JAD as a mini-version of the manifest. The following attribute values must be the same in both files, or else the MIDP application manager will reject the MIDlet suite:

• MIDlet-Name

• MIDlet-Version

• MIDlet-Vendor

For all other attributes, the values in the JAD file take precedence.

The following is an example of a JAD file:

MIDlet-Name: Super Games

MIDlet-Version: 1.0

MIDlet-Vendor: Your Games Co.

MIDlet-1: SuperGame,/supergame.png,com.your.SuperGame

MIDlet-2: PowerGame,/powergame.png,com.your.PowerGame

MicroEdition-Profile: MIDP-1.0

MicroEdition-Configuration: CLDC-1.0

MIDlet-Jar-Size: 2604

MIDlet-Jar-URL: http://your-company.com/MIDlets.jar

As you can see, the primary difference between the JAD and the manifest examples is the inclusion of the two MIDlet-Jar attributes. Using these attributes, the application manager can determine the download and device storage requirements for your game.

MIDP 1.0 Libraries

The MIDP specification does a good job of locking down the hardware characteristics of MIDs for you, but there's more to developing applications than just describing the hardware. The MIDP also delivers the real guts of the J2ME mobile software solutionthe libraries.

The MIDP libraries provide tools designed specifically for the idiosyncrasies of development on MIDs. This includes access to:

• A user interface catering to small screens and limited input

• Persistent storage (non-volatile memory), also known as record management

• Networking (through an implementation of the CLDC connection framework)

• Timers

• Application management

I'll review the details of all of these API parts in Chapter 5, "J2ME API." For now, you can review the following list of available classes.

• General utility

• java.util.Timer

• java.util.TimerTask

• java.lang.IllegalStateException

• User interface classes

• javax.microedition.lcdui.Choice (interface)

• javax.microedition.lcdui.CommandListener (interface)

• javax.microedition.lcdui.ItemStateListener (interface)

• javax.microedition.lcdui.Alert

• javax.microedition.lcdui.AlertType

• javax.microedition.lcdui.Canvas

• javax.microedition.lcdui.ChoiceGroup

• javax.microedition.lcdui.Command

• javax.microedition.lcdui.DateField

• javax.microedition.lcdui.Display

• javax.microedition.lcdui.Displayable

• javax.microedition.lcdui.Font

• javax.microedition.lcdui.Form

• javax.microedition.lcdui.Gauge

• javax.microedition.lcdui.Graphics

• javax.microedition.lcdui.Image

• javax.microedition.lcdui.ImageItem

• javax.microedition.lcdui.Item

• javax.microedition.lcdui.List

• javax.microedition.lcdui.Screen

• javax.microedition.lcdui.StringItem

• javax.microedition.lcdui.TextBox

• javax.microedition.lcdui.TextField

• javax.microedition.lcdui.Ticker

• Application classes

• javax.microedition.midlet.MIDlet

• javax.microedition.midlet.MIDletStateChangeException

• Record management classes

• javax.microedition.rms.RecordComparator (interface)

• javax.microedition.rms.RecordFilter (interface)

• javax.microedition.rms.RecordListener (interface)

• javax.microedition.rms.RecordStore

• javax.microedition.rms.InvalidRecordIDException

• javax.microedition.rms.RecordStoreException

• javax.microedition.rms.RecordStoreFullException

• javax.microedition.rms.RecordStoreNotFoundException

• javax.microedition.rms.RecordStoreNotOpenException

• Networking classes

• javax.microedition.io.Connection (interface)

• javax.microedition.io.ContentConnection (interface)

• javax.microedition.io.Datagram (interface)

• javax.microedition.io.DatagramConnection (interface)

• javax.microedition.io.HttpConnection (interface)

• javax.microedition.io.InputConnection (interface)

• javax.microedition.io.OutputConnection (interface)

• javax.microedition.io.StreamConnection (interface)

• javax.microedition.io.StreamConnectionNotifier (interface)

• javax.microedition.io.Connector

• javax.microedition.io.ConnectionNotFoundException