This article is aimed at competent Java programmers who’re looking to write applications for the J2ME platform. Some AWT experience at least of using the Graphics class would be useful too.

The Java 2 Micro Edition or J2ME/Java ME provides a Java programming environment for consumer electronic products. This is quite an exciting development if you are a closet geek like me because it means that a mobile phone for example, is now a potential target environment for my Java programs rather than just the desktop machines or servers they currently get deployed on.

Any mobile phone manufactured after 2002 will likely have some implementation of the Mobile Information Device Profile (MIDP) on it. Most phones will also support “OTA” downloads which means that
once you’ve written an application getting the thing onto the phone is no harder than pointing your phone at a URL. With all this in mind I decided to try my hand at writing a Java application for my own mobile phone (a motorola c650) and this article explains how I did it.

I decided and interesting and (vaguley) useful application to write would be a program to solve Sudoku puzzles. If you haven’t heard of Sudoku then it’s a fun puzzle with simple rules that appears in most daily newspapers here in the UK. You can find out all about it here http://www.sudoku.com
here is a good site for daily puzzles etc Sudokusan

What do I need to write my program ?

Probably a good IDE e.g. netbeans mobility pack would do it, and you can download other spcific development toolkits for each mobile phone (e.g. visit here for motorola
specific development kits).

However, probably the easiest way is to get the Wireless Development Toolkit from Sun. This is free to
download and you can get it from here

Note – you will need to have at least JDK 1.4.2 or higher to run the toolkit, but that’s free too and you can get it here.

An overview of the MIDP API.

It may be useful at this stage to find out what version of the API your phone will support
this will probably be available via your phone settings. The application described here requires
at least MIDP 2.0.

A Java application for a J2ME platform differs slightly from a server or client app, but not drastically. The API is cut down, most notably if you’re used to the Collections
framework then you’ll be upset since this is not available. A vector and a hashtable are provided however and with a bit of imagination you can easily get round the API limitations. The only
other major thing to get used to is the GUI API, as you might imagine, this is quite different from what you may be used to in standard Java, but it is really quite intuitive.

Like most other Java frameworks, MIDP applications are not “stand alone”, they are invoked by the platform on which they run. This is exactly analagous to an Applet or a Servlet. The same goes here then, when the mobile phone user selects your application, the phone software will invoke it. This happens at a cleanly defined point, in this case it happens in a class called a “MIDlet”.

A Midlet is the MIDP equivalent of a J2EE Servlet. It sits passively waiting to be started by the container, when the container has decided to run the application it will call the “startApp” method on the MIDlet subclass that implements the application.

But where do I start ?

OK – at this point if you’re still reading, hopefully you can program in Java and you know what
Sudoku is. Now we’re off, I’ll explain the other API’s as we use them. First though, lets summarise
what the application will do :-

1) Display a 9×9 grid which will allow the user to enter numbers as they appear in the puzzle.
2) Solve the puzzle for the user.

After installing the Wireless toolkit, we need to create a new application. We do this by choosing “File” and then “New Project”. Next we’ll be asked for a Project name and a “MIDlet class name” ?

But I haven’t written any code yet – why does it want a class name ?

Don’t worry just yet – I’ll explain this later. Besides, we can always change this if we decide we don’t like the name. For the time being lets call the project “Sudoku” and call the MIDlet “sudoku.midlet.SudokuSolver”.

Observant readers will notice that this implies a package called “sudoku.midlet”. Now if we take a look beneath the the WTK installation directory and then “apps”, we can see that a folder has been created called “Sudoku”. This is for our new application. The directory called “src” is where we have to put our code. We’ll start with the MIDlet.

What should the MIDlet do ?

Well, this all depends on on how you want to write your program. In our case the MIDlet will decide which commands the user can invoke, what happens when they are chosen, and what Screen they are available on. The MIDlet will also decide which screen the user sees at first.

What about the MIDP API for creating GUIs ?

This lives in a package called javax.microedition.lcdui, the central abstraction here is Displayable.

As you can see from the above diagram, there are two types of displayables, on the left we have Canvas and on the right Screen. Leaving aside the differences between these for time being, the important point to make here is that MIDP GUIs consist of a single screen at a time. That is, only one “Displayable” can be showing at any given time. The job of the programmer is then to decide what screen is showing at any time, and to set the current screen probably in response to user selections. You use the “Display” class to act as a manager, it sets the current Displayable using Display.setCurrent().

In the SudokuSolver MIDlet – we declare the following member variables :-

/* The game. */
SudokuGrid game = new SudokuGrid();

/* The canvas subclass which renders the grid and the numbers */
SudokuCanvas gridPanel = new SudokuCanvas(game);

The SudokuCanvas class is a direct subclass of Canvas. A Canvas lets you customise the contents of a Displayable
entirely, subclasses of Screen on the other hand are higher lever controls such as lists and textboxes. We want
to display a 9×9 sudoku grid which reflects the contents of the game model. The SudokuCanvas class is used to actually
paint the 9×9 grid and render the numbers. Next we need to set the list of commands that a user can choose from when a
displayable is showing. We do this by adding commands the Displayable…voila :-

Here we add a list of commands (declared as private members of the MIDlet) to the SudokuCanvas. We also declare the
the MIDlet will listen out for those commands being chosen by making it implement the “CommandListener” interface. The
Splash screen simply displays a welcome screen.

How do I run my application ?

This is easy. Once we’ve finished editing our source, we click the “build” button which will compile all the code, after
that you run it on the selected device. So you should see the following (the default colour phone) :-

To package the application and get it on your phone, follow these steps :-

1) Choose Project/Package/Create Package
2) Look in the bin directory, copy the two files .jad and .jar
3) Put them on a webserver !

The next article will explain how all the drawing works, and how the solver
actually solves the grid, but this should have covered the basics.

NB – you may find that some phones HTTP protocol handling software is more picky than others, therefore you may need to
configure the webserver to report the correct MIME type for a JAD file. Motorola phones don’t seem to mind about this though.

Subscribe

Steven Wood's Blog syndicates its weblog posts
and Comments using a technology called
RSS (Real Simple Syndication). You can use a service like Bloglines to get
notified when there are new posts to this weblog.