Home -- > Notes Index -- > Note

A Basic guide to developing i-appli programs by Zev Blut (2002-8-14)
Author: Zev Blut
Email: zblut@excite.co.jp
Website: Current guide

The difference between i-appli and Sun's MIDP profile
Needed tools
Generating and Running an i-appli
Gotchas
Additional Information

Http Connections
Dates in Jam file
Graphic performance
Colors

Historical
Summary
Links

Welcome.
I have developed this in the hopes of helping others who are getting started with developing i-appli programs for NTT DoCoMo's new mobile phones. Those who are not fluent in reading Japanese know that finding information about the i-appli API is not easy, so I figured I might help with what I have learned.

Before we start you will some times see me use the term keitai, this is a commonly used Japanese word that is often used to mean a mobile phone. Actually keitai means portable and the full term for a mobile phone is keitai denwa, but it is often shortened to keitai. So, when you see keitai I mean a mobile phone.

The difference between i-appli and Sun's MIDP profile

NTT DoCoMo decided that they are not going to use Sun's community developed profile API MIDP. They say something to the nature that the MIDP is also for things like pagers and thus NTT DoCoMo's API is better optimised for their phones. Surprisingly enough the API's themselves are actually fairly similar.

First of all they are both part of Sun's Java ME (J2ME) CLDC concept. This means that they use the reduced Java Virtual Machine KVM, restrictions on the use of primitive types such as Doubles (cannot be used), and it uses a subset of the Java API's java.lang, java.io, java.util, and javax.microedition.io.
Most importantly you create an i-appli by creating a class that subclasses com.nttdocomo.ui.IApplication and override the public void start() method. Sun's MIDP profile extends Midlet and are thus called Midlets. They are not the same.
Application descriptor files NTT DoCoMo's jam file vs Sun's jad file.
NTT DoCoMo's 503 Series handsets and the FOMA handsets support i-appli execution and are in use Japan today.
There are a two different providers that offer MIDP Midlets in Japan, they are KDDI and J-Phone.

As to which API is better? I have my opinions, but I will not bias you yet. = )

Needed Tools

A java compiler and a jar tool this can be found in the J2SE toolkit by Sun.
The Java ME (J2ME) toolkit by Sun. This being the base CLDC kit, the MIDP classes are not needed.
the NTT DoCoMo specification pdfs
your choice of NTT emulators.
NTT DoCoMo has not released a tool set for i-appli yet so you will need to use third party implementations.
- iEmulator
- iJavaEngine i503 SourceForge project
  The iEmulator and iJavaEngine are both implementations of the API designed to allow you to compile your software against NTT's idea. As for using these API for testing it is a bit more difficult and not very close to the real thing.
- Zentek has created an API implementation, called i-jade, that allows you to compile against and actually run in a simulator of various 503 series handsets that are very close to what it is like with the real thing.
  I read on a mailing list a person's question about the other packages in the i-jade jar file such as com.zentek.*, I would imagine that you should only concern yourself with the com.nttdocomo classes since those are the ones guaranteed to be in phone and also we have documentation, in Japanese, on it.
However, I found that I prefer, in Forte, to develop and compile with either the iEmulator or the SourceForge implemenataion, because the i-jade jar file has been obfuscated and the code completion of the methods then give me meaningless variable names such as "p1" instead of "eventType".

Generating and Running an i-appli

So you have created a class that overrides IApplication and you are ready to test it, and deploy it!

I took the easy way out and compiled everything within Forte, having my classes in a mounted directory and then the iEmulator/or iJavaEngine classes mounted also. Of course, you can always compile from the command line of java just make sure that the bootclasspath has the cldc java libraries and that your classpath also contains the i-jade/iEmulator/iJavaEngine and your classes.

Actually, I recently encountered a problem when preverifing my classes that were compiled from the very basic Forte environment. It seems that my simple way of compiling actually used the fully Java classes and thus inserted a few illegal classes in my classes. So make sure that you set up your environment to compile only with the CLDC classes and the NTT DoCoMo classes!

At this point I would say that it is best to use the i-jade simulator to test out your class. You can do this by going to the command line and typing something like this
"c:\i-jade\java -jar i-jade-f.jar"

You will then see two windows appear one with a replica image of the 503 keitai and the other is a control window in Japanese. Really the control windows commands are so simple that you do not need to worry if you cannot read Japanese. Simply select the very first menu item of the first menu to select the IAppli class or (jam file) that you want to run. The Cell phone will then start your application and you can test it from there. The second menu item is the quit option and the second menu is simply the about window. In the control window you will also see the path of your currently loaded class or jar file. If you loaded it from a class you are going to need to replace the backslashes (or forwardslashes) with periods of the package name of your class so for example
"c:\keitaiprograms\test\com\me\TestAppli"
would become
"c:\keitaiprograms\test\com.me.TestAppli"
Well, I hope that made sense!

Now if you tested it and you are ready to try and deploy your program onto a real phone you need to do a few more things.

