Developing for Japanese Phones in Netbeans (Part 1)

Netbeans Mobility Pack

Developing for J2ME applications for the primary carriers in Japan can be a living nightmare. There are three main mobile phone carriers in Japan: au/KDDI, Voda Phone (now Softbank) and NttDocomo. Each of these providers have a midraid of phones of all sizes and capabilities and each week there are new ones. Here in Japan people change phones as often as their underwear...

For a J2ME application to be successful it must be compatible with the current phones used at the moment which means that development never stops and evolves very, very fast. As new phones come with new MIDP profiles and propietary extensions programming this little MIDLet's is a new experience each time.

I am a VIM guy and I am used to develop huge enterprise projects and web applications in a console with screen+vim. But for J2ME development I really recomend an IDE especially Netbeans with it's preprocessor to handle device fragmentation.

Developing a J2ME application requires several steps like class preverification, ofuscation, signing, packing, deployment. These steps can vary from carrier to carrier and even from phone to phone of the same carrier. A single change on the source code would require to excecute all these steps for each phone of each carrier and doing by hand is tedious and error prone. This gets worse if we have a different source code for each phone (Device Fragmentation Problem).

The Mobility Pack of Netbeans is a lifesaver in this case with support for several configurations in a single project. But life is not perfect and the only carrier that provide UIC compliant development environments is Voda Phone. To develop au and NttDocomo applications in Netbeans we must do some magic.

Installing Ez Appli's (au/KDDI) Toolkit

To develop an Ez Appli we need to download the tool kit Ez Appli. Just click where it says 同意する that means you accept the agreement. In the next page click where it says ダウンロード to download the tool kit. You will end with a file called "ezplus_emulator.exe".

You can also download a programming guide and the KDDIP javadoc files from this page but they are useless if you cannot read Japanese.

To install the tool kit simply double click the exe file and accept any defaults you get except for the install directory part. When the installation programs asks for an installation path make sure the path has no blank spaces. I have found the emulator cannot understand spaces on the path names.

From now on I assume the toolkit is installed in c:\ezplus. Inside that directory must be an structure like:

-- Doc               -> PDF files with manual and guide
-- Tools
   -- CmdTool        -> Development Tools
   -- Emulator       -> Contains the phone emulator
   -- KDDIP          -> Contains the KDDIP library

Steps for Ez Appli Development

There are several steps involved in developing an Ez Appli. The tool kit contains a CmdTool that sorts of eases the job but is not that feature rich. Ez Appli development is very similar to J2ME MIDLet development. We need to create a MIDLet (jar file) and a Description file (jad file). This includes preverification and ofuscation of the classes and source code etc.

When developing MIDLets the jar and jad files are enough to run the application. In the case of Ez Appli we must create a KJX file using the KJXArchiver.jar that comes with the toolkit. All au phones need this KJX file to excecute the application.

All these steps can be done manually or by using the CmdTool that comes with the tool kit. As I said this can be error prone and tedious when there are several versions of the source code to support several devices.

Ez Appli configurations and profiles

Ez Appli's use the CLCD1.0 configuration and the MIDP1.0 profile combined with the au custom profile KDDIP. The KDDIP profile simply adds classes to control the phones hardware (backlight, vibration, etc) and to access services specific to au (c-mail, smarf, e-mail, etc.). If you can read a little japanese then the documentation that comes with the tool kit can give you an idea of what you can do.

Fortunatelly since we want to create applications that run equally in all carrier phones we must avoid all custom classes. This completely eliminates KDDIP classes from the picture and we end with MIDP1.0. This means that we can write a MIDLet using the J2ME english documentation available on the net and it will run without too much problems on au phones and hopefully also run on Vodaphone phones.

Even without using the KDDIP profiles we must understand some physical limitations present on the phones that depend on the profile they can run. There are several versions of KDDIP profiles listed below:

Version	KXJ Size	RecordStore Size
Phase1	50KB	10KB
Phase2	50KB	10KB
Phase2.5	50KB	10KB
Phase3	150KB	10KB + 100KB extended

The KJX size refers to the maximum size the Ez Appli can have. Any KJX file larger than the limit will not download to the real phones even if it runs well on the emulator. The RecordStore limit refers to the max amount of persitent storage the phone can handle.

Ez Appli Development With Netbeans

With Netbeans is easy to add new J2ME development platforms in the Tool->Java Platform Manager->Add Platform dialog. With this dialog we can simply point to the directory where the tool kit is installed and all the black magick is done for us.

Unfortunatelly this only works for tool kits that comply with the UEI (Universal Emulator Interface) standard and the Ez Appli toolkit is not compatible. But don't despair! we can add custom tool kits with some work. Essentially what we need to do is to tell Netbeans the steps it must follow to create an Ez Appli.

For au I took the time to generate the platform definitions for the KDDIP Phase1 and Phase2 profiles.

Phase1.xml file:

<!DOCTYPE platform PUBLIC '-//NetBeans//DTD J2ME PlatformDefinition 1.0//EN'
             'http://www.netbeans.org/dtds/j2me-platformdefinition-1_0.dtd'>

<platform name="ezplusTool" home="C:\ezplus" type="custom"
      displayname="KDDI Phase1" srcpath="" docpath="${platform.home}/doc"   
      preverifycmd=""C:/WTK22/bin/preverify.exe"
      -classpath "{classpath}" -d "{destdir}"
      "{srcdir}""
      runcmd=""
>
 <device name="C452CA/C451H" securitydomains="trusted,untrusted" description="Phase 2 Devices">
     <configuration name="CLDC" version="1.0" displayname="CLDC1.0"
               classpath="C:/WTK22/lib/cldcapi10.jar" dependencies="" default="true"/>
    
     <profile name="KDDIP" version="1.0" displayname="KDDIP1.0"
                   classpath="C:/WTK22/lib/midpapi10.jar;${platform.home}/Tools/KDDI-P/kddip.jar"
                   dependencies="" default="true"/>
       </device>

