Mobile Apps Resource: J2ME Tutorial, Part 1: Creating MIDlets

J2ME Tutorial, Part 1: Creating MIDlets:

begins -->

't move sidebars -->

ends -->

begins -->

-->

Contents

J2ME Introduction

Acquiring and Installing the J2ME Development Kit

Understanding the Process of MIDlet Creation--Without the Toolkit

Understanding the Process of MIDlet Creation--Using the Toolkit

The MIDlet Lifecycle

ends -->

Java 2 Micro Edition (J2ME) combines a resource-constrained JVM and a set of

Java APIs for developing applications for mobile devices.

This article is the first in a series. This time, after a quick introduction

to J2ME, I will provide a step-by-step guide to creating J2ME applications,

also known as MIDlets, using a simple example. This will cover how to

test and deploy these MIDlets as well. Finally, I will round out this installment

with a look at the lifecycle of a MIDlet.

J2ME Introduction

What is J2ME? Cut away the hype and the excess fat and you are left with

yet another (set of) Java APIs. Since these APIs cannot run on a traditional Java

Virtual Machine (JVM), due to the limited size of mobile devices in regards to memory

and resource availability, J2ME defines a limited version of the JVM as well. In

a nutshell:
J2ME combines a resource constrained JVM and a set of Java APIs for

developing applications for mobile devices.
Do you, as a developer, have to install this JVM and the APIs on mobile devices?

No. Device manufacturers install and prepackage their devices with this JVM

(and associated APIs). As a developer, you only need to develop applications

targeting these devices and install them. Easier said than done!
J2ME can be divided into three parts, as shown in Figure 1: a configuration,

a profile, and optional packages. A configuration contains the JVM (not the traditional

JVM, but the cut-down version) and some class libraries; a profile builds on

top of these base class libraries by providing a useful set of APIs; and optional

packages, are well, an optional set of APIs that you may or may not use when creating

your applications. Optional packages are traditionally not packaged by the device

manufacturers, and you have to package and distribute them with your application.

The configuration and profile are supplied by the device manufacturers and they

embedded them in the devices.

Figure 1. The J2ME stack
The most popular profile and configuration that Sun provides are the Mobile Information Device Profile (MIDP)

and Connected Limited Device Configuration (CLDC), respectively. As the name suggests,

CLDC is for devices with limited configurations; for example, devices that have

only 128 to 512KB of memory available for Java applications. Consequently,

the JVM that it provides is very limited and supports only a small number of

traditional Java classes. (This limited JVM is actually called the KVM.) Its

counterpart, the Connected Device Configuration (CDC) is for devices with at

least 2MB of memory available and supports a more feature-rich JVM (but still

not a standard JVM).
The MID profile complements the CLDC configuration very well because it minimizes

both the memory and power required for limited devices. It provides the basic

API that is used for creating application for these devices. For example, it

provides the javax.microedition.lcdui package that allows us to

create the GUI elements that can be shown on a (limited) device running the

MID profile on top of a CLDC configuration. Note that MIDP cannot be used with

CDC devices. CDC devices get their own set of profiles, like the Foundation

and Personal profiles. However, I will not cover these profiles or the CDC here,

and will concentrate on using MIDP and CLDC only.
The latest versions of MIDP and CLDC are 2.0 and 1.1, respectively. Not many devices

currently support these versions, but the list is growing rapidly. Sun maintains

a list of devices according to version.

Acquiring and Installing the J2ME Development Kit

Getting started with developing applications (henceforth called "MIDlets") for

the J2ME platform is easy. Although device manufacturers install and prepackage their devices with this JVM

(and associated APIs), you still need to install the J2ME

Wireless Toolkit 2.2 on your development machine. Before that, however, you

must also have the Java Development Kit (JDK), version 1.4.2 or greater, installed.

Warning: I had problems getting the Wireless Toolkit to work properly with

JDK 5.0. If you don't need the latest features in version 5.0, it is best

to stick to any 1.4.2 version. I have used 1.4.2_05 for all examples in this

series.

You need this Toolkit because it contains tools that are important in generating

