English  Español  Português  Français  Italiano  Deutsch  Nederlands  Svenska  Dansk  Suomi  Norsk  Русский  Polski  Română  Български  Hrvatski  Česky  中国  中國  日本語  한국어  Ελληνική  हिन्दी  العربية 

J2ME software development for cellular phones

(2002)

Colin Fahey

This document is obsolete!  The information in this document might have been valid and useful in the year 2002, but many things have changed in subsequent years!  This document should now only be regarded as an interesting historical record of the year 2002.  Do not rely on any information or advice in this document.  All technical information in this document is very obsolete. 

Downloading self-created software, self-created images, and self-created telephone alert melodies (i.e., "ring tones"), was relatively rare and difficult in the year 2002.  Sadly, six years later, some cellular phone service providers (including Apple, which provides the exclusive software and "ring tone" portal for the iPhone) still impose restrictions on downloading software, images, and music, because cellular phone service providers enjoyed extremely large financial profits by controlling these types of downloads. 

Fortunately, cellular phones such as those featuring the "Android" software platform, will forever end the ability of companies to create and exploit closed markets for such uses of cellular phones.  Although consumers willingly purchased cellular phone service plans that included very high costs for downloading software, images, and music, this is because of the limited number of cellular phone service options available. 

The economic dynamics that have enabled certain companies to grow to dominate the market should not be interpreted as implicit strong approval by the consumers.  As companies start to dominate, and then make it difficult or impossible for competitors to enter the market, the dominating companies can offer products that combine high positive value (e.g., the ability to communicate from anywhere) with high negative value (e.g., high prices for desirable software, images, and music, all of which would otherwise be freely available; thus, the service adds negative value).  No consumer is forced to purchase a cellular phone, but there is no doubt that the dominant cellular phone service providers have gradually created conditions that can not be considered a "free market".  Therefore, the cellular phone service market has been economically "inefficient" and has been an undue burden on consumers. 

Hopefully, requirements that cellular phone service radio frequencies be available to competing services will restore normal market values to data transfer, such that cellular phone service providers are again reduced to mere carriers of data (i.e., only providing bandwidth) rather than information or entertainment providers! 

The business of transporting data must be separated from the business of selling data, otherwise there will be an incentive for the data transportation business to block competitors from selling data through the same data transportation channel. 

The video game console market suffers from the same problem.  The manufacturers of video game console hardware are in the business of creating devices that can display video games, but those same companies also have exclusive control of the transfer of software to those video game consoles.  Therefore, there is an incentive for the video game console manufacturers to block competitors from selling software for the video game consoles.  If a video game console hardware manufacturer focused on designing and manufacturing hardware that could be sold at a profit (instead of at a significant loss, as with the X-Box and PlayStation and Nintendo video game consoles), then the video game market would thrive, and the quality of the best video games would dramatically improve, and the cost of video games would collapse. 

This section describes how to download development tools that can be used to compile J2ME source code in to class files suitable for mobile devices.  Note that the Sun "J2ME Wireless Toolkit", discussed in a later section of this article, requires downloading the Java SDK described in this section. 

This means you need the conventional Java 2 SDK from Sun.  I downloaded and used version 1.4 via the following link:

Here is what the download page looks like:

Start the installation program.  Install to the default location ( c:\j2sdk1.4.0_03 ) unless you are able to solve path problems that may arise. 

I won't pretend to know what this is, but I simply downloaded it from the Sun web site.

Here is what the CLDC main download web page looks like:

Only 1.0.3 was available at the time I visited.

In order to download this, I needed to register with Sun web site.  I created the following profile:

I downloaded the following file:

I unzipped to the following directory:

I renamed the "cldc-1_0_3-fcs" directory to simply:

I won't pretend to know what this is either, but I simply downloaded it from the Sun web site.

Here's what the MIDP main download web page looks like:

I downloaded the following file:

I unzipped to the following directory:

I renamed the "midp-1_0_3-fcs" directory to simply:

Add the following lines to your AUTOEXEC.BAT file:

Then force these variables to be reloaded by running the batch file:

You can also set up these same variables using the Windows environment variable control panel.

Notice that I chose to specify explicit directory paths to my current version of the Java 2 SDK.  Therefore, if I upgrade, then I must modify the AUTOEXEC.BAT file to specify the new directories. 

Once the settings above take effect, you should be able to run the Java tool programs from the command prompt without specifying the complete path to the tool programs. 

The following command will start the cellular phone device emulator: 

The following image shows the cellular phone device emulator: 

Using any text editor, a person can type in code, such as for this HelloMIDlet.java source code file:

Here is the code in plain text format:

Caution: The following command must be on a single line, but has been expanded to several lines of text only for clarity.

(Current directory: C:\HelloMIDlet)

Note: The "-target 1.1" is necessary to avoid an error in the future "preverify" stage.  Apparently this has something to do with a problem with MIDP 1.0.3 support in JDK 1.4. 

(Current directory: C:\HelloMIDlet)

This generates a new *.class file in a new subdirectory called "output" (by default).

(Current directory: C:\HelloMIDlet)

This starts the phone emulator, indicating that the new "output" directory contains some of the necessary *.class files.

The following image shows the expected result.

A "manifest.mf" file is essential to getting an actual cellular phone to interpret the contents of a *.jar file.  If a proper "manifest.mf" file is not included within the *.jar file, then the cellular phone might successfully download the *.jar file, but might fail to interpret the downloaded file, possibly reporting an error such as "Unsupported Content Type". 

The following is an example of a simple "manifest.mf" file.

Here is the "manifest.mf" file as plain text: 

Notice that the CLDC and MIDP versions are specified in this file.  Be very cautious and conservative when editing the various fields in this file.  If you get "File Corrupt" errors, then try eliminating all fields that are not shown in this example.  Also, put the fields in the order in which they appear in the example.  Also, shorten each field value as much as you can, and keep the characters limited to simple letters, digits, periods, and dashes.  Some cellular phone services, and cellular phones, can tolerate more variation of field ordering and field contents. 

The following command creates a *.jar file.  The *.jar file will contain the specified manifest.mf file, and will contain the *.class files found in the specified directory.

Current directory: C:\HelloMIDlet

Complex hypothetical example of creating a *.jar file

Suppose an icon image file (e.g., "icon.png") is to appear in a *.jar file as "/icon.png".  (Note: Program icons do not appear on the Motorola T720 cellular phone, but do appear on other cellular phone types, and do appear in the MIDP emulator.) 

Suppose there is a directory named "images" with image files (*.png format).  Suppose this directory, and all of the images contained in the directory, should be accessible to the Java program by the relative directory /images (such that an image "a.png" would be accessible using the path "/images/a.png"). 

Suppose all of the *.class files produced by the preverify command are contained in a directory named "verified".  For example, the verified version of the main class, "MyApp.class", would be in the "verified" folder, along with the other classes of the program.  All of these classes are to be accessible in the root directory of the *.jar file. 

The following command will create a *.jar file that achieves the various goals specified in the previous paragraphs.  Caution: the command has been expanded to several lines of text here only for clarity.  When entering the command at a command prompt, the command must not contain line breaks; otherwise the command interpreter will interpret the entered text as multiple independent commands. 

The final part of the command is difficult to understand.  It has the following meaning:  "Change the current working directory to .\verified, and then put all *.class files found in the relative directory '.' (namely all *.class files in the current working directory) in to the *.jar file."  Because the directory had been changed before specifying the path of the classes to put in the *.jar file, the local path will not appear in the relative path when the files are placed in to the *.jar file. 

For example, suppose the verified classes are in the following directory: 

C:\MyApp\verified 

Suppose there are class files such as the following: 

C:\MyApp\verified\w.class 

