Developing for Japanese Phones in Netbeans (Part 3)

IAppli (NttDocomo) Development in Netbeans

In parts one and two of this large blog post I explained how to use Netbeans with the Mobility pack to develop mobile applications for two of the major carriers in Japan (au/KDDI and Softbank). In this last part I will talk about developing IAppli's that are how the mobile applications for NttDocomo phones are called.

There is a big difference in development for NttDocomo phones when compared with the other two carriers and any other J2ME platform. NttDocomo uses a propietary profile called Doja instead of the standard MIDP profile.

There are core differences between MIDP and Doja that make them incompatible. For example in MIDP the main application class inherits from the MIDLet class while in Doja the main application class inherits from IApplication class. This kind of core differences and others (see here) makes it necessary to have two complete different versions of the source code (Doja and MIDP versions) if we want the application to run on as most platforms as possible.

If we ignore this incompatibility details then Doja is a great platform for developing applications for phones. I really found Doja development much easier and entertaining than the MIDP counterparts. Maybe because at the time Doja had much more functionality than MIDP. Current versions of MIDP may be by now as good as Doja but I bet Doja is even more powerful than it was before.

Doja Versions

There are several versions of Doja here in Japan and I now of at least two international versions that are used in other parts of the world. In Japan we have versions: 1.0, 1.50E, 2.0, 2.1, 2.50E, 3.0, 3.5, 4.0 and 4.1 and internationally we have versions: 1.5 and 2.5.

I will talk here how to use Japanese versions of Doja versions between and including version 3.0 to 4.1 since the procedure is exactly the same. I have not used the international versions and really don't know if they are excactly the same as the Japanese ones. For information (in english) of the international versions of Doja please refer to the Doja Development Network. All I can tell is that the information in this page is applicable to the Japanese versions of Doja as well.

Getting the IAppli Development Toolkits

All the necessary files for IAppli development can be downloaded from this page. The firsts links are development guides (pdf files) and java api documentation (zip files) for each of the Doja versions available. In the section that says something like アプリ開発ツールのダウンロード is were we can download the development toolkits. You can choose the version of Doja you want to develop but for this guide I have only tested versions 3.0 to 4.1.

Click in the version you want and a page with the requirements and a download link will appear. As usual you need a Windows2000/XP machine with Java2 SDK 1.4.X and for this guide you also need Netbeans with the Mobility Pack version 4.2 or 5.0.

Click in the download link (is in english) and a terms of use page appears. If you agree with the terms of use click in the link below that says 同意する and save the zip file on disk. The file is called emufordoja4_1_201.zip for Doja4.1. If you choose a different Doja version the file name may be different.

Unzip, click the install exe file and accept all the defaults. If you have doubts you can follow the instructions in this page since the steps are very similar to the Japanese versions of Doja.

If everything went OK you will have the tool installed in C:\iDKDoJaX.Y where X and Y are the version number of the Doja toolkit. In my case it is C:\iDKDoJa4.1. I must note that Doja4.1 comes with a plugin for Netbeans already but it does not use the Mobility Pack. This means that all the features that the mobility pack offers cannot be used with this plugin.

The idea of using Netbeans is the ability of the Mobility Pack to handle device partitions and the automatic application build process so I will not be using the plugin that comes with Doja. Also previous versions of Doja do not have this plugin making it difficult to develop applications that support several versions of Doja.

You can develop IAppli's with the toolkit alone following these instructions. In fact all the tutorials that you can find in the Doja Development Network should work in any version of Doja so if you are not interested in using Netbeans for Doja development stop reading this blog and study all the tutorials in the Doja Development Network page.

IAppli's with Netbeans

As with EzAppli's the Doja development toolkits are not UEI compatible so some manual work is needed in order to develop Doja applications with Netbeans. For Netbeans to detect the Doja toolkit as a J2ME platform we must create a platform definition file:

<?xml version='1.0'?>
<!DOCTYPE platform PUBLIC '-//NetBeans//DTD J2ME PlatformDefinition 1.0//EN' 'http://www.netbeans.org/dtds/j2me-platformdefinition-1_0.dtd'>
<platform name="iDKDoJa4.1" home="C:\iDKDoJa4.1" type="custom" displayname="NTT Doja 4.1" srcpath="${platform.home}/doja_stub_src.zip:${platform.home}/stub_src.zip:" docpath="${platform.home}/doc," preverifycmd=""{platformhome}/bin/preverify.exe" -classpath "{classpath}" -d "{destdir}" "{srcdir}"" runcmd="">
<device name="FOMA" securitydomains="trusted,untrusted" description="FOMA">
<configuration name="CLDC" version="1.0" displayname="CLDC1.0" classpath="${platform.home}/lib/classes.zip" dependencies="" default="true"/>
<profile name="DOJA" version="4.1" displayname="Doja4.1" classpath="${platform.home}/lib/doja_classes.zip" dependencies="" default="true"/>
</device>
</platform>

This platform definition file works for all Doja versions (3.0~4.1). Only make sure to change the version number (i.e. 4.1 with your version) and the path where the toolkit is installed in you machine.