MIDlets. This Toolkit provides

the development environment for the MIDP 2.0 and CLDC 1.1 (and for MIDP 1.0

and CLDC 1.0, since these parameters are backwards compatible), and it provides

the optional packages required for the optional libraries, like 3D and Mobile

Media applications. Lastly, it provides the ability to sign your MIDlets so

that they can be authenticated before installation on a remote mobile device.
Once you download the installation package for the Toolkit, install it in the

directory of your choice. The default, on Windows, is C:\WTK22, and this will be the

installation directory for the examples in this series as well. I will not explain

the directories created under this folder just now. Before I do that, let us try and

understand the process of generating a MIDlet from scratch.

">

Understanding the Process of MIDlet Creation--Without the Toolkit

There are seven steps in the creation of a MIDlet. These steps are: designing,

coding, compiling, preverification, packaging, testing, and deployment. Some

of these steps are not strictly MIDlet-centric (for example, every application

needs to be designed, coded, and compiled), but we will cover them here because

there are MIDlet-centric differences. The Toolkit abstracts a lot of

these steps so that it is easier for you in the overall scheme of things. This

is fine and dandy once you know the process, but when you are only starting

out, you really should be coding by hand, rather than using a sugar-coated abstraction.
To ensure that we get a hands-on understanding of these steps, let us take the

help of a simple example. We will create a MIDlet that, when executed, will

print the current date and time on a mobile device for a short time. Along with

this in mind, keep Figure 2 handy to understand the sequence of these steps.

Also, note that I will explain the lifecycle of MIDlets later. For the moment,

let's get a simple MIDlet up and running, which will illustrate these steps.

Figure 2. Steps to MIDlet creation

Step 1: Design

MIDlets are different from other applications

that you may have created, simply because MIDlets run in an environment that

is very different. There are several issues, not just those that are most visible

(for example, the interactivity of your MIDlet with the user), but others that

impact its usability.
For the example application, our Date-Time MIDlet does not need user interactivity.

It needs to display the current date and time for a few seconds when the user

executes the MIDlet. For simple cases like this, it is perhaps sufficient to

mimic the design of the MIDlet by drawing it on a piece of paper. For more complex

designs with multiple screens, it is best to design the screens professionally

before starting the actual coding process.

Step 2: Code

Each MIDlet must extend the abstract MIDlet class found in the

javax.microedition.midlet package, much like creating an applet

by extending the java.applet.Applet class. At the minimum, your

MIDlet must override three methods of this abstract class, startApp(),

pauseApp(), and destroyApp(boolean unconditional).

Here is the DateTimeApp class:

package com.j2me.part1;

import java.util.Date;

import javax.microedition.lcdui.Alert;
import javax.microedition.lcdui.Display;
import javax.microedition.midlet.MIDlet;

public class DateTimeApp extends MIDlet {

 Alert timeAlert;

 public DateTimeApp() {
 timeAlert = new Alert(Alert!);
 timeAlert.setString(new Date().toString());
 }

 public void startApp() {
 Display.getDisplay(this).setCurrent(timeAlert);
 }

 public void pauseApp() {
 }

 public void destroyApp(boolean unconditional) {
 }
}

In this example, DateTimeApp's constructor creates the element that is

necessary to display the time on a device's screen and the startApp

method does the actual task of displaying this element. Don't worry if you don't

understand how the Alert element works, or when the constructor

or the other methods are called. I will cover the former in the next part, when

we look at the GUI elements of MIDP 2.0, and the latter later in this article

in the MIDlet Lifecycle section.
Copy this code into a file called DateTimeApp.java and save it in a folder that

mimics its package structure (com\j2me\part1). You can save it anywhere you

want on your machine; as far as this article is concerned, we will save

it in the folder C:\WTK22\article\com\j2me\part1.

Step 3: Compile

With this simple code in place, you now need to know how to compile it so that

it is ready for mobile devices. Compiling MIDlets is not very much different

from compiling normal Java applications. You still use javac as the compiler,

except you need to change the boot CLASSPATH while compiling MIDlets. This has

the effect of changing the base Java classes that the Java compiler uses to