Then specifying "-C .\verified ." in the command to create the *.jar file, starting from a current directory of "C:\MyApp", will result in "w.class" being put in the root directory of the *.jar file. </e>

Warning: When the "-C" option is specified, it changes the current working directory at that point of processing the overall sequence of command parameters to the jar command.  Therefore, the jar command might complain that it cannot find other files mentioned in command parameters beyond the "-C" option.  If this happens, simply move the "-C .\verified ." to be the final parameters of the overall command. 

The following shows verbose output of the jar command. 

A *.jad file is necessary so that the cellular phone can describe a computer program to a person before the person decides to download the program.  The *.jad file also provides some indirection from the *.jar itself. 

Here is the example hi.jad file in plain text format:

There are programs which can generate the *.jad file, which makes it easier to update the "MIDlet-Jar-Size:" field each time the *.jar file is changed (and its size changes).  If you search the Internet you will find useful J2ME programs. 

If the size field doesn't specify the exact byte total of the *.jar file, then the following error might appear after a successful download to a cellular phone: "Download Failed" (download failed). 

For the Motorola T720 cellular phone, the following error message might be used to inidcate invalid fields in the *.jad file, or possibly invalid fields in the generated MANIFEST.MF file within the *.jar file: "Failed: File Corrupt" (failed: file corrupt). 

The following executes the class found in the *.jar file, described by the *.jad file. 

(Current directory: C:\HelloMIDlet)

Much of what I presented here can be found on many other Internet sites.  However, I corrected some errors found on other Internet sites, and added missing details, and presented the complete experience of someone trying to do this stuff.  Here are very informative links that helped me get started: 

http://wireless.java.sun.com/midp/articles/getstart
http://wireless.java.sun.com/midp/articles/setup

The simple program presented in the previous section of this document only has a single source code file, and the program does nearly nothing and thus is not a good example of cellular phone programming. 

My friend Sam Robertson wrote an interesting J2ME program that teaches a person to play the card game "Blackjack" (also called "21").  A player is presented with a "dealer card", and the player's pair of cards, and the player must decide what to do: "stay", "hit", "double-down", or "split". 

This program has six source code files.  The program responds to user input, and does simple drawing and text updates. 

Click on the following link to get the source code, and the *.jad file, "manifest.mf" file, and a batch file, all in one convenient ZIP file.

Extract to an arbitrary directory, but if you extract to "c:\" under Windows, the following example discussion will be even closer to your actual situation.

File: "manifest.mf":

The following batch file is rough, but it serves as an illustration of how you might get started with writing your own batch file to build your J2ME program.  This example batch file does the following:

Here is the same file ("build_sbj.bat") in plain text format:

Here is the result of running the "build_sbj.bat" batch file at the command line:

Note that the warning messages for the "rmdir" and "del" operations simply indicate that there is nothing to remove. 

You can see the new directories (i.e., "classes" and "verified") and the new *.jar file that resulted from running the batch file:

To deploy the sbj.jar file, we need to create and edit the sbj.jad file to have the correct *.jar size in the appropriate field:

File: sbj.jad

A person might need to add the complete URL to the *.jar file when the *.jad file is put on an Internet site -- but I discovered (by an experiment) that I was able to avoid mentioning the full URL (i.e., I only specified the *.jar file name by itself).  However, putting in the complete URL, but I wanted to let you know what I observed.

Having multiple source files in your project is common, and in this section we gave a crude illustration of building multiple classes, followed by packaging and execution. 

Please see the following section regarding using Sun Wireless Toolkit, which makes building applications much easier. 

Sun offers a convenient development environment for building and packaging J2ME programs: "Java 2 Platform Micro Edition (J2ME) Wireless Toolkit (version 1.0.4_01)". 