Save this file as "Doja4.1.xml" and put it in the platform directory (\config\Services\Platforms\org-netbeans-api-java-Platform) in your user home directory (the Windows default is C:\Documents and Settings\{username}\.netbeans. If you installed more than one Doja toolkit create different files for each one (i.e. Doja3.0.xml, Doja3.5.xml and so on) making sure to change the version names and the installation path. Copy all these platform definitions files in the directory above.

Now when entering the Netbeans Java Platform Manager (Tools menu) you will see the Doja platform for all the toolkits you created xml files for.

The description file (JAM)

When creating mobile applications using the MIDP profile we need to create a description file (JAD file) that contains information about the application. In Netbeans this JAD file is generated for us and if we need to add attributes to the file (i.e. HTTP support) we can do it easily in the projects properties of Netbeans.

For Doja we need to create a similar file but is called JAM instead of JAD and has different attributes that a JAD file does not support. The best way I have found to create this file when building the project is to use the Eclipse Doja plugin. This plugin contain some ant tasks that make it easy to create the JAM file and since Netbeans build system is based on ANT tasks we can easily add support for the JAM file creation.

First we must download the Eclipse Doja Plugin from this page. Look for a file called jp.gr.ttj.Doja_0.0.1.zip and download it. Uncompress the file and look for a file called anttask.jar and copy it in a directory where the Netbeans ant can find it. I simply copy it in the projects directory but this means I must copy this file in each of the Doja projects I create.

HelloNtt example IAppli

Now the main part. To develop an IAppli using Netbeans we proceed as any normal MIDLet. We create a new "Mobile Application" project and follow the Netbeans dialogs selecting the projects name and folder. For this example create a project called HelloNtt. You can check the Set as main project box but uncheck the Create Hello Midlet box.

In the next dialog select in the Emulator Platform the NTT Doja 4.1 platform (or any other Doja platform you have installed) and finish the project creation process.

If the Doja emulators do not appear in the list box of emulator platforms then you forgot to create the platform definition xml file and copy them in the Netbeans platforms directory in your userhome as indicated above.

As I mentioned in the previous section we need to modify the building process of Netbeans to create a JAM descriptor file. For this we need the anttasks.jar file that comes with the Eclipse Doja plugin (see previous section). Copy the anttasks.jar file inside the newly created project directory (i.e. HelloNtt) and open the build.xml file inside there.

You must add the following targets in between the <project> and </project> tags in the build.xml file:

        <target name="post-jar">
        <taskdef name="file" classname="jp.gr.ttj.ant.FileTask">
            <classpath>
                <pathelement location="anttask.jar"/>
            </classpath>
        </taskdef>
        <taskdef name="date" classname="jp.gr.ttj.ant.DateTask">
            <classpath>
                <pathelement location="anttask.jar"/>
            </classpath>
        </taskdef>
        <file property="jarsize"  type="size" file="${basedir}/${dist.dir}/${dist.jar}"  />
  <date property="TODAY_i" pattern="E, dd MMM yyyy HH:mm:ss" />
        <echo file="${dist.dir}/${name}.jam">
LastModified = ${TODAY_i}
AppClass = ${name}
AppName = HelloNtt
PackageURL = http://www.mypage.com/${name}.jar
AppSize = ${jarsize}
UseNetwork = http
SPsize = 102400
 </echo>
    </target>
    
    <target name="run" depends="init,jar">
 <exec executable="${platform.home}/bin/doja.exe" dir="${dist.dir}">
  <arg value="-i" />
  <arg value="${name}.jam" />
 </exec>  
    </target>    
    
    <target name="post-clean">
         <delete file="${dist.dir}/${name}.jam"/>
    </target>

Only look where it says AppName and PackageURL. These are the most important attributes of the JAM file and MUST be setup to reflect your application. The AppName is simply the name of the application you are developing. The one that will appear in the phone when the application appears in the list of IAppli's installed in the phone. The PackageURL is the URL address from where the IAppli is to be downloaded. This URL is not important when running from an emulator but must be the real URL from where the IAppli is to be downloaded when deploying to real phones.

The UseNetwork and SPsize attributes tell that the IAppli can use http connections and the Scratch Pad (Persistent Storage) respectively. They are not required for our little HelloNtt example but you may need them for more interesting applications.

Please make sure that all attributes that are to be written to the JAM file have no white spaces to the left in the build.xml file. This way there will be no spaces to the left in the JAM file. All the attributes you add must be in between the <echo> and </echo> tags.

If you understand how ANT works you may see that there is also a run task there. This task simply invokes the Doja.exe emulator with the JAM file as parameter. You may be also define a debug task to use the Dojag.exe emulator that supports debugging functions like limited phone memory and storage.

HelloNtt Source code

The little example here is gonna be very different from that used for EzAppli and S!-Appli mostly because Doja is different. Within the project's context menu (right click) select New->MIDLet and in the dialog that appears input the IAppli name (HelloNtt). A new java source will be created in the src directory of the project. Delete everything in that file and put the following code:

import com.nttdocomo.ui.*;

public class HelloNtt extends IApplication {   // --- (1)

    public void start() {
        Display.setCurrent(new MyPanel());      // --- (2)
    }
    
    class MyPanel extends Panel implements ComponentListener{
    // --- (3)
        /**--- (4) ---**/
        private Label lbl = new Label("Your Name");
        private TextBox tbx =
        new TextBox("",16,1,TextBox.DISPLAY_ANY);
        private Button btn = new Button("Press");
        
        public  MyPanel(){
            /**--- (5) ---**/
            add(lbl);
            add(tbx);
            add(btn);
            
            setComponentListener(this);         // --- (6)
        }
        
        public void componentAction
        (Component source, int type, int param){
            /**--- (7) ---**/
            if(source == btn){
                Dialog d =
                new Dialog(Dialog.BUTTON_OK,"Message");
                d.setText("Hello " + tbx.getText());
                d.show();
            }
        }
    }
}

This example was taken from the beginners section of the Doja Development Network page without any modification.

Now simply build and run the project as any other Netbeans project and you should see the Doja emulator being launched with your newly HelloNtt IAppli on it.

Now with this part 3 of the blog you should be able to develop mobile applications for all the three major cellular phone carriers in Japan. EzAppli's for au/KDDI, S!-Applis for Softbank and IAppli's for NTTDoCoMo.