compile your MIDlet against, thereby ensuring that compilation is targeted towards

the narrow set of Java's APIs for the J2ME platform. So instead of compiling

against the java.lang.Date in "normal" Java, you actually want compilation

done for J2ME's java.lang.Date. This is done by pointing to the CLDC and MIDP classes

for javac's -bootclasspath option while compiling.

This is shown below for the DateTimeApp MIDlet compilation. To do this compilation,

make sure you that you enter the command by navigating to the directory C:\WTK22\article

via the command prompt.

C:\WTK22\articlegt;javac -bootclasspath ..\lib\cldcapi11.jar;..\lib\midpapi20.jar 
 com\j2me\part1\DateTimeApp.java

Notice that I have done the compilation against the CLDC API's 1.1 and MIDP

API's 2.0 versions, respectively, by including these libraries in the bootclasspath

option. I could have done the compilation against other versions if it was required,

by simply pointing to their respective libraries.

Step 4: Preverify

Before you can deploy your MIDlet class, it needs to be preverified.

Verification of byte code is a step performed by the JVM before it runs any

class file to ensure that the class file is structurally and conceptually correct

as per the JVM specification. If the class file fails this check, it is rejected

and the JVM shuts down, indicating either security or integrity violation of

the class file. This verification is done by all JVMs, even the tiny JVM contained

in a CLDC configuration for a J2ME device. Although this is not a problem for

"normal" applications, verification in J2ME devices is a resource

and memory constraint that they simply cannot handle (or should not handle).

Therefore, the need for preverification.
Preverification is one part of a special two-step verification process, especially

designed for constrained devices, such as the ones running CLDC-based JVMs.

The idea is to let a developer preverify his classes, which limits the amount

of work needed to be performed when the classes are verified in the device.

This preverification process adds special information to the classes that identifies

them as preverified and makes the process on the device much more efficient.
Keeping this in mind, preverify your Date-Time MIDlet. The Wireless Toolkit

comes with a preverification tool in the bin folder of its installation (C:\WTK22\bin).

The following command, when executed from C:\WTK22\article, will preverify the

DateTimeApp.class created in the previous step.

C:\WTK22\articlegt;..\bin\preverify.exe -classpath ..\lib\cldcapi11.jar;..\lib\midpapi20.jar 
 com.j2me.part1.DateTimeApp

By default, the preverifier will create the preverified version of your

DateTimeApp.class file in a folder called output in the current directory. It

will preserve the package structure, so your preverified class will now be in

the folder C:\WTK22\article\output\com\j2me\part1\. You can, of course, point

the output to another folder, using the -d option for the preverify tool, but

for the moment, use the default output folder.

Step 5: Package

Packaging your MIDlet so that it ready for testing and deployment is a fairly

involved process, with several steps. Although each step is straightforward, they must be followed in proper sequence.
The first step is to create a Manifest file. This Manifest file describes the

contents of the Java Archive (JAR) file that we will be creating in the next

step. There are several attributes that can go in this file, but for your Date-Time

MIDlet, stick to only the ones that are required. This file's contents are shown

here:

MIDlet-Name: DateTimeAppbr /
 MIDlet-Version: 1.0.0br /
 MIDlet-Vendor: Vikram Goyal

Save this file as Manifest.mf in the C:\WTK22\article\output folder. (Note

the newline after the last attribute, MIDlet-Vendor. It must be present, otherwise

this attribute will not be recognized.)
Next, create the JAR file that packages up the preverified DateTimeApp.class

file and the Manifest file. To create this JAR file, navigate to the C:\WTK22\article\output

directory and issue the following command:
C:\WTK22\article\outputjar cvfm DateTimeApp.jar Manifest.mf .\com
This will create the DateTimeApp.jar file in the current (C:\WTK22\article\output)

folder.
The second-to-last step is to create a file that has an extension of .jad. A Java

Application Descriptor (JAD) file points to the location of the MIDlet it describes

so that a J2ME device can install it. Again, this file can contain several attributes

for a single MIDlet (or for several MIDlets), but for your Date-Time MIDlet,

