Cross-platform programming with Java technology and the IBM Web Services Toolkit for Mobile Devices

Make sure your Java apps run on as many platforms as possible without modification

When you're writing a Java application for the server or desktop, you can be reasonably sure that the Java platform will fulfill its "Write Once, Run Anywhere" promise. But when you're dealing with code that will run under the J2ME Mobile Information Device Profile (MIDP), things get a little trickier. If you've downloaded the Web Services Tool Kit for Mobile Devices (WSTKMD) and are eager to write mobile Java web services, you'll need to check out the warnings in this article(see Resources). Peter Haggar describes some of the pitfalls he encountered in making sure that the WSTKMD's sample applications ran on all the target platforms.


Peter Haggar, Senior Software Engineer, EMC

Peter Haggar is a senior software engineer with IBM in Research Triangle Park, NC, and is the author of Practical Java Programming Language Guide (Addison-Wesley, 2000). In addition, he has published numerous articles on Java programming. He has a broad range of programming experience, having worked on development tools, class libraries, and operating systems. At IBM, Peter works on emerging Internet technologies and is currently focused on high-performance and mobile web services. Peter is a frequent technical speaker on Java technology at industry conferences. He has worked for IBM for more than 15 years and received a BS in computer science from Clarkson University. Contact Peter at

18 February 2003

The IBM Web Services Tool Kit for Mobile Devices (see the Resources section below for a link) supports the Java programming language on BlackBerry ™ devices, PocketPC™, and Palm OS4™ mobile devices; on the Palm OS4 platform, it also supports the C programming language. The Java language is touted as a cross-platform environment, with which code can be written once and run on a variety of operating systems without modification. While this is largely true in desktop and server environments, writing Java applications for mobile devices utilizing MIDP (the Mobile Information Device Profile) is not as straightforward.

The sample Java applications that ship with the toolkit run unmodified on all supported devices. However, there the devices have different user interfaces (UIs), and the apps thus have different UIs on the different devices. We took great care to ensure that each Java application would run unmodified on each supported device. This proved more difficult than we first imagined, due to the lack of consistency among the various MIDP implementations, along with differences in the various devices' user interfaces.

In this article, I'll outline the issues that you need to consider, and the programming constructs and style you should use, to ensure that your Java programs can run, unmodified, on each device supported by the IBM Web Services Tool Kit for Mobile Devices.

MIDP programming

The MIDP programming environment offers a very limited amount of functionality to the programmer. In addition, MIDP has been implemented differently on different devices. Therefore, you cannot program to MIDP and assume that your application will look and behave consistently in varying environments. For example, the MIDP GUI library does not support a single class for buttons. You can draw buttons natively, or you can rely on each individual MIDP implementation for each device to provide buttons for your menu items.

When creating the sample applications for the Web Services Tool Kit for Mobile Devices, we avoided certain user interface classes in order to ensure that each program would run on each device. When you are preparing your own code for this purpose, you need to accept the fact that your application will have a different interface on different devices. Furthermore, the user of the application will interact with it differently depending on the device on which the program is run.

Device differences

The user interacts with each of the devices I'll discuss here differently, due to their differing designs. For the purposes of this article, I'll describe the differences between the devices I worked with during the development of the tool kit: the Palm i705 Handheld running Palm OS4, the Compaq iPAQ 3670 Color Pocket PC running Pocket PC 2002, and the BlackBerry 5810 Handheld running BlackBerry OS 3.2 platform, a Java language operating system. Understanding these differences was key in developing an application that ran on all the devices.

Note that the IBM J9 Virtual Machine that runs on Palm OS4 platform does not support the INETLIB networking library on the Palm i705 device. Therefore, there is no way to make a network call with this VM on this device, and thus the Web Services Tool Kit for Mobile Devices does not support the Palm i705 Handheld. (Other Palm OS4 devices are supported.) However, non-networking applications can still run on the Palm i705 Handheld to help pinpoint user interface issues that arise with Palm OS4 devices.

  • Palm i705 Handheld: The user interacts with this device via a touchscreen. Menus are also available but are accessed via the menu button provided by the device.
  • iPAQ 3670 Color Pocket PC: The user interacts with this device via both a touchscreen and a five-way hardware button on the bottom of the device. As you'll see, the touchscreen does not work with all GUI controls available in MIDP, making your choice of GUI control important.
  • BlackBerry 5810 Handheld: The user interacts with this device via a trackwheel and a hardware selection button. This device does not support a touchscreen and is therefore completely menu driven. Because there is no touchscreen, the process of selecting items is different than it is on the other devices. You use the trackwheel to change the highlighted item, then use the menus or the spacebar to select the highlighted item.