(Caution: You need to download the Java 2 SDK 1.4 as described in an earlier section to use this toolkit. Do this now if you don't already have this version of the Java 2 SDK.) 

Go to the following Internet site to download the toolkit: 

http://java.sun.com/products/j2mewtoolkit/ 

Download the "1.0.4_01 English" version.  Here is what the download page looks like: 

This will download the following file: "j2me_wireless_toolkit-1_0_4_01-bin-win.exe" 

Execute this program to install on your system.

After the toolkit is installed, you can launch it from the "Start" (start) menu system:

You can also access MIDP-1.0 documentation via the "Documentation" item in this Start (start) menu.

Disregard the "MIDlet-Jar-Size" field (with value "100" bytes) for now.  We will eventually cause the correct value to get set. 

Click on the only row in the table ("MIDlet-1") to highlight and select it.  Then click the "Edit" button. 

Do the following: 

(1) Project --> Clean : Removes all *.class files;
(2) Build : Builds all *.class files and preverifies;
(3) Project --> Package --> Create Package : Produces *.jar and *.jad

When you do these three steps, the resulting *.jar and *.jad are immediately ready for execution in the local emulator, or for immediate deployment on your Internet site for others to download "Over The Air" (OTA).  The *.jar size field in the *.jad file will be correct.  Don't forget to do step (3) every single time you rebuild! 

Now you can test by hitting the "Run" (run) button. 

Just copy the *.jar and *.jad files from the specified locations (reported by the toolbar's console window during a build of the project), such as:

(From the console window:)

Put these files directly on to your Internet site without modification, and it should work.  Here is what I saw on my cellular phone after downloading this compiled application "over the air" (OTA)

If you have an Apache Internet web server, you need to create a file named ".htaccess" within your web site root directory.  The ".htaccess" file enables you to override Apache configuration, such as adding or overriding file MIME types.  You must add the specify the MIME types corresponding to *.jar files and *.jad files, as shown in the following text file: 

Here is my simple .htaccess file as plain text:

Apparently, creating or modifying this file results in an immediate change of Apache server behavior.  I guess the Apache server checks the modification date and time of the ".htaccess" file upon each new incoming transaction, and the server reloads that file if the modification date and time has changed. 

If you have a different kind of Internet web server, you must determine how to specify MIME types, and you must ensure that *.jar files and *.jad files are assigned the appropriate MIME types. 

You will know if the MIME types have not been set up if the cellular phone refuses to download your *.jad file and reports the following error: 

"406: Not Acceptable" 

The Motorola T720 J2ME cellular phone with AT&T service is able to download a *.jad file directly, by typing the URL of the *.jad file in to the cellular phone.  This is likely to work for other J2ME cellular phones with other cellular phone service providers. 

However, it might be more convenient for people to download the *.jad file by selecting a link within an HTML document or within a WML document.  (Note: WML is now obsolete. Most cellular phones can now interpret HTML.) 

The following images show the exact sequence of actions I did to download and execute the MIDlet developed and deployed as described in the previous sections above.  These images are photographs of the screen of my cellular phone. 

(1) Main screen: When you open the phone, you see the main screen. Press the center button to go to the main menu. 
(2) Main Menu: Move to the item "WebAccess". 
(3) WebAccess: Move to the item "Go To URL". 
(4) Enter URL: Type in the URL of a *.jad file (or of an HTML document, or of a WML document). 
(5) Details; This information was parsed from the *.jad file. Press DOWNLD to download the *.jar file. 
(6) Download Complete; Wait for this message to disappear; 
(7) Installing; Wait for this message to disappear; 
(8) xxxx bytes transferred; Wait for this message to disappear; 
(9) Installed; Wait for this message to disappear; 


When the WebAccess menu appears again, after the program has been installed, simply exit each menu to return to the main screen. 

(1) Main screen: When you open the phone, you see the main screen. Select the "Games & Apps" option via the main menu, or press the downward cursor on the main screen. 
(2) Java Powered: Wait for this screen to disappear. 
(3) Games & Apps: Select the item with the name of your program! 
(4) Yay! Successful execution of your program! 

The program appearance on the cellular phone is very similar to the appearance within the emulator.

The following errors messages are only relevant to the Motorola T720 (GSM/J2ME) cellular phone. 

Cause #1

Any file (HTML, JAD, JAR, MID, GIF) over 1644 bytes will cause this error for certain Internet web hosts and servers.  Here is a brief list of hosts and servers: 

The problem is due to a flaw in the Motorola T720 GSM/J2ME firmware, which causes downloading files in fragments to fail.

The only apparent solution is to switch Internet web hosts or server type.  Other cellular phone types do not have this problem. 

Cause #2

The "MIDlet-Jar-Size:" field of a *.jad file does not indicate the exact byte total of the corresponding *.jar file.

Cause #1

The *.jar file uses API functions which are not available on the specific cellular phone. 

For example, MIDP 2.0 functions are not available on the Motorola T720 GSM/J2ME cellular phone (which only has MIDP 1.0 functions).  A program might execute within an emulator, but might not execute on the cellular phone. 

The solution is to search for MIDP 2.0 functions in the source code and replace them with MIDP 1.0 functions, or eliminate the features which require the MIDP 2.0 functions. 

Cause #2

The "manifest.mf" file used to create the *.jar file (via the "jar" utility) contains errors. 

Make sure the "manifest.mf" file has the following versions of CLDC and MIDP: 

The entire "manifest.mf" file should look almost exactly like the following: 

Each line of text in the "manifest.mf" file, including the final line of the file, should end with a "carraige return" (CR; 13; 0x0d) character followed by a "line feed" (LF; 10; 0x0a) character. 

The only fields of the "manifest.mf" file in your own version of the file that should differ from the example shown here are the first three fields listed in the example.  The final three fields should be an exact match with the example, and the final two characters of the file should be the "carriage return" and "line feed" after the final field. 

Here are possible problems in your version of the "manifest.mf" file: 

Perhaps some of the cases listed above do not actually cause problems for many cellular phones, but eliminating all of the cases listed above might enable the download to succeed.  After the download is successful, you can experiment with variations of the "manifest.mf" file to discover what other things you can do without causing download errors.  When the "manifest.mf" file is modified, it is important to verify that downloading the program continues to work for all target cellular phones and cellular phone service providers.  Some phones and services are less flexible than others. 

When a "manifest.mf" file is added to a *.jar file via the jar program, the jar program creates a new version of the manifest file within the *.jar file.  The generated version of the manifest file within the *.jar file is named "MANIFEST.MF".  The jar program might add fields to this file that do not exist in the "manifest.mf" file provided by the programmer.  Do not extract a "MANIFEST.MF" file from a *.jar file, unless you are prepared to eliminate some fields and make the remaining fields look exactly like the example "manifest.mf" file shown above. 

Cause #1

The cellular phone cannot accept the MIME type reported by the remote server for a specific file. 

For example, JPG image files are not supported by the Motorola T720 and will cause this error.

This error can also occur if the MIME type for a supported file type (e.g., GIF, MID, JAD, JAR) is not reported correctly by the server.  A person must be very careful to report the exact MIME type for the supported file types. 

Cause #2

The file cache on the cellular phone itself needs to be cleared (e.g., Browser Settings -> Clear Cache). 

If you recently added MIME types to a remote server, and then attempted to download a file that had previously failed to install due to an incorrect or missing MIME type, then the file cache on the cellular phone might be an obstacle to downloading the file again with the proper MIME type. 

It is also possible that the remote file was modified and that the cached version is defective and is preventing the repaired file version from being downloaded as a replacement. 

Clearing the browser cache on the cellular phone should ensure that a subsequent download benefits from the latest server configuration (e.g., new MIME settings) and remote file updates. 

Cause #3

[From Motorola documentation: http://developers.motorola.com/developers//wireless/global/emea/other/UCT.html]