you will stick with the ones that are required.

MIDlet-1: DateTimeApp, , com.j2me.part1.DateTimeAppbr /
 MIDlet-Name: DateTimeAppbr /
 MIDlet-Version: 1.0.0br /
 MIDlet-Vendor: Vikram Goyalbr /
 MIDlet-Jar-URL: DateTimeApp.jarbr /
 MIDlet-Jar-Size: br /
 MicroEdition-Profile: MIDP-2.0br /
 MicroEdition-Configuration: CLDC-1.1br /

Save this file as DateTimeApp.jad in the same folder as the JAR file (C:\WTK22\article\output).

I will explain the attributes in this file later, but for now, note that the

value of the MIDlet-Jar-Size attribute is missing. This missing

value brings you to the last step of the packaging step, where you determine

the size of the DateTimeApp.jar file, and put that value in this JAD file, in

actual bytes. It is very important to get this exactly right, as the installation

of this MIDlet will fail if this value is different from the actual size. On

my machine, this value is 1469 bytes, and therefore, this is what this attribute

looks like on my machine:
MIDlet-Jar-Size: 1469

This completes the packaging part. Well, actually, there are other steps in

the packaging that I could talk about (for example, signing and obfuscation),

but to keep things simple, I will leave those steps for later discussion. For

now, you will move on to testing of your MIDlet.

Step 6: Test

Before deploying your MIDlets, they must be tested by using a base common

emulator device that mimics the functionality of an actual device on your computer.

This emulator is part of the Wireless Toolkit and provides functionality that

is sure to be present in the majority of devices for which the MIDlet is targeted. This emulator is present in the bin folder of the Toolkit.
From the output directory created in the preverify step earlier, and where

we now have a packaged MIDlet in the form of JAR and JAD files, issue the following

command to run the emulator with this JAD file as an option.
C:\WTK22\article\outputgt;..\..\bin\emulator.exe -Xdescriptor DateTimeApp.jad

You should see the emulator pop up on your screen as shown in Figure 3, with

the DateTimeApp MIDlet selected. If it doesn't, the most likely error at this

point would be incorrect JAR size information. Make sure you have the exact

size listed in the JAD file.

Figure 3. Testing the DateTimeApp
At the lower right-hand corner of the emulated device's screen, you can see the "Launch" menu item

listed. The emulator has installed the MIDlet and is ready to launch it. Click

on the phone button just underneath that menu item and the MIDlet should display

the current date time for a few seconds and then disappear. Note that the MIDlet

is still running even after the date and time disappear, because in code, you did

not destroy it.

Step 7: Deploy

This is it! Now you have reached the stage where you can deploy the MIDlet

directly on your mobile device. There are two ways to do this. The first is via

a network connection between your computer and your handset. This can either

be via a USB cable or a Bluetooth wireless connection, depending on your device.

Most Java-enabled devices will allow you to install J2ME applications via this

connection.
Second, and the one that is more interesting, because it opens up your MIDlet

to the outside world, is via the Internet. After all, what good is your MIDlet

if the rest of the world cannot see it? Of course, this means that your device

should be able to connect to the Internet using its internal browser.
Before you proceed further, recall that when you created the JAD file, you

entered two attributes in it that specified the version of CLDC (1.1) and MIDP

(2.0) for which the MIDlet was created. Since the DateTimeApp MIDlet does not

use any of the features of these versions, it should theoretically run on devices

that support the lower versions of these attributes, as well. Therefore, the

DateTimeApp MIDlet should run on CLDC 1.0 and MIDP 1.0, but because the JAD

file restricts these versions to the newer ones, devices will fail to install

this MIDlet if they do not support these new versions. If this is the case with

your device, fear not! As I said before, because we are not using any MIDP-2.0-

or CLDC-1.1-specific features, you can simply change these version numbers in

the JAD file, and this will be sufficient to install this device on all Java-enabled devices. If this is the case with your device, or the device that you

are going to test this MIDlet on, simply change these values in the JAD file

and you are good to go.
To be able to deploy your MIDlet via the Internet, you need to have access