You need to preverify the classes that you compiled. The Java ME (J2ME) tool set comes with a program called preverify. You preverify classes to reduce some of the work the KVM has to do when loading and checking a class. Since these devices are on slower and less powerful processors you want to do as much work as possible ahead of time.
So here is where an interesting problem that I had occured if you decide that you want to preverify with the iEmulator(jar file)/iJavaEngine/(i-jade jar file) I got various errors when preverify classes that override Panel and such. The iEmulator and iJavaEngine packages would give me an error saying that they could not find javax.swing.JPanel, which of course is used as a stop gap measure to simulate the real thing. Well on a real phone you will not have any Swing packages so this was a problem. The i-jade jar files would not work either giving me a different error. So I expaned the i-jade jar file and linked the preverifier to that directory and everything works well. If you have a solution to this problem please tell me!
to preverify type something like this
"c:\preverify -classpath c:\cldc\classes;c:\i-jade\i-jade-f.jar;c:\myclasses -d c:\myOutput MyClass "
Once you have preverified your classes you will then want to jar the classes and any support files such as gifs or audio together. There is a serious limitation of the i-appli phones and that is the jar file must be under 10kb in size!
Here is were I lost a few hours of work spread across a few days on. In order to deploy your application you need to create an Application Descriptor File, with a .jam extension. This file has a few important keys that must be used.
- AppName = [This is the name of the application to appear in the i-appli menu]
- AppVer = [This is the version of the program something like 1.1]
- PackageURL = [this is the full or relative URL of the program's jar file]
- AppSize = [the size in bytes of the jar file]
- AppClass = [ the name of the Iapplication class to load]
- LastModified = [The date of the last time the file was modified]
after that it needs to be in SJIS encoding and you must have the Microsoft carriage returns after each key entry. The actual program that loads the jam file on the phone is extrodinarly picky and I had a very hard time getting it to recognize my correct jam files. Finally, I got lucky and now when I want to make a new jam file I copy my working jam file and going into vi and very delicately replace information making sure to not insert any returns or otherwise unneeded changes and preserving the "^M" returns after each entry.
In addition, You must be extra careful with how you input your LastModified entry. It must be the first three letters of the day of the week. Followed by a comma then the date then the first three letters of the month then the year then comma then the time hour:minutes:seconds
So something like this
LastModified = Tue, 30 Jan 2001 18:26:15
After this you make a web page that you need to add a special tag to your html file
<OBJECT declare id="application.declaration" data="FunGraphics.jam" type="application/x-jam">
My Appli Test
</object>
download appli
<a ijam="#application.declaration" href="Fail.html">click here!</a>
The href field in the a tag declaration is a link to a failure url if there was a special type of failure that occured.
Then download and i-appli away!

Gotchas

Also watch out for loading resources in the MediaManager class, make sure you have 3 slashes such as "resource///me.gif".

When going to sites use the name versus the IP address of the site. Or else the i-appli will not download.

You can use relative URLs in the Web Page and the jam file, just make sure you are not moving them around too much! I would say that the relative URLS are actually more preferable.

The i-appli menu has a good function that lets you get the latest version of your IApplication so it uses the jam file and extra info it recors to find your site and check for new revisions.

Additional Information

Http Connections

First important piece of information is that if you want to make a Http connection, to up/download information from the originating server you must add to your jam file the "UseNetwork = http" flag. If you do not add this, most likely everything will work fine on your emulator and when you download the program onto a real phone and run it, as soon as you actually call the code that makes the connection you will get an error message and the program will quit. Also, if you are using ssl over http (https) then you still say http. I have not yet tested this, but the docs say that this is the case.

Dates in Jam file

So if you have read my warnings about jam files and you created them very carefully and you are still having problems, then this information might be of great help. Well you must be very precise when you enter your data for the LastModified field. It must start with the first three letters of the day of the week, thus Monday is Mon, Tuesday is Tue, Wednesday is Wed and so forth. Then you have the comma and the date of the month this must be 2 digits so if it is the second of the month then it is 02 not 2. I have not tested the month part yet, but I believe that the month must also be the first three letters of the month January becomes Jan, Febuary becomes Feb and so on. Then you have the year which must be 4 digits and then the 2 digit hours colon 2 digit minutes colon 2 digit seconds. If you do not follow this format, then the phone will give an error when attempting to download the jam file and thus prevent you from downloading the jar file and running the program. So the format is something like this LastModified = ABC , ## ABC ##:##:## , where ABC means 3 alphabetical characters, and the # symbol means a number.

Graphic performance

If you want to improve the graphic performance of your application, then when using the Graphics object before performing the operation call the lock method. Thus if your Graphics reference is called then you would do something like this g.lock() when done you call g.unlock(false) or true if you want to force the graphics to be flushed instantly. False means to put the Graphics a queue and to draw the Graphics when its' turn comes. This allows for double buffering and the reduction of screen flashing and such.

Colors

This is something that got me for not reading the docs carefully. The Graphics have a few colors declared as constants. At first I thought Ok so if I want to draw a yellow line then I will call g.setColor(g.YELLOW) then g.drawLine(0,0,100,100) . Of course, I was wrong! You must call g.setColor((g.getColorOfName(g.YELLOW)))

Historical

Note: I just went to a Sun Tech Day conference about MIDP programing yesterday (Feb 7th) and the presenter said something that caught my interest. She said something to the nature of running MIDP on i-appli phones. So I had to ask her if she knew that they are currently different. She said that since i-appli are the first (or someof the first) java enabled phones they did not have time to get up to spec with MIDP. So she is hinting that maybe the next generation or two of i-appli phones will actually go over to MIDP. Of Course, if you look at NTT DoCoMo's FAQ site about i-appli they seem to have a different stance. Interesting nonetheless.

Summary

i-applis are not Midlets!
Get a NTT DoCoMo API implementation.
Get Sun's Java ME (J2ME) CLDC base.
jar file 10kb restriction.
Scratch pad 5kb restriction.
Don't forget to preverify.
Beware of the seriously delicate jam file!