</platform>

Phase2.xml file:

<!DOCTYPE platform PUBLIC '-//NetBeans//DTD J2ME PlatformDefinition 1.0//EN'
'http://www.netbeans.org/dtds/j2me-platformdefinition-1_0.dtd'>>
<platform name="ezplusTool" home="C:\ezplus" type="custom" displayname="KDDI
 Phase2" srcpath="" docpath="${platform.home}/doc"
 preverifycmd=""C:/WTK22/bin/preverify.exe"
 -classpath "{classpath}" -d "{destdir}"
 "{srcdir}""
 runcmd="">
 
 <device name="C3001H/C3002K/C5001T/A3011SA/A3012CA/A3013T/A3014S"
  securitydomains="trusted,untrusted" description="Phase 2 Devices">
    
  <configuration name="CLDC" version="1.0" displayname="CLDC1.0"
   classpath="C:/WTK22/lib/cldcapi10.jar" dependencies="" default="true"/>
 
  <profile name="KDDIP" version="2.0" displayname="KDDIP2.0"
   classpath="C:/WTK22/lib/midpapi10.jar;${platform.home}/Tools/KDDI-P/kddip.jar"
   dependencies="" default="true"/>
       </device>

</platform>

These are simply XML files that defines the environment needed to build Ez Appli's. You do not need to understand the syntax and simply save them inside the "Services\Platforms\org-netbeans-api-java-Platform" directory inside your .netbeans config directory.

From the definition file you can see that the Ezplus toolkit makes use of the preverify command and the midpapi.zip library from the Wireless Toolkit. Make sure you set the path to these two files to reflect the installation path of the Wireless Toolkit in your machine. If you do not have the Wireless Toolkit installed you can use the one installed with Netbeans. I have tested these platform definitions files with Netbeans 4.1 and 5.0 without any visible problems.

Also make sure the path to the kddip.jar file coincides to the path where you installed the Ezplus toolkit.

After saving this files in the appropiate place when you restart Netbeans you will see the two new platforms added to the list of J2ME Platforms in the Java Platform Manager of Netbeans. They will be called KDDI Phase1 and KDDI Phase2 respectively.

Ez Appli Hello World

Now we can try to develop a simple Hello World Ez Appli. With Netbeans create a new Mobile Application Project (File->New Project->Mobile->Mobile Application) and proceed with the project creation dialog as normal until you get the the Default Platform Selection dialog. Here make sure to select any of the new platforms as default platform. The CLCD1.0 and KDDIP1.0/KDDIP2.0 will be selected automatically depending on the profile you chose.

Next select other platforms templates if you want and finish the creation process. At this point we should have a new Mobile Project ready to start development. Before we compile we need to modify the build.xml script a little to handle the KJX file creation and to invoke the Ez plus emulator when running the project. To do this simply open the build.xml file of the project and add these tags inside the <project> and </project> tags.

 <target description="Create AU KJX file" name="post-jar">
    <java jar="${platform.home}/Tools/CmdTool/KJXArchiver.jar" fork="true">
       <arg line="-c ${dist.dir}/${dist.jad} ${dist.dir}/${dist.jar} {dist.dir}/${name}.kjx">
    </java>
 </target>
  
 <target name="run" depends="init,post-jar">
    <exec executable="${platform.home}/Tools/Emulator/run.bat" dir="${dist.dir}">
        <arg value="${basedir}/${dist.dir}/${name}.kjx">
    </exec>  
 </target>   

The code above defines two ant tasks in the build.xml file. One is to generate the KXJ file using the KJXArchiver that comes with the Ezplus toolkit. The other task is to call the emulator with the created KJX file. This task requires a run.bat file I generated to call the emulator. Simply copy the next file a run.bat inside the Emulator subdirectory of the Ezplus toolkit:.

@echo off
cd C:\j2me\ToolKits\ezplusTools\Tools\Emulator
javaw -jar jbmidp.jar %1

Of course make sure you change the path to reflect that of your machine. With the build.xml file in order we can now create a simple MIDLet as usual. With the project select create a ne MIDLet (Right Click->New->MIDLet) and edit the source as a normal MIDLet. Here is my example source code:

import javax.microedition.midlet.*;
import javax.microedition.lcdui.*;

public class HelloKddi extends MIDlet {
    public void startApp() {
        Display.getDisplay(this).setCurrent(new HelloCanvas());
    }
    
    public void pauseApp() {
    }
    
    public void destroyApp(boolean unconditional) {
    }
    
    public class HelloCanvas extends Canvas {
 public void paint(Graphics g) {
            g.setColor(0,222,100);                  
            g.drawString("Hello World",40,20,Graphics.TOP|Graphics.HCENTER);
 }
    }
}

If you have ever programed a MIDLet for any other mobile device based on the MIDP profile you will see that these one is identical.

Now we can build and run this application as any other Netbeans project with the context menu (right click). Not only that we can now add new configurations to the project and use all features of the Mobility Pack to develop for au (KDDI) phones.

Notes

I was able to create platform configurations for Phase1 and Phase2 of the Ezplus toolkit. For Phase2.5 and Phase3 there is a different toolkit but I am unable to make it work with Netbeans. In fact I am not able to develop with that toolkit even with the CmdTool that comes with it.

Since au gives priority to the Brew platform and not to J2ME the kind of applications we can develop for au phones is very limited. If you want to develop rich applications for au Phones you better start learning Brew.

In subsequent posts I will talk about Vodaphone (JSCL/MEXA) and NttDocomo (Doja) development using Netbeans.