to a web server with a real-world IP address or domain name. You also need to

have administrative privileges to be able to modify the configuration files

of your web server to add some Multipurpose Internet Mail Exchange (MIME) types

for the JAD and JAR extensions. If you are using Jakarta/Tomcat as your web

server, you don't need to do this, as it already has these MIME types. For the Apache

web server, modify the mime.types file and add the following extension types.
text/vnd.sun.j2me.app-descriptor jad
application/java-archive jar

By adding these MIME types, you are informing the browser, or any

client accessing these files from the server, how to handle these files when they

are downloaded into the device.
Next, create an HTML file that will become the point of reference. Strictly,

this is not necessary, because a device that can access an HTML page can also

access a JAD file. But an HTML page provides a point of reference, and therefore,

let's create one for your Date-Time MIDlet. The HTML doesn't need to be anything

fancy. Don't forget that users will be accessing this page via a mobile device,

so it is prudent to keep the size of this page to the minimum. This is shown

in Listing 2.

lt;HTMLgt;
 Click lt;a href=DateTimeApp.jadgt;herelt;/agt; to download DateTimeApp MIDlet!
lt;/HTMLgt;

Listing 2. DateTimeApp.html page for accessing the DateTimeApp MIDlet
The page provides a link to the JAD file, and the JAD file provides a link

to the associated JAR file via the MIDlet-Jar-URL: DateTimeApp.jar

attribute. However, since this is now going to be accessed via a web server

over the Internet, it is advisable to make this link absolute instead of relative.

(The behavior of relative URLs is inconsistent as far as MIDlet access is concerned.)

Since I am going to serve this MIDlet via a web site (Craftbits.com)

I manage, I have modified this link to an absolute URL using this web site.
MIDlet-Jar-URL: http://www.craftbits.com/j2me/DateTimeApp.jar
You will, of course, need to change this URL to your own domain.
Finally, upload the modified JAD file, the newly created HTML file, and the

original JAR file to your web server to a directory location where you will

be able to navigate to the HTML page via your mobile device browser. Now, anyone

with a mobile device that can browse the Internet should be able to point to

your DateTimeApp.html file and download, install, and run the DateTimeApp MIDlet.
For those who don't have access to a web server, I have uploaded these files

to my web server. Simply point to http://www.craftbits.com/j2me/DateTimeApp.html

through your device and you will be able to see this MIDlet in action.
That's it! You have completed all the steps required to manually create and

deploy a MIDlet. This process has helped you to understand what goes on behind

the scenes and given you confidence in all the steps of MIDlet creation. Because

a lot of these steps are repetitive, it makes sense to use an automated tool.

This is where the Wireless Toolkit comes in, and you will use it to create the

rest of the MIDlets in this article series. For the moment, let's recreate the

same MIDlet using this Toolkit so that you can get familiar with its interface.

">

Understanding the Process of MIDlet Creation--Using the Toolkit

In the section Acquiring and Installing J2ME Development Kit above, you

downloaded the Toolkit and installed it in the folder C:\WTK22 (as far as this

article series is concerned; you may have downloaded and installed it in a different

folder). Let's explore the contents of this folder. Figure 4 shows these contents

as they should now look on your machine.

Figure 4. Wireless Toolkit folder contents
Note that the default installation of the Toolkit would not have created

the article folder, and that you created it in the previous

section.
As far as a MIDlet developer is concerned, the most important folders are the

apps and bin folders, but here is a short summary

of each of these folders.

Folder Name	Folder Description
appdb	Directory that acts as a simulation for mobile device file system
apps	MIDlets created using the Toolkit reside in this directory
bin	Contains executables for the various tools, including the Toolkit itself, and various other tools like the preverifier and the emulator
docs	The Wireless Toolkit documentation including API documentation for MIDP 2.0 and MIDP 1.1
lib	Contains the JAR files for MIDP (both 2.0 and 1.1), CLDC (both 1.1 and 1.0) and several other optional libraries
sessions	Directory where network and profiling sessions are maintained
wtklib	Contains the libraries for the Toolkit itself, including the properties of various device emulators