J2ME MIDP and WAP Complementary Technologies

Print-friendly Version

by Qusay H. Mahmoud
February 2002

The Wireless Application Protocol (WAP) is an open specification that addresses wireless network characteristics by adapting several data-handling approaches already in use by Web protocols, and introducing new ones, where appropriate, to the special requirements of handheld wireless devices. The reuse of existing Web technologies eases the development of WAP applications, and make it similar to developing HTML-based Web applications since it is browser-based.

Another approach to developing wireless applications is to use the Java 2 Micro Edition (J2ME) Mobile Information Device Profile (MIDP). MIDP is also an open specification that adapts existing technologies such as Java and the Web. Developing MIDP-based applications (also known as MIDlets) is similar, but not identical, to developing Java Applets in the sense they share a similar programming model.

In either approach, Java plays an important role. In WAP, Java servlets and JavaServer Pages (JSPs) can be used to generate dynamic WAP content on the fly (not to mention that most WAP development tools are actually written in Java!), and in MIDlets, Java is the programming language for developing them.

WAP and MIDP are not competing technologies, however. They are in fact complementary technologies as you will see here. If you are new to WAP, please see WAP for Java Developers, and if you are new to MIDP please see Getting Started with MIDP.

This article presents a brief overview of the WAP and MIDP programming models, then it:

• Gives a flavour of the effort involved in developing WAP applications and MIDlets
• Shows how to rewrite existing WAP applications as MIDlets
• Provides a look into how WAP and MIDP will be integrated together

The examples throughout this article were developed using Ericsson's WapIDE and Sun's J2ME Wireless Toolkit.

Programming Models

The programming model of both, WAP and MIDP are in many ways similar to existing programming models such as the Web and Java.

The WAP Programming Model

The WAP programming model is similar to the Web programming model with matching extensions for accommodating the characteristics of the wireless environment. Figure 1 illustrates the WAP programming model.

Figure 1: The WAP Programming Model

As you can see, the WAP programming model is based heavily on the Web programming model. While WAP was not designed to use HTML, in some cases the data services or content located on the Web server is HTML-based. Some WAP gateways are capable of converting HTML pages into a format that can be displayed on wireless devices. But because HTML wasn't really designed for small screens, the WAP protocol defines its own markup language, the Wireless Markup Language (WML), which adheres to the XML standard and is designed to enable powerful applications within the constraints of handheld devices. In most cases, the actual application or other content located on the Web server will be native WAP created with WML or generated dynamically using Java servlets or JSPs. WAP 2.0 is moving towards XHTML, which is a reformulation of HTML 4.0 as an XML application.

In HTML, there are no functions to check the validity of user input or to generate messages and dialog boxes locally. To overcome this limitation, JavaScript was developed. Similarly, to overcome the same restrictions in WML, a new scripting language known as WMLScript has been developed.

The basic unit of a WAP application in WML is the card that specifies a single interaction between the user and the user agent. Sample 1 shows the simplest WML document with a single card.

Sample 1: Hello.wml

<?xml version="1.0"?> <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.2//EN" "http://www.wapforum.org/DTD/wml12.dtd"> <wml> <card id="FirstCard" title="First Example"> <p> Hello World </p> </card> </wml>

When viewed on a WAP-enabled phone, Sample 1 is rendered and displayed as shown in Figure 2.

Figure 2: The output of Example1.wml

The MIDP Programming Model

The MIDP programming model is a mix of the Java programming model and the Web programming model. MIDlets are developed using Java and compiled the same way you compile any Java application. Similar to applets, however, where an applet is described in an HTML file, a MIDlet or a group of MIDlets (known as a MIDlet Suite) is described in a Java Descriptor (JAD) file. while applets run in a Web browser, MIDlets run in a MIDlet management software (which is preinstalled on MIDP devices) that provides an operating environment for KVM and MIDlets where they run. Unlike applets, however, MIDlets do not get destroyed when they finish running. They remain installed on the device until they are explicitly removed.

		Note: It is natural for MIDlets to remain on the device till they are explicitly removed. Therefore, MIDlets remain available for offline usage and in that sense MIDP supports disconnected operations. This is a big plus for entertainment applications such as games!

In MIDlets, the basic unit of interaction is the screen, which encapsulates and organizes graphics objects and coordinates user input through the device. The WML example shown earlier in Sample 1 can be rewritten as a MIDlet as shown in Sample 2.

Sample 2: HelloMIDlet.java

