HomeDigital EditionSys-Con RadioSearch Java Cd
Advanced Java AWT Book Reviews/Excerpts Client Server Corba Editorials Embedded Java Enterprise Java IDE's Industry Watch Integration Interviews Java Applet Java & Databases Java & Web Services Java Fundamentals Java Native Interface Java Servlets Java Beans J2ME Libraries .NET Object Orientation Observations/IMHO Product Reviews Scalability & Performance Security Server Side Source Code Straight Talking Swing Threads Using Java with others Wireless XML

Here in Japan, where it's common to see someone thumbing away on a cell phone while on the train, NTT DoCoMo was one of the first companies in the world to release Java-capable mobile phones. In the ensuing six months, more than four million users have adopted the phones - and the number is growing. That's a good enough reason for an aspiring J2ME programmer with a sense of adventure to learn a little about programming Java applications for NTT DoCoMo phones.

Before I go into the technical details on how to develop for these phones, let's talk about the types of devices available today. Six models of the 503i series mobile phone, provided by five manufacturers, are currently available to the consumer.

A few common hardware traits of these mobile phones:

  • They are small, light, and provide long hours of talk time.
  • They provide a color screen, with at least 16 harmony audio capability for ringtones and for use in applications.
  • They have the capability to display GIF images.
  • The phones can also write e-mail, browse a reduced form of the Web, and download backgrounds and ringtones for customizing the phone and, of course, Java applications.
More information about the 503i series phones can be found at http://503i.nttdocomo.co.jp/normal/n_index.html (in Japanese, but the site has lots of pictures).

For various reasons NTT DoCoMo released its own profile for J2ME developers to use when programming for the phones. This profile is known as i-mode Java - also called by its nickname DoJa (DoCoMo's Java). I-mode Java resides on top of the Connected, Limited Device Configuration (CLDC), just like the other - competing - profile, the Mobile Information Device Profile (MIDP).

To clear things up quickly, MIDP and DoJa are not compatible. Each has its own API and way of handling things, such as the user interface and data storage. When you write a program using MIDP, you write a MIDlet; when you write a program using DoJa, you write an i-appli. MIDP and DoJa are quite similar, but at the same time different: the i-mode Java specifications have defined many requirements that are currently left up to the implementers of MIDP devices to decide.

I-Mode Java Specifications
When I first looked at the i-mode Java specifications, my reaction was that it's too strict. DoJa specifies that all applications must be less than or equal to 10KB in size. How can you get a great program that is going to revolutionize the world to fit in 10KB? Well, don't fret. Many interesting applications have already been written and keep me happily occupied on my train rides to Tokyo. I'm surprised by what I have been able to fit in 10KB.

Another requirement of the specification is that applications must be downloaded to the handset from a Web page, thus solving the over-the-air issues that some have had with MIDP phones.

All applications have the ability to store up to 5KB of permanent data on the phone. Unlike MIDP, where you have MIDlet Suites that can share data in storage, DoJa doesn't allow for the sharing of data among i-applis.

As mentioned previously, all phones must support the GIF image format. In addition, all phones must allow HTTP/HTTPS (SSL) connections to the host server that the i-appli was downloaded from (SSL is built into the phones, providing end-to-end security from the handset to the Web site, thus easily providing a solution for secure transmissions).

Not directly related to the specifications but still important to know is that NTT DoCoMo charges the user 0.3 yen for every 128 bytes of information sent from and received by the phone. If you want happy users, you need to keep their bills in mind when writing network-intensive applications.

DoJa provides four packages that are added to the ones found in the CLDC: com.nttdocomo.io, com.nttdocomo.net, com.nttdocomo.ui, and com.nttdocomo.util. Later in this article, I'll use some of the classes in the com.nttdocomo.ui package to help you get acquainted with developing i-applis.

Resources and Tools for Developing I-Applis
Now that I've introduced the basics, let's cover what you need to do to start developing i-applis. First, go to NTT DoCoMo's Web site about i-mode Java and download two English .pdf files (www.nttdocomo.com/i/java/index.html). These documents are an API listing and a developer's guide to creating i-applis. They'll be of considerable use for further exploration.

Once you have these documents, you need to get an emulator and an SDK to develop with. First you should get the CLDC SDK from http://java.sun.com/products/cldc/. This provides the CLDC base classes, source code, and documentation.

If you're familiar with the J2ME Wireless Toolkit provided by Sun Microsystems for developing MIDlets, then you'll be pleased to know that NTT DoCoMo provides a modified version of this toolkit for developers. It can be found on the Japanese Web site at http://www.nttdocomo.co.jp/i/java/tool.html.

If you can't read Japanese and are having trouble with the page, don't worry. Take it through a machine translation site, such as AltaVista's Babel Fish at http://babelfish.altavista.com). The toolkit will run in English (if you aren't running a Japanese OS) and provides an emulator to run your i-applis on. As a bonus, it also automates many of the compilation, preverification, and packaging steps discussed later.

