Welcome.
I have developed this site 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 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 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 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.
Updated Information
Link to updated information
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 J2ME CLDC base.
- jar file 10kb restriction.
- Scratch pad 5kb restriction.
- Don't forget to preverify.
- Beware of the seriously delicate jam file!
Links
Here are a few links for information about J-Phone and KDDI's Java properties. Sorry most of it is in Japanese, But you should be able to find the Java information.
JPhone
KDDI
About
I hope that this helps you along with developing IApplications! If you
find any errors or new ways of doing something please tell me. My
email address is zblut@excite.co.jp
Happy programming!
Zev Blut
Minor updates : 2002 March 25