import javax.microedition.midlet.*; import javax.microedition.lcdui.*; public class HelloMIDlet extends MIDlet { // The display for this MIDlet private Display display; // TextBox to display text TextBox box; public HelloMIDlet() { } public void startApp() { display = Display.getDisplay(this); box = new TextBox("First Example", "Hello World", 20, 0); display.setCurrent(box); } /** * Pause is a no-op since there are no background activities or * record stores that need to be closed. */ public void pauseApp() { } /** * Destroy must cleanup everything not handled by the garbage * collector. * In this case there is nothing to cleanup. */ public void destroyApp(boolean unconditional) { } }

Even to the untrained eye, Sample 1 looks much simpler than Sample 2. It is the same idea with HTML-based applications and applets. Applets however, bring dynamic applications to the Web and it is the same thing with MIDlets. But remember, we are not trying to compare WAP applications with MIDlets here; as we mentioned earlier these are not competing technologies but complementing ones.

When running on a Java-enabled phone, such as the Motorola/Nextel i85s, Sample 2 is displayed as shown in Figure 3.

Figure 3: Output of HelloMIDlet

Rewriting WAP Applications as MIDlets

We now look at rewriting WAP applications as MIDlets. The idea however, is not to compare which one is easier but rather to show you the effort involved. We discuss how to rewrite decks, lists, input fields, buttons, and WML with WMLScript.

Decks

Multiple cards are grouped together in decks. A deck is the topmost element of a WML document. When the user agent receives a deck, it activates only the first card in the deck. Sample 3 shows a hypothetical guide for the city of Vancouver that consists for a deck composed of three cards.

Sample 3: CityGuide.wml

<?xml version="1.0"?> <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.2//EN" "http://www.wapforum.org/DTD/wml12.dtd"> <wml> <card id="city" title="Vancouver Guide"> <p> <a title="Food" href="#food">Food</a><br/> <a title="Education" href="#education">Education</a><br/> </p> </card> <card id="food" title="Restaurants"> <p> <a title="Canadian" href="#canadian">Canadian</a><br/> <a title="Chinese" href="#chinese">Chinese</a><br/> <a title="Greek" href="#greek">Greek</a><b/> </p> </card> <card id="education" title="Education"> <p> <a title="Schools" href="#schools">Schools</a><br/> <a title="Univerities" href="#universities">Universities</a><br/> </p> </card> </wml>

When viewed on a WAP-enabled device, Sample 3 is rendered as shown in Figure 4a. Once the city card is loaded, you can navigate through it using the soft key on your device. Figure 4b shows what happens when the Food option is selected, and Figure 4c shows what happens when the Education option is selected.

Figure 4a:City Figure 4b:Food Figure4c:Education

Just as a WAP application may consist of multiple cards in a deck, a MIDlet usually consists of several screens, but only one screen at a time can be visible. The WAP application in Sample 3 can be written as a MIDlet as shown in Sample 4.

Sample 4: CityMIDlet.java

import javax.microedition.midlet.*; import javax.microedition.lcdui.*; public class CityMIDlet extends MIDlet implements CommandListener { Display display; List menu; List food; List edu; String currentMenu; static final Command nextCommand = new Command("Next", Command.OK, 2); static final Command backCommand = new Command("Back", Command.BACK, 2); public CityMIDlet() { } public void startApp() { display = Display.getDisplay(this); menu = new List("Vancouver Guide", Choice.IMPLICIT); menu.append("Food", null); menu.append("Education", null); menu.addCommand(nextCommand); menu.setCommandListener(this); mainMenu(); } public void pauseApp() { display = null; menu = null; } public void destroyApp(boolean unconditional) { notifyDestroyed(); } public void mainMenu() { display.setCurrent(menu); currentMenu = "main"; } public void foodMenu() { food = new List("Restaurants", Choice.IMPLICIT); food.append("Canadian", null); food.append("Chinese", null); food.append("Greek", null); food.addCommand(backCommand); food.addCommand(nextCommand); food.setCommandListener(this); display.setCurrent(food); currentMenu = "food"; } public void eduMenu() { edu = new List("Education", Choice.IMPLICIT); edu.append("Schools", null); edu.append("Universities", null); edu.addCommand(backCommand); edu.addCommand(nextCommand); edu.setCommandListener(this); display.setCurrent(edu); currentMenu = "education"; } public void commandAction(Command c, Displayable d) { String label = c.getLabel(); if(label.equals("Next")) { if(currentMenu.equals("main")) { List down = (List) display.getCurrent(); switch(down.getSelectedIndex()) { case 0: foodMenu(); break; case 1: eduMenu(); break; } } else if (currentMenu.equals("food")) { mainMenu(); } else if (currentMenu.equals("education")) { mainMenu(); } } else if(label.equals("Back")) { if(currentMenu.equals("food")) { mainMenu(); } else if(currentMenu.equals("education")) { mainMenu(); } } } }

When running on a MIDP-enabled phone, Sample 4 is displayed as shown in Figure 5.

Figure 5: Output of CityMIDlet

Navigation in WAP and MIDP

As you can see from Sample 3, navigation in the Vancouver city example is done using the <A> tag, which will appear as an option in the soft-key menu and can be selected to move to the next card. On the other hand, navigating between screens in MIDlets is done using commands. In a sense, commands in MIDP are similar to <A> since they are mapped to soft-keys as well but personally I prefer the navigational mechanisms in MIDP much better than WAP. Unlike MIDP, WAP provides an ill-defined navigation and interaction model with some of its hidden navigational paths. Sometimes I get lost between cards and would not know which key do I need to press to get a list of options, for example.

Lists

A list in a WAP application can either be of a single choice or multiple choice type.

Single Choice Lists

In a single choice list, only one option can be selected. Sample 5 shows the WML code for a single choice list.

Sample 5: Pizza.wml

<?xml version="1.0"?> <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.2//EN" "http://www.wapforum.org/DTD/wml12.dtd"> <wml> <card id="Pizza" title="Pizza Mobile"> <p> <b>Pizza Size</b> <select title="Size"> <option>Small</option> <option>Medium</option> <option>Large</option> </select> </p> </card> </wml>

When rendered on a WAP-enabled phone, it looks as shown in Figure 6.

Figure 6: Single Choice List

MIDP supports single choice lists as well. The Pizza example shown in Sample 5 can be written as a MIDlet as shown in Sample 6.

Sample 6: PizzaMIDlet.java

import javax.microedition.midlet.*; import javax.microedition.lcdui.*; public class PizzaMIDlet extends MIDlet { Display display; ChoiceGroup size; Form form; public PizzaMIDlet() { } public void startApp() { display = Display.getDisplay(this); size = new ChoiceGroup("Pizza Size", Choice.EXCLUSIVE); size.append("Small", null); size.append("Medium", null); size.append("Large", null); form = new Form("Pizza Mobile"); form.append(size); display.setCurrent(form); } public void pauseApp() { } public void destroyApp(boolean unconditional) { notifyDestroyed(); } }

When it runs on a MIDP-enabled device, this example is displayed as shown in Figure 7.

Figure 7: Single Choice List in MIDP

Multiple Choice Lists

In a multiple choice list, multiple items can be selected all at once. For example, Sample 7 shows a WML example of a multiple list for selection toppings for a Pizza.

Sample 7: Toppings.wml

<?xml version="1.0"?> <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.2//EN" "http://www.wapforum.org/DTD/wml12.dtd"> <wml> <card id="top" title="Pizza Toppings"> <p> <b>Select Toppings</b> <select title="Toppings" multiple="true"> <option>Mushrooms</option> <option>Black Olives</option> <option>Extra Cheese</option> <option>Pineapple</option> </select> </p> </card> </wml>

When it runs on a WAP-enabled device, it will be rendered and displayed as shown in Figure 8.

Figure 8: Multiple Choice List in WML

The WML Toppings example can be written as a MIDlet. As you can see, all that needs to be done to change from a single choice list to a multiple choice list is to use MULTIPLE instead of EXCLUSIVE. In this example, however, we have used a ChoiceGroup instead of a List just for illustrating the rich family of GUI components available in MIDP.

Sample 8: ToppingsMIDlet.java

import javax.microedition.midlet.*; import javax.microedition.lcdui.*; public class ToppingsMIDlet extends MIDlet { Display display; ChoiceGroup size; Form form; public ToppingsMIDlet() { } public void startApp() { display = Display.getDisplay(this); size = new ChoiceGroup("Select Toppings", Choice.MULTIPLE); size.append("Mushrooms", null); size.append("Black Olives", null); size.append("Extra Cheese", null); size.append("Pineapple", null); form = new Form("Pizza Toppings"); form.append(size); display.setCurrent(form); } public void pauseApp() { } public void destroyApp(boolean unconditional) { notifyDestroyed(); } }

When the ToppingsMIDlet runs on a MIDP-enabled device, it is displayed as shown in Figure 9.

Figure 9: Multiple Choice List in MIDP

Input Fields

Applications may need to input from users. Now we will see an example of a WAP application that requires the user to enter their name and phone number. This is done in Sample 9.

Sample 9: Delivery.wml

<?xml version="1.0"?> <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.2//EN" "http://www.wapforum.org/DTD/wml12.dtd"> <wml> <card id="form" title="Pizza Delivery"> <p> <b>Enter your name and address</b><br/> <input type="text" title="Name: " name="name"/><br/> <input type="text" title="Phone: " name="phone"/><br/> </p> <p> <do type="accept" label="Submit"> <go href="#db"/> </do><br/> </p> </card> </wml>

This example uses another form of navigation -- buttons. When the Submit button is selected, the #db card (which is not shown in this example) will be loaded.

When this applications runs on a WAP-enabled browser, it is displayed as shown in Figure 10a. When the user clicks on the menu, the Submit button shows up and the user can select it as shown in Figure 10b.

Figure 10a: input Figure 10b: Submit button

This example can be written as a MIDlet as shown in Sample 10.

Sample 10: DeliveryMIDlet.java

import javax.microedition.midlet.MIDlet; import javax.microedition.lcdui.*; public class DeliveryMIDlet extends MIDlet { private Display display; private TextField name; private TextField phone; private Form form; private Command submit; public DeliveryMIDlet() { name = new TextField("Name:", "", 10, TextField.ANY); phone = new TextField("Phone:", "", 10, TextField.PHONENUMBER); form = new Form("Pizza Delivery"); submit = new Command("Submit", Command.OK, 2); } public void startApp() { display = Display.getDisplay(this); form.append(name); form.append(phone); form.addCommand(submit); display.setCurrent(form); } public void pauseApp() { } public void destroyApp(boolean unconditional) { notifyDestroyed(); } }

As you can see, MIDP is more explicit in what kind of input is required. For example TextField.ANY signals that any character can be entered, and TextField.PHONENUMBER signals that only digits can be entered. This is useful as on some phones this can be interpreted as when a text field requires a phone number then the phone keys can only be used to enter digits and therefore input can be entered faster. In other words, you do not need to press a key multiple times to get a specific digit.

If you run this MIDlet on a MIDP-enabled device, it will be displayed as shown in Figure 11. In comparison with the WML example, note that in the case of MIDlets the commands are shown on the same screen and therefore there are no hidden paths. This makes MIDlets visible and more user friendly.

Figure 11: Input fields in MIDP

Validating Input with WMLScript

So far we have seen how to rewrite WML applications as MIDlets. The question that may come to mind is what about WMLScript? If a WML page uses a WMLScript page, can this be rewritten as a MIDlet. The answer is yes.

The example we will now look at is a login application that asks the user to enter a password. If the user enters the right password, the application displays a new screen. If the user enteres an incorrect password, a dialog box is displayed asking the user to try again. The WML code for this application is shown in Sample 11, and the WMLScript code (which is responsible for checking and verifying the input) is shown in Sample 12.

Sample 11: login.wml

<?xml version='1.0'?> <!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN" "http://www.wapforum.org/DTD/wml_1.1.xml">> <wml> <card id="passwd" title="password:"> <p> Enter Password: <input type="text" name="passwd"/> </p> <do type="accept" label="GetIn"> <go href="login.wmls#validatePASSWD($(passwd))"/> </do> </card> <card id="Results" title="Results:"> <p> You entered: $(passwd)<br/> </p> </card> </wml>

The WMLScript code is shown in Sample 12.

Sample 12: login.wmls

extern function validatePASSWD(passwd) { if (String.toString(passwd) == "99") { WMLBrowser.go("login.wml#Results"); } else { Dialogs.alert("Error; login incorrect. Try again!"); } };

When you run this application on a WAP-enabled device, you see something similar to Figure 12a. If the user provides an incorrect password, you see something similar to Figure 12b.

Figure 12a and 12b: correct password and incorrect password dialog

This login application can be written as a MIDlet as shown in Sample 13.

Sample 13: LoginMIDlet.java

import javax.microedition.midlet.MIDlet; import javax.microedition.lcdui.*; public class LoginMIDlet extends MIDlet implements CommandListener { private Display display; private TextField password; private Form form; private Command login; public LoginMIDlet() { password = new TextField("Password:", "", 10, TextField.PASSWORD); form = new Form("Login"); login = new Command("GetIn", Command.OK, 2); } public void startApp() { display = Display.getDisplay(this); form.append(password); form.addCommand(login); form.setCommandListener(this); display.setCurrent(form); } public void pauseApp() { } public void destroyApp(boolean unconditional) { notifyDestroyed(); } public void validateUser(String password) { if (password.equals("99")) { TextBox tbox = new TextBox("Results:", "You entered: "+password, 40, 0); display.setCurrent(tbox); } else { Alert error = new Alert ("Error: login incorrect", "Try again!", null, AlertType.ERROR); error.setTimeout(Alert.FOREVER); display.setCurrent(error, form); } } public void commandAction(Command c, Displayable d) { String label = c.getLabel(); if(label.equals("GetIn")) { validateUser(password.getString()); } } }

If you run this application, you will see something similar to Figure 13a (user provided correct password) and Figure 13b (user provided incorrect password).

Figure 13a: correct password Figure 13b: incorrect password

As you might be able to figure out, as applications get more sophisticated there won't be really much difference in the amount of code to be written.

		Note: To give your application a professional look and feel, you may wish to associated icons with error or confirmation messages. This can be done in both WAP and MIDP, but it is worth noting that WAP supports wireless bitmap (WBMP) format and MIDP supports the non-patented Portable Network Graphics (PNG) format.

WAP and MIDP: what can they learn from each other?

WAP and MIDP solve similar problems but each can learn a couple of things from the other. There are special features that are available in WAP but not in MIDP and vice versa. Here, I summarize the important features:

• WAP has support for additional phone functionality such as setup and integration with address book. Despite the fact that not all WAP-enabled devices support this feature, there are no comparable APIs available for this in MIDP. It is very likely that this will be possible in future version of MIDP.
• In addition to the MIDP high-level graphics APIs used in this article (such as Form, List, ChoiceGroup, and others), MIDP provides a low-level graphics APIs that enable the programmer to have control over every pixel of the device's display. This is important for entertainment applications (such as games) in a wireless environment.
• Speaking of entertainment applications, MIDP is the way to go for this. The very nature of MIDlets (they exist on the device till they are explicitly removed) allow users to run them even when the server becomes unavailable (support for disconnected operations).
• The WML provides the tags and the possible presentation attributes, but it doesn't define an interaction model. For example, WML defines a SELECT element for providing a list (as shown in Samples 6 and 7). Some WAP-enabled devices interpret the SELECT tag as a popup menu list while others interpret it as a menu that can be used for navigation. Therefore, there is no standard interaction model defined for this element. If a developer uses it, the application may run well on some devices and poorly on others. MIDlets, on the other hand, provide a clearly defined standard for interaction using commands.

Integrating WAP and J2ME MIDP

As mentioned earlier, WAP and MIDP shouldn't be viewed as competing technologies but rather as complementing ones. If you have any experience working with MIDlets, and more importantly downloading MIDlets on real physical devices (such as the Motorola/Nextel i85s cellular phone) then you might be aware that MIDlets are not currently being provisioned over the air. In order to facilitate over the air provisioning, there is a need for some kind of an environment on the handset that allows the user to enter a URL for a MIDlet Suite, for example. This environment could very well be a WAP browser.

Therefore, similar to Java Applets that are integrated in HTML, MIDlets can be integrated into a WML page. The WML page can then be called from a WAP browser and the embedded MIDlet gets installed on the device. In order to enable this a WAP browser (with support for over the air provisioning) is needed on the device. Another alternative approach for over the air provisioning is the use of Short Message Service (SMS) as have been done by Siemens where the installation of MIDlets is accomplished by sending a corresponding SMS. If the SMS contains a URL to a Java Descriptor (JAD) file specifying a MIDlet Suite then the recipient can install the application simply by confirming the SMS.

Conclusion

This article discusses the programming model of WAP and MIDP and shows how WAP applications can be rewritten as MIDlets. The examples shown throughout the article illustrate that any WAP application can be rewritten as a MIDlet or a MIDlet Suite. MIDP provides a rich set of APIs for constructing MIDlets and provides an excellent navigational and interaction model.

MIDlets combine excellent online and offline capabilities that are useful for the wireless environment, which suffers from low bandwidth and network disconnection. Integrating WAP and MIDP opens up possibilities for new wireless applications and over the air distribution models.

For more information

• J2ME
• MIDP
• J2ME Wireless Toolkit
• WAP Forum
• Over the air provisioning
• Midletcentral (over the air provisioning using OTA server)