Another emulator, probably new to developers from the MIDP world, is Zentek Technology's i-JADE product (found at www.zentek.com/i-JADE/index.html). It's designed to emulate the look and feel of actual phones available in Japan right now. These emulators are invaluable tools for developers, and I suggest you download both.

Finally, you'll need a J2SE SDK for use during development. You should have no problems using most IDEs with DoJa, but if you want to integrate development into the IDE, then Forte for Java, JBuilder, and VisualCafé all offer ways to integrate the emulators.

Writing an I-Appli
Now that you know where to find resources and tools for i-mode Java, we're ready to write a simple application. For this article it's going to be the tried-and-true Hello World, found in Listing 1.

The first thing to note is that all applications must have a class that extends com.nttdocomo.ui.IApplication. This class must implement IApplication's start method, which is first called when the user runs the application on the phone. This is similar to an applet's start method or a MIDlet's startApp method. In the start method I create a Panel (a class that represents a screen and lets you place objects on it), called hpanel, then make a Label, called hlabel, with the text "Hello World!" and add it to the panel I created.

Next, I set hpanel's softkey 2 text to show "quit" and register the HelloWorldAppli class as the SoftKeyListener. All phones have two buttons called softkeys located on the left and right edges, below the handset's screen. When you set the text for a softkey, it will be displayed directly above the button.

Softkeys are commonly used as a way to quickly activate functions or menu options. In this example pressing the right button (softkey 2) will quit the application. One point to remember is that all i-applis must quit by calling the IApplication terminate method. Don't call System.exit() or Runtime.exit() as they will cause a SecurityException.

We catch that a softkey has been pressed by making our class implement SoftKeyListener with the two methods softKeyPressed and softKeyReleased and register the listener to the panel to catch the events when the panel is showing.

Finally, we're ready to show the message to the user. Thus we call the static setCurrent method on the singleton class Display (passing in hpanel). This is a rather long and involved version of Hello World, but if we did a simpler version, using System.out instead of creating Panels and Labels, the message would never be shown on a real phone, because the phones don't show System.out or error messages.

Of course, I could decide not to bother to implement the quit command, but in that case the user would then have to press the force quit key (usually the power button). Pressing this button drops the user out of the i-appli software listing and back to the base screen the phones show when powered on. If they pressed our softkey instead, it would quit the application and return to the listing of downloaded i-applis on the handset, which is much more user-friendly.

Figures 1-4 are screenshots of the application running on the wireless toolkit, i-JADE, and on a real phone.

Figures 1-4
Figures  1-4:

Compiling I-Appli
The steps needed to go from code to pixels shown on a real phone are fairly similar to those needed for an MIDP application, but a bit more involved for a J2SE application. In all cases, once you've written your code you must compile it. A trusty J2SE compiler will do the job just fine.

When compiling you must set the bootclasspath parameter to the CLDC base library instead of the usual J2SE base, then set the classpath to point to your source code and the DoJa API. Make sure to turn off debugging info, because it'll add to the size of your application and be of no use while running on a real phone. In this example our compilation command might look like this:

c:\jdk1.3\bin\javac -g:none -bootclasspath
c:\j2me_cldc\bin\api\classes -classpath
c:\ijadeP\i-jade-p.jar;. -d compiled HelloWorldAppli.java

Run Preverify
Next you must preverify your compiled code. For those who do this on a daily basis with MIDP, it's exactly the same (except for a few different parameters). For those who don't know, "preverify" is a tool used to offload some of the work the KVM must do to ensure that the Java bytecodes it receives are valid. It's included in the CLDC SDK, and it can also be found in the wireless toolkit for DoJa.

Following is an example of running the preverify command on the HelloWorldAppli class:

c:\j2me_cldc\bin\preverify -classpath
c:\j2me_cldc\bin\api\classes;c:\ijadeP\expandedJar\ -d
preverified compiled

To explain, I run the preverify command, setting the classpath to the CLDC's classes and the DoJa classes, and take the classes in the compiled directory, outputting the resulting preverified classes to a folder called preverified. In this example I'm using i-JADE for the DoJa API - the preverify tool can't read .jar files, so you must expand any .jars you're using, setting the classpath to point to the expanded folder (in this case the folder used is expandedJar).

Packaging I-Appli
After running preverify, you can package the application to deploy it. I-mode Java phones take a .jar file with the preverified classes and any other resources you wish to use, such as GIFs and sound files. Make use of the J2SE's .jar tool to bundle your application into a .jar file. When making a .jar, the handsets won't use the Manifest file; therefore you can save space by using the flag - M in your .jar command.

As in the following example:

c:\jdk1.3\bin\jar -cvfM HelloWorld.jar
HelloWorldAppli.class

Once you've made your application a .jar, look at the file. If it's less than 10,240 bytes, you're in the clear and ready to take the next step in deploying your application. If it's greater than 10KB, trim your classes and/or resources so your .jar file is 10KB.

