Developing Java ME applications in BlueJ - a Tutorial


Note for users of the Java ME SDK

The names used by this toolkit for critical Java ME libraries have been changed by the SDK developers. See below for details of how to use BlueJ for Java ME development with the new (3.0) SDK.


From version 2.5.0 onwards, BlueJ includes facilities for developing Java ME applications (called MIDlets) which will run on devices like mobile (cellular) phones. To do this, BlueJ makes use of external standard libraries and device emulators from the Sun Java Wireless Toolkit (WTK), which must be downloaded and installed in order to enable this behaviour. This document describes how to setup BlueJ for use with Java ME applications, how to customise BlueJ's use of those tools, and some of the limitations of the current implementation.


Technically, the particular flavour of applications BlueJ supports are called Java ME CLDC/MIDP MIDlets. These will run on any Java-enabled mobile phone, or on the emulator included with the Wireless Toolkit. Because the WTKM is currently only available on Linux and Windows, BlueJ can only be used to create MIDlets when running on Linux or Windows systems.

Support for MIDlets in BlueJ is at a similar level to the historic support for applets:

Because the JUnit testing framework which BlueJ uses for Unit Testing relies on reflection in Java, which is not part of Java ME, BlueJ's unit testing facility is not available in Java ME projects.

Emulator and Library Setup

Before using BlueJ to develop a Java ME project, you must download the Sun Java Wireless Toolkit for CLDC and install it on your system.

Once you have done that, open BlueJ and go to the Miscellaneous Preferences panel (Tools/Preferences .../Miscellaneous) and tick the Show Java ME controls checkbox. When you do that, BlueJ will attempt to find a Wireless Toolkit for you, and fill in its location. If it can't find one (which should only be if you have installed it in an unusual place, or you have more than one Toolkit installed), you can press the Browse button to find it yourself.

BlueJ Miscellaneous Preferences Panel

That's all. You are now ready to create and run Java ME projects.

Creating a Java ME project

The only visible change in BlueJ when you selected Show Java ME controls is the addition of an extra item New ME Project ... on BlueJ's Tools menu. This creates a new BlueJ project, and tags at as being a Java ME Project. Choose an appropriate folder, and create a project called Hello. You should see a normal BlueJ project window, except with a new button in the left-hand column: Deploy. We will use this later to run the MIDlet we are creating. Click on the New Class button.

New Class dialog

Note that in the New Class dialog you can create  MIDlet, Class, Abstract Class, and Interface classes, but not Applet, Unit Test, or  Enum classes, which don't exist in Java ME.

Create a MIDlet class, and call it Hello. Note that the class created is stereotyped as a <<MIDlet>>

The class created is the bare bones of a Java ME MIDlet. It will compile, and can be deployed to a phone or the WTK emulator, but it doesn't do anything. To turn it into a simple Hello World application, you need to do the following (or just download the whole class source code):

You should now be able to compile your MIDlet and move on to running it.

Running a Java ME project

Before you can run a Java ME application, you must send it to an appropriate device (called "deployment"). the only device which BlueJ knows about is the emulator which is part of the Wireless Toolkit. BlueJ allows you to deploy directly to that emulator, or to simply create the files (called jad and jar files) which can be deployed to real devices (in ways which are beyond the scope of this tutorial).

Use the Deploy… button in the BlueJ window (above the progress bar) or the Deploy… menu item in the Project menu. The Java ME Deploy dialog, containing data for the jad and jar files, pops up with default values which you can edit. Only the MIDlet class name is not editable. BlueJ saves your changes for subsequent deployments. The MIDlets listed in the dialog are all the MIDlets in your suite.

Deployment dialog

The Move Up/Down buttons let you change the order in which the MIDlets get written to the jad file (there's only one in this project, so the buttons are disabled). The Exclude button lets you remove a MIDlet from the jad file, but it does not remove it from the BlueJ project so that you later have the option of putting it back with the Include button.

The MIDP specification requires that the MIDlet suite name, version, and vendor not be blank. Therefore, if you blank out these fields BlueJ assigns default values to them in the jad and jar files.

You don't need to change anything at this stage, so just press OK, and (after a short pause) the emulator will be displayed, looking (something) like a standard mobile phone. To start your Java ME application, press the launch key (with your mouse).


Details and Gotchas

Compiler and library settings

You can change the Java ME libraries which BlueJ uses by changing properties in the file bluej.defs (global change) or (this user only). Change the two properties below if you want to use different core MIDP or CLDC libraries, and/or if you want to specify optional libraries.

bluej.javame.corelibraries=midpapi20.jar cldcapi11.jar

If you are using the Java ME SDK 3.0 (or later?) you will need to change the corelibraries property anyway, because the names of the Jar files have been changed to midp_2.0.jar and cldc_1.1.jar.

Note that above and below these two properties you can also add options for the compiler, emulator, and the preverify command:

bluej.javame.compiler.options=-source 1.4 -target 1.4

Any output generated by setting these options will appear in the BlueJ log file bluej-debuglog.txt.

Java ME Project Structure

A BlueJ Java ME project contains a MIDlet suite. The directory of a newly created ME project contains the usual files, in addition to  res/icons/default.gif,  the default icon for MIDlets.

To change the default icon file that BlueJ uses when creating new ME projects, replace the file  me-default-icon.gif  in the directory  lib/images  in your BlueJ installation. Change the file contents—but not the name—as this is the file that BlueJ copies into  res/icons/default.gif when BlueJ creates a new ME project. Delete default.gif if you don’t want a default icon.

Note that when you change an icon, whatever file you choose as the new icon gets copied into directory res/icons—if it is not already there—given that BlueJ assumes that this directory contains all the icons for your suite. You could also put into this directory all your icons before deploying so that you don’t have to search for them through the Deploy dialog .

The jad and jar files, which represent the deployable application, get written to the project directory. BlueJ writes to the jar file the entire contents of directories res and +tmpclasses. The latter contains the preverified class files. Only the three attributes name, version, and vendor get written to the jar’s manifest, and these are a duplicate of the values written to the jad file.

When deploying, BlueJ also creates file  MIDlet.defs for its own internal use. This contains data from the Deploy dialog. You would only want to delete this file if you wanted to entirely reset this dialog to its default values.

Where BlueJ looks for emulators and libraries

In Windows BlueJ searches for the toolkit in all the file system roots, and in Linux it searches the directory named in the System property user.home, as well as the "standard" directories /usr/local and /usr/lib. BlueJ searches only one level down from each root. That is, it can find C:\WTK2.5.1 but not  C:\mydir\WTK2.5.1, or /usr/local/WTK2.5.1 but not /usr/local/mydir/WTK2.5.1 Note that BlueJ stops searching once it finds the first directory that satisfies the requirements of being a Wireless Toolkit.

Using other emulators and libraries

BlueJ supports Java ME project development using an external device emulator and associated libraries. Extensive testing has been done using the Sun Java Wireless Toolkit, but it should also work with emulators from other sources (including handset manufacturers) which conform to the Unified Emulator Interface.

Working with older BlueJ versions

If you open a Java ME project in an earlier version of BlueJ (pre-2.5.0) that does not handle Java ME projects, the I-am-an-ME-project flag in the bluej.pkg file gets reset. The result is that this project will not be recognized as an ME project when you re-open it in a later version of BlueJ. The fix is easy: using a text editor simply put this flag back in the bluej.pkg file by adding anywhere in the file the line: