Create i-mode content with DoJa

With more than 40 million subscribers in Japan, NTT DoCoMo's i-mode is one of the most popular wireless Internet services in the world. Customers can get the latest news, download ringtones, and send messages. Two years after the service launched, in January 2001, NTT DoCoMo added a new feature to i-mode phones: DoJa, a version of the Java platform specially tailored to the mobile environment. i-mode Java applications are referred to as i-applis. Games are the most common type of i-appli, but the platform is equally well suited to network-centric applications.

NTT DoCoMo is building alliances to offer the i-mode service outside Japan. As of May 2005, i-mode Global is deployed in Taiwan, Germany, the Netherlands, Belgium, France, Spain, Italy, Greece, and Australia. Agreements have also been reached in Singapore, the United Kingdom, Ireland, Israel, and Russia. The DoJa Overseas Edition (DoJa OE) was created to provide an application platform that is largely compatible with Japanese content and that competes with the MIDP, the Java environment most often found in these countries.

Phones in Japan are released in series that have a common specification. The 503i series of phones was the first to feature DoJa and was provided using PDC, a 2G mobile phone standard. In addition to its Personal Digital Cellular (PDC)-based service, called mova, NTT DoCoMo also offers a 3G network based on Wideband Code Division Multiple Access (W-CDMA), called FOMA. Over time, NTT DoCoMo plans to phase out 2G phones in favor of 3G phones, the 700i and 900i series and their successors. Currently, handsets for i-mode Global use 2G networks, based on the Global System for Mobile Communications/General Packet Radio Service (GSM/GPRS) standard.

How the DoJa versions differ

Unlike DoJa OE, the current Japanese DoJa, version 4.0, is available exclusively on 3G phones, which allows for more generous network limits. There is also a DoJa 4.0 LE version for low-end 3G phones. DoJa 3.0 was the last version used on Japanese 2G phones of the 505i and 506i series.

DoJa 1.5 OE and DoJa 2.5 OE are based on DoJa 1.0 and DoJa 2.0, respectively, but each also contains classes from newer Japanese DoJa versions available at the time the specification was finalized. The APIs were selected to ensure that a large number of applications could run on both Japanese and overseas editions. DoJa 2.5 OE introduced one feature not found in Japan; it includes access to Short Message Service (SMS) functions.

Table 1 lists the differences between DoJa 1.5 OE and 2.5 OE and their Japanese counterpart, DoJa 4.0. The descriptions of some handsets distinguish between heap memory available to Java and heap used for native resources such as media data. In such cases, the sum of both heap sizes is given in Table 1.

Back to top

DoJa architecture

Figure 1 shows the main building blocks that form the DoJa architecture. The diagram's contents will be discussed in more detail in the following sections. In the remainder of this article I specifically discuss the features found in DoJa 2.5 OE, but the basics apply to all versions of DoJa.

Tool support

To help you develop your DoJa applications, NTT DoCoMo provides a toolkit that consists of an emulator and plug-ins for the Eclipse and Sun ONE Studio graphical development environments. The only supported operating systems are Windows™ 2000 (service pack 4) and XP (service pack 1). You will also need a Java 2 SDK version 1.3.1 or later.

The emulator can perform the tasks necessary to build and execute a DoJa application, but advanced features, such as obfuscation or performance monitoring, are not available. When you start a new project, the necessary folders are created automatically, and you can begin development by placing your source files in the src directory. Different application properties and start options can be used to emulate the execution of the application on a phone. The tool's build process outputs two files: a standard Java archive (JAR), with the extension .jar, that holds Java classes and resources; and an additional application descriptor file (ADF), with the extension .jam.

Applications inherit from com.nttdocomo.ui.IApplication and must implement the abstract method start(). Thus, the simplest possible DoJa application would be the one shown in Listing 1.

package dojasample;

import com.nttdocomo.ui.*;

public class SimpleMain extends IApplication
{
  public void start()
  {
    System.out.println("Hello DoJa World");
  }
}
        

The plug-ins that come with the DoJa toolkit officially support Eclipse version 2.1.1 and Sun ONE Studio 4, Community Edition. The former is still available from the archives of the Eclipse Web site. You can also use Eclipse 2.1.3 instead of version 2.1.1, but not version 3.x. Sun ONE Studio 4 has been discontinued by Sun. (The plug-ins are written to the APIs provided by the IDEs. The more recent versions of these IDEs provide different APIs, which is why the plug-ins don't work with those versions.)

With the DoJa plug-ins, you can start the emulator from within either IDE, and set breakpoints in your code and debug your applications. Of course, an emulator can only deliver an approximation of a real phone's behavior -- you are advised to test your application early and often on real devices. After you have your application ready for installation, the only way to transfer it to a phone is through a mobile network connection.

i-mode employs the concept of the so-called semi-walled garden; content providers can gain advantages, such as placement in the i-mode menu, by coming to an agreement with NTT DoCoMo, but anyone can offer content on an unofficial site. Any Web server that is accessible over the Internet can offer your application for download. You need to place your application's JAR and ADF files on the Web server, along with an HTML page that contains code to trigger the download of the application. Listing 2 shows the necessary code. It uses the object tag to declare an application and the a tag with the ijam property to create a link that can be selected by the user to download the software.

<html>
  <body>
    <object declare id="DoJa Sample" data="dojasample.jam" type="application/x-jam">
    </object>
    <a ijam="#DoJa Sample" href="error.html">Download DoJa sample.</a>
  </body>
</html>
        

Java Application Manager

On the phone, the Java Application Manager (JAM) takes over the responsibility for your application and handles the installation, upgrade, deletion, and execution of your software. The JAM first downloads the descriptor file and analyzes its contents before downloading the actual Java software. The ADF contains key/value pairs separated by equal signs (=) and has five mandatory properties:

• AppName: Your application's name. Only one application is allowed per JAR file.
• PackageURL: The link to the JAR file.
• AppSize: The size of your JAR file.
• AppClass: The main class of your application.
• LastModified: Version information, in the form of a timestamp. The JAM uses this information to determine if your application needs updating.

The emulator creates values for AppSize and LastModified automatically; the other properties need to be specified by the developer. If needed, optional keys can be configured for permission requirements and other attributes of an application.

In a typical scenario, the user would select and start an application from a list displayed by the phone's user interface. However, DoJa also foresees other ways of starting a Java program:

• Automatic launch at regular intervals, as specified in the ADF file.
• Startup from mail, OBEX, or SMS software. These native applications can trigger the start of an already installed application by receiving specially formatted messages.
• Startup from a browser. The application could be launched directly after download; alternately, a special HTML tag can start up an application that's already on the phone.
• Startup from another Java application.
• Startup as a standby application. These applications are resident and displayed as part of the standby screen, the same way that a background picture is displayed. They are started automatically whenever the user returns to the standby screen, and suspended or terminated when a call comes in or another Java application is launched. One potential use for a standby application would be a calendar that displays current appointments. Standby applications inherit from MApplication rather than IApplication.

DoJa and CLDC

The Connected, Limited Device Configuration (CLDC) as specified by the Java Community Process is the basis of the DoJa environment. The configuration defines a subset of the Java programming language and VM features as well as a core set of Java APIs. DoJa 4.0 in Japan uses CLDC 1.1; for DoJa 2.5 OE, manufacturers can choose to support either CLDC 1.0 or 1.1.

In CLDC, the Generic Connection Framework (GCF) was introduced to provide a low-footprint and extensible API for network I/O. In DoJa, the framework is used for access to persistent storage, loading of resources from the JAR file, HTTP/HTTPS communication, and the OBEX protocol. As specified in the CLDC, Java classes need to be preverified after being compiled. This includes additional information in the class file that makes it easier for the VM to verify that classes are valid; the emulator takes care of the necessary steps. Depending on which CLDC version your device supports, different limitations apply; for example, CLDC 1.0 doesn't support floating point operations.

User interface

All DoJa classes other than the CLDC APIs are proprietary to NTT DoCoMo. The majority of classes concern the user interface; they can be split into high-level and low-level APIs. High-level UI classes are used to build screens from standard components; low-level UI classes enable you to draw directly on the screen using graphics primitives.

A screen on the display is represented by subclasses of Frame, such as Dialog and Panel. UI components can be added to a Panel that acts as a container. The high-level APIs were designed in a way that enables you to build the same user interfaces as you can with i-mode-compatible HTML. UI events can be received by setting the respective listener. Listing 3 shows how to display a button and receive an event when it is pressed:

package dojasample;

import com.nttdocomo.ui.*;

public class HighLevelUiSample extends Panel implements Sample,
    ComponentListener
{
  private Label _status;

  public HighLevelUiSample()
  {
    Button button = new Button("Button");
    add(button);
    _status = new Label();
    add(_status);
    setComponentListener(this);
  }

  public void componentAction(Component source, int type, int param)
  {
    if (type == BUTTON_PRESSED)
    {
      _status.setText("Button pressed");
    }
  }

  ...
}
        

You can use Canvas, another subclass of Frame, if you need more control over the appearance of your screens. Canvas provides a Graphics object with drawing primitives. Double buffering is controlled by lock() and unlock(); before drawing, the screen is locked and buffering starts -- afterwards, the contents can be flashed to the screen by unlocking the Graphics object. This process is illustrated in Listing 4.

package dojasample;

import com.nttdocomo.ui.*;

public class LowLevelUiSample extends Canvas implements Sample
{
  ...

  public void paint(Graphics graphics)
  {
    graphics.lock();

    graphics.clearRect(0, 0, getWidth(), getHeight());
    graphics.drawRect(0, 0, getWidth() - 1, getHeight() - 1);
    graphics.drawArc(0, 0, getWidth() - 1, getHeight() - 1, 0, 360);
    graphics.drawLine(getWidth() / 2, 0, getWidth() / 2, getHeight());
    graphics.drawLine(0, getHeight() / 2, getWidth(), getHeight() / 2);

    graphics.unlock(true);
  }

  ...
}
        

Media playback

The com.nttdocomo.ui package also includes classes for media playback. AudioPresenter can handle several audio formats, such as SMF (Standard MIDI File) and MFi (Melody Format for i-mode); VisualPresenter handles picture and video formats, such as JPEG, GIF (also animated), and MPEG4. (Please note that not every phone has to support all of these media formats.)

Before a media resource such as an animated GIF can be played, the resource must first be retrieved from the MediaManager. Then, the media object's use() method must be called before it is actually loaded into memory and ready. Listing 5 illustrates the process.

package dojasample;

import com.nttdocomo.ui.*;

public class MediaSample extends Panel implements Sample
{
  private VisualPresenter _visualPresenter;

  public MediaSample()
  {
    MediaImage mediaImage = MediaManager.getImage("resource:///animation.gif");

    try
    {
      mediaImage.use();
    }
    catch (Exception e)
    {
      System.out.println("Error using media");
    }

    _visualPresenter = new VisualPresenter();
    _visualPresenter.setImage(mediaImage);
    add(_visualPresenter);
  }

  public void show()
  {
    _visualPresenter.play();
  }

  ...
}
        

In Listing 5, a picture in GIF format is loaded from the JAR file and its animation started by calling VisualPresenter.play(). After you are finished with the resource, you can call MediaResource.unuse() and dispose(). In a similar fashion, you can play audio files by using AudioPresenter.

Scratchpad

The scratchpad is a non-volatile memory area where data that needs to be persistent between invocations of an application can be stored. It is a contiguous chunk of memory that you have to structure yourself. An application can use up to 16 scratchpads, whose sizes in bytes have to be specified in the SPsize key of the descriptor file, and whose total size cannot exceed 200 KB. For example SPsize = 10240, 10240 reserves two scratchpads, each 10 KB in size. For security reasons, data cannot be shared between applications.

The data is accessed using CLDC's Generic Connection Framework by using URLs in the following format:

scratchpad:///<number> [;pos=<start-point> [,length=<access-length>]]

Here, <number> determines which scratchpad is used; <start-point> provides an initial offset from which data is read or written; and <access-length> can be specified to set a maximum data length. After the connection is opened, data can be accessed using standard I/O classes such as DataInputStream or DataOutputStream, as in Listing 6. This code uses an SPsize value of four to fit in an int type.

package dojasample;

import java.io.*;
import javax.microedition.io.*;
import com.nttdocomo.ui.*;

public class ScratchpadSample extends Panel implements Sample
{
  ...

  private void storeNumber(int number)
  {
    DataOutputStream dos = null;

    try
    {
      dos = Connector.openDataOutputStream("scratchpad:///0");
      dos.writeInt(number);
      dos.close();
    }
    catch (IOException e)
    {
      System.out.println("Error writing number");
    }
    finally
    {
      try
      {
        if (dos != null)
          dos.close();
      }
      catch (IOException ignored)
      {}
    }
  }

  private int retrieveNumber()
  {
    int number = 0;
    DataInputStream dis = null;

    try
    {
      dis = Connector.openDataInputStream("scratchpad:///0");
      number = dis.readInt();
      dis.close();
    }
    catch (IOException e)
    {
      System.out.println("Error reading number");
    }
    finally
    {
      try
      {
        if (dis != null)
          dis.close();
      }
      catch (IOException ignored)
      {}
    }

    return number;
  }

  ...
}
        

Network I/O

The GCF is not only used for scratchpad and resource access; it is also used for network communication. HttpConnection serves as the entry point to HTTP and HTTPS communication; ClientObexConnection and ServerObexConnection are used for the OBEX protocol.

Application linking

Interaction between Java applications and other phone software is referred to as application linking. You already saw how to launch a Java program from other applications in the Java Application Manager section. In addition, DoJa also provides APIs that allow Java code to access the following native programs:

• Browser
• Java application update functions
• SMS
• Voice call
• Phonebook
• Bookmark
• Scheduler
• Image data management
• Camera

Listing 7 shows how to add a new bookmark to the phone's built-in Web browser. For security reasons, the access must be declared in the ADF. In this case, AccessUserInfo must be set to yes.

package dojasample;

import com.nttdocomo.system.*;
import com.nttdocomo.ui.*;

public class ApplicationLinkingSample extends Panel implements Sample
{
  ...

  public void show()
  {
    try
    {
      int id = Bookmark.addEntry("http://www.ibm.com/developerworks/",
          "developerWorks");

      if (id == -1)
      {
        _status.setText("Bookmark canceled");
      }
      else
      {
        _status.setText("Bookmark id " + id);
      }
    }
    catch (InterruptedOperationException e)
    {
      _status.setText("Bookmark error");
    }
  }

  ...
}
        

Optional APIs

Manufacturers can choose to provide additional APIs that extend the standard set and use a common interface if installed. In Japan, advanced features are often first introduced as optional APIs and get promoted to standard interfaces after they become part of the mainstream. Other features, such as fingerprint authentication, always remain optional because not all phones are equipped with the necessary hardware.

DoJa 1.5 OE does not have any optional parts, but in version 2.5, the most important optional feature is 3D support in the package com.nttdocomo.opt.ui.j3d. In addition, an extended AudioPresenter that supports tempo adjustment and key shifting has been introduced, along with a subclass of Image called TransparentImage that can handle transparency. Other functions, such as sprite and camera support, are available in both com.nttdocomo.ui and com.nttdocomo.opt.ui. Classes in the latter package are deprecated and only exist to maintain compatibility with the original Japanese DoJa version.

If you use an optional API, you may need to determine what phone model your code is running on before making use of optional features. You can distinguish between different phones by:

• Testing the model-specific string that is part of the browser's user agent header.
• Specifying each device you target in the TargetDevice key of your application descriptor file. The Java Application Manager will only install your application if the phone is included in this property.
• Retrieving the mobile phone's model name by using System.getProperty("microedition.platform") inside your application.

Back to top

DoJa and MIDP compared

If you are familiar with MIDP, you will have little trouble finding your way around DoJa.

Both versions of Java have CLDC in common. APIs defined in the CLDC specification and the build process, including the preverification step, are identical. In the same manner, DoJa's Java Application Manager and MIDP's Application Management Software share many concepts; they first check a descriptor file before they actually download the application. They use different properties and formats, but in both cases the application descriptor fulfills the same purpose.

The APIs on top of the CLDC are different, although there is a large overlap in functions. Applications that rely heavily on low-level graphics such as games will be relatively easy to port. DoJa and MIDP both have a Graphics class, and both Graphics classes have similar methods. Care must be taken to properly use DoJa's lock() and unlock() mechanism for double buffering. You'll also need to replace MIDP's Display.callSerially() and Canvas.serviceRepaints() APIs with your own synchronization mechanism. For DoJa 1.5 OE, clipping and off-screen drawing are not supported.

Other porting tips:

• For high-level UI components, look for similar classes in com.nttdocomo.ui and javax.microedition.lcdui. Often you can find a good replacement. MIDP's Form and Alert correspond to DoJa's Panel and Dialog. In DoJa, you cannot assign several commands to one soft key as you can in MIDP.
• For DoJa's AudioPresenter, look for corresponding classes in javax.microedition.media.
• MIDP's Record Management System corresponds to DoJa's scratchpad. The record-oriented access is replaced by an unstructured memory area.
• HTTP and HTTPS communication should be easy to replace by using classes from javax.microedition.io and com.nttdocomo.io, respectively.
• The maximum application size of DoJa 2.5 OE applications is 30 KB, which can be challenging. The supported size of MIDP applications depends on the manufacturer, but is usually larger.

MIDP 1.0 applications will be easier to port to the DoJa platform than applications that use MIDP 2.0 just because the specification contains fewer features. Conversely, replacements for DoJa APIs can sometimes be found in optional APIs that extend MIDP. For example, OBEX communication is specified in JSR-82 and 3D support in JSR-184.

Back to top

In conclusion

In this article, I have described DoJa, the Java platform that is part of i-mode. A special edition for usage worldwide, the DoJa Overseas Edition has been created and designed to be largely compatible with Japanese content. I have compared MIDP with DoJa; although the two differ in details, they have similar concepts.

This should get you started building your own i-applis. i-mode is available worldwide and DoJa might be the perfect fit for your application.

Back to top

Download

Information about download methods

Resources

• Download the specifications and tools for DoJa Overseas Edition from the DoJa Developer Network. This site contains a list of supported handsets and other useful information.
  
  
• "J2ME 101, Part 1: Introduction to MIDP's high-level user interface" (developerWorks, November 2003) is a helpful tutorial on MIDP.
  
  
• Browse for books on these and other technical topics.
  
  
• The IBM Redbook "Using WebSphere Studio Device Developer to Build Embedded Java Applications" can help you learn more about CLDC and MIDP.
  
  
• IBM Forms for Mobile Devices is an XML-based alphaWorks technology that provides a robust platform on which application developers can quickly create and deploy robust, forms-based enterprise applications on mobile devices.
  
  

About the author

Comments

Back to top

Trademarks

Table of contents

• How the DoJa versions differ
• DoJa architecture
• DoJa and MIDP compared
• In conclusion
• Download
• Resources
• About the author
• Comments