Creating an Application Descriptor File
Once we have the .jar file, we're ready to create an Application Descriptor File, otherwise known as a .jam file. This file is used to tell the phone about your application before you download and execute it. It contains vital information, such as the application size and name, parameters to pass to the application, and whether it uses the network. For this article I'll introduce you only to the details that are mandatory for all applications: AppName, AppClass, AppSize, PackageURL, and LastModified.

  • AppName: Name of the application; used when showing the list of the applications on the handset.
  • AppClass: Class that extends IApplication. If this class is part of a package, make sure to give the fully qualified class name.
  • AppSize: Size of the .jar file containing the i-appli in bytes.
  • PackageURL: URL pointing to the .jar file to download. If the .jam and .jar file are in the same directory, then just give the name of the .jar file.
  • LastModified: Time the application was last updated. Used to check if upgrades are available. This is also the trickiest key to work with. If the next five steps aren't followed, it can lead to problems at download time.
    1. The first three letters of the day of the week followed by a comma
    2. The two digit date
    3. The first three letters of the month
    4. The four digit year
    5. Finally, the time up to the number of seconds, separated by colons and using two digits for each number
It can be a pain, but with practice it becomes easy (even Panasonic made a mistake implementing this spec, so beware of the month of April if you want to have your app run on a Panasonic phone). Listing 2 is an example .jam file for the HelloWorld i-appli named HelloWorld.jam.

Note that the wireless toolkit and i-JADE Lite Plus can automate the compilation, preverification, and packaging process, and can generate the .jam file, greatly simplifying development and saving you from the vagaries of the LastModified key.

Developing a Web Page for Deployment
The final steps involve creating a special Web page. Upload this page along with the .jar and .jam files for the application onto a Web server. To create the page, follow NTT DoCoMo's modified cHTML format. This is HTML with fewer frills; a good site for information about the tags is http://www.nttdocomo.com/i/tag/lineup.html). The Web page must include two specific tags: an Object tag and an Anchor tag. Listing 3 provides a sample Web page for the application, and Figure 5 shows what it looks like on a real phone.

Figure 5
Figure  5:

To make the Web page, create an object tag that specifies an ID to refer to the anchor tag and a data attribute that gives the path to the .jam file. The object tag also has a type attribute with the value "application/x-jam".

For the anchor tag insert a special attribute ijam that references the object tag's ID value. Then give an HREF attribute pointing to a page to display if the user attempts to download the i-appli from a handset or browser that doesn't support i-applis.

Once you've created the Web page, all that's left is to upload the page along with the .jar and .jam files to a Web site. If you're in Japan, open up the page in your phone and click on the anchor to download and run the application.

Summary
You've now seen what it takes to make a simple application for NTT DoCoMo's Java-enabled handsets. It might seem like the various steps to develop and release an i-appli are a chore, but practice makes it easy, and the time-consuming task eventually returns to writing the code itself. Now it's time to come up with more of those great applications that keep everybody so occupied that they miss their intended destination on the train!

Resources
1. Mailing list focusing on the mobile phones in Japan: www.appelsiini.net/keitai-l/
2. NTT DoCoMo's Web site about i-mode: www.nttdocomo.com/i/index.html
3. NTT DoCoMo's listing of the Java-enabled 503i series phones: http://503i.nttdocomo.co.jp/
4. Web page I created to help beginners get started developing i-applis: www.geocities.co.jp/SiliconValley-Cupertino/1621/
5. Zentek Technology's i-JADE emulator: www.zentek.com/i-JADE/index.html
6. Sun Microsystems CLDC SDK: http://java.sun.com/products/cldc/

Author Bio
Zev Blut is a software developer in the R&D department for Yamatake Corporation in Fujisawa, Japan. He has worked with the i-mode Java API since the phones were released to the public in January 2001. Blut holds a computer science degree from the University of Texas at Austin. [email protected]

	


Listing 1: Source Code for HelloWorldAppli.java

import com.nttdocomo.ui.*;


public class HelloWorldAppli extends IApplication implements SoftKeyListener {


    public void start(){
        Panel hpanel = new Panel();
        Label hlabel = new Label("Hello World!");
        hpanel.add(hlabel);


        hpanel.setSoftLabel(Frame.SOFT_KEY_2,"Quit");
        hpanel.setSoftKeyListener(this);


        Display.setCurrent(hpanel);
    }


    public void softKeyPressed(int softKey){
    }


    public void softKeyReleased(int softKey){
        if (softKey == Frame.SOFT_KEY_2){
            this.terminate();
        }
    }
}




Listing 2:  Application Descriptor File: HelloWorld.jam 

AppName = HelloWorld
AppClass = HelloWorldAppli
AppSize = 629
PackageURL = HelloWorld.jar
LastModified = Sat, 04 Aug 2001 23:00:10




Listing 3: hw.html: Example Web Page for the HelloWorld I-Appli

<html>
<body>
<object declare id="helloworld.dec" data="helloworldiappli.jam"
type="application/x-jam"></object>
Please press
<a ijam="#helloworld.dec" href="handsetError.html"> here 

to download the i-appli. 
</body>
</html>

  
 

All Rights Reserved
Copyright ©  2004 SYS-CON Media, Inc.
  E-mail: [email protected]

Java and Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. SYS-CON Publications, Inc. is independent of Sun Microsystems, Inc.