User interface differences: Menus and buttons

Some of your design decisions are going to be based on the inherent differences in the devices, as well as the differences in how data is rendered by the different MIDP implementations. For instance, as noted, the BlackBerry device does not have a touchscreen and operates from a menu-driven interface. Therefore, you must design your application to be menu driven if you want it run unmodified on each device.

MIDP contains a Command class that the user can trigger; this class is used to encapsulate operations. Because the BlackBerry device is completely menu driven, all Command objects are displayed as menu choices on its UI. On the other devices, the MIDP implementation determines whether the device displays the Command objects as menu choices or as buttons.

For example, on the Palm i705 Handheld, all Command objects are displayed as menu items. On the iPAQ device, in contrast, they are preferably displayed as buttons; but when there are too many Command objects to fit on the screen, a Menu button is added that, when pressed, displays the remaining Command objects in a menu. In your code, you can determine the order in which these objects appear: when you create Command objects, you create them with a CommandPriority. The lower the number, the higher the priority. On the iPAQ device, the Command objects with the highest priority are given preference to display as buttons rather than menu items.

Because of these differences, when you are designing an application to run unmodified on these various devices, it is important to design the application's flow around the Command class and accept that your Command objects will display either as buttons or menu items depending on the device characteristics.

User interface: Differences in List implementations

The differences in GUI controls' appearance on various devices of the sort we just described is to be expected; you can plan around such differences without too much difficulty. However, the differing behavior of the same control across devices is cause for more concern.

For example, the List control displays a list of items to be selected. The user is presented with a list of text and/or images. The user can make a selection, and the application takes action based on the item(s) selected. The List control supports three types: Multiple, Exclusive, and Implicit. According to the documentation for MIDP (see Resources), List types work as follows:

  • The user can use a List of type Multiple to select one or more items. However, the process of selecting the items does not in itself generate a selection event. The user must take another action, like pressing a button or activating a menu choice, before the program queries the list to determine what item(s) were selected.
  • A List of type Exclusive allows the user to select only one item. However, as with the Multiple-type List, the user doesn't generate a selection event by changing the selected item. The programmer must provide a button or menu choice to enable the user to confirm the choice made; activating this choice or button prompts the program to query the List and determine which item was selected.
  • The Implicit-type List is the only List that is supposed to automatically generate a selection event when an item in the List is selected. Only one item may be selected at a time, and each time the selection item is changed, a selection event is automatically generated.

Unfortunately, as implemented on the three platforms I'm describing here, the List control does not always demonstrate the behavior documented for it. Furthermore, the behavior of the List control differed from platform to platform, making it impossible to use this control in any cross-platform applications. Let's look at these inconsistencies in detail.

List control on Palm OS4 devices

Under Palm OS4 platform, each time you select an item in a Multiple- or Exclusive-type List, a selection event is generated. This behavior is not consistent with the MIDP documentation.

For an Implicit-type List, at no time are selection events generated. To use this type of List under Palm OS4 platform, you would need to provide a menu item that, when selected by the user, prompts the app to query the list to see which item has been selected. This behavior is also not consistent with the MIDP documentation; a programmer writing an application to the MIDP spec would probably not provide such a menu item, thus making the Implicit useless on this platform.

List control on Compaq iPAQ Pocket PC with PocketPC 2002

Under Pocket PC 2002 platform on the Compaq iPAQ device, for both Multiple- and Exclusive-type Lists, no events are generated when you select List items. This behavior is consistent with the MIDP documentation.

For an Implicit-type List, however, there are problems. If you attempt to select an item using the stylus, the iPAQ device's touchscreen will not properly change the item selection. If you use the five-way hardware button, you can select items properly; pressing the center of the five-way hardware button then generates a selection event. This behavior is consistent with the MIDP documentation for List; however, the lack of touchscreen control with this type of List is bothersome, and is most likely a bug in the MIDP implementation for this device.

List control on BlackBerry 5810 Handheld

Because the BlackBerry device does not have a touchscreen, items are highlighted by moving the trackwheel. The user selects the highlighted item by pressing the spacebar or using menu options.

For a Multiple-type List on the BlackBerry 5810 Handheld, no selection events are generated when pressing the spacebar to select an item. In addition, choosing Change Option from the menu has the same effect as pressing the spacebar: It changes the selected item but does not generate an event. This behavior is consistent with the MIDP documentation.

For an Exclusive-type List, no selection events are generated when pressing the spacebar to select an item. However, in contrast with the Multiple-type List, there were no menu items to choose from. This behavior is consistent with the MIDP documentation, though inconsistent with the implementation of the Multiple-type List.

For an Implicit-type List, selection events are generated when you choose Select from the menu. Pressing the spacebar has no effect. This behavior is consistent with the MIDP documentation.

Differing List controls: Can they be reconciled?

The List control behavior differs from device to device. In addition, its behavior on the Palm device is not consistent with its documented behavior. On the iPAQ device, the List control's behavior is consistent with the MIDP documentation; however, the fact that the Implicit-type List does not respond to the touchscreen and requires the use of the five-way hardware button is inconsistent and aggravating. The BlackBerry implementation is also consistent with the documentation; however, the menus available under the three types of List are not consistent. The Multiple type contains a Change Option menu item, the Exclusive type contains no menu items, and the Implicit type contains a Select menu item.

Other MIDP implementations may also provide inconsistent behavior; you should not assume that they all have the same limitations described here.

ChoiceGroup: An alternative to List

Because of the problems associated with the List control on the devices I used, I realized that I could not use that control in a cross-platform application. Instead, I use the ChoiceGroup control to display a list of choices to the user. You can create either a Multiple- or an Exclusive-type ChoiceGroup control. Like their corresponding List types, these types should not generate selection events when the user chooses items. For the sample applications, I used an Exclusive-type ChoiceGroup, since I only wanted the user to be able to make one selection from each list. Then, I provided different Command objects that, when selected, would take action based on which item in the ChoiceGroup was selected.

Multithreaded connections

There is one more trick you'll need to keep in mind in order to have one program execute on all three devices we're considering here. A device running the BlackBerry OS can only make an HTTP connection from a secondary thread and not on the main thread. Palm OS4 and Pocket PC 2002 devices have no such restriction.

I initially attempted to have my applications dynamically determine which device they were running on and create a secondary thread only when running on the BlackBerry platform. However, this technique itself ran into a problem: the System.getProperty("os.version"); call returned a null value on the BlackBerry platform. Under the Pocket PC 2002 and Palm OS4 operating systems, this method call returned valid values; however, I did not want to assume that a null return from a System.getProperty("os.version"); call always implied the need for a secondary thread for HTTP connections.

Therefore, the code for the Palm and Pocket PC device becomes slightly more complicated with the addition of a secondary thread used only to make the HTTP connection. The code in the sample programs shows how this is done. However, if you don't plan to deploy your application to the BlackBerry platform, you won't need to worry about this issue.


Writing one Java application that will run intuitively for the user on Palm OS4, Pocket PC 2002, and BlackBerry OS 3.2 platforms is not as straightforward as desktop or server Java programming. The MIDP environment is not as robust as J2SE or J2EE, and the differences among devices can play havoc with your cross-platform plans. You need to take care to ensure that the GUI controls you use work properly and somewhat consistently on each deployed platform. In addition, the user interface requirements must not exceed the various devices' capabilities.

To some extent, you must take a least-common-denominator approach and work around the various characteristics and limitations of your target devices to create an application that is usable on each of them. In addition, you might have to add complexities that are unnecessary on some platforms in order to satisfy the requirements of others. For example, the addition of a secondary thread for HTTP connections for BlackBerry OS platforms makes code more complex than necessary for Palm OS4 and Pocket PC 2002 devices.

In the end, it is worth putting in the additional work and complexity to have one application run on multiple devices. Doing so reduces code maintenance and the time and effort needed to track multiple versions of the same application. Furthermore, this approach takes advantage of the cross-platform features of the Java programming language. Over time, as J2ME and MIDP improve, the differences between the various MIDP implementations and their behavior on the various devices will diminish. This will result in an easier and more straightforward path to cross-platform J2ME and MIDP development.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into SOA and web services on developerWorks

Zone=SOA and web services
ArticleTitle=Cross-platform programming with Java technology and the IBM Web Services Toolkit for Mobile Devices