MIDP for Palm OS 1.0: Developing Java Applications for Palm OS Devices

If you are new to wireless software development, it is easy to get started. Start by looking at the MIDP series of articles that explain the CLDC/MIDP and shows how to get started with programming.

Installing the MIDP for Palm OS on the Windows Platform

To install the MIDP for Palm OS:

1. Download the MIDP for Palm OS 1.0. This package (midp4palm-1_0.zip), which is about 500KB (excluding the documentation), is the FCS of the MIDP for Palm OS 1.0 implementation.
2. Unzip the package in the root directory c:\

   This gives you a new folder called midp4palm1.0 that contains tools and sample applications. Check to make sure you have a file called MIDP.prc in the PRCfiles directory, which is the application runtime environment that supports MIDP for Palm OS.

   Now you are ready to install the MIDP for Palm OS on your Palm device.

Installing the MIDP for Palm OS on the Device

Use HotSync to install the MIDP.prc on your Palm device.

1. Place your Palm device in the cradle.
2. Using your Palm Desktop software on the PC (or a similar program), click the install icon and browse to c:\midp4palm1.0 to select MIDP.prc. Press the HotSync button on the cradle to install the file.
3. Go to the application directory on your Palm and check to see if the Java HQ is there. Java HQ is the application runtime environment that supports MIDP for Palm OS. Note that the Java HQ environment takes up roughly 600K of your Palm device's storage.

   You should see the Java HQ icon as shown in Figure 1. If you do not see it, click on another application (for example, calculator) and then go back to the application directory.

Figure 1: Java HQ special icon on Palm

If you tap the Java HQ icon, you see the About screen (as shown in Figure 2) that contains the copyright notice, and gives you the option to change the Java HQ preferences, which apply to every Java application running on the device.

Figure 2: Java HQ's About Screen

Now you are ready to install other Java applications on your Palm.

Running Sample Applications

There are several applications written in Java for the Palm that come with the software you just installed. All the files that end with (or have the extension) prc in the directory c:\midp4palm1.0\PRCfiles are MIDP-based Java applications for the Palm. You can use HotSync to install them.

As an example, use HotSync and install the files Demos.prc and Games.prc. Once you have installed these two files, you see two new special icons as shown in Figure 3.

Figure 3: Installing sample MIDP-based Java applications

A MIDP-based Java application for the Palm runs just like any other Palm application -- simply by tapping the corresponding icon. Note that the Java HQ must have already been installed. When you launch a Java application on the Palm, the Java HQ runs automatically. Also, it is important to note that the first time you launch the application, you are asked to read and accept the MIDP license; the login MIDlet starts automatically once you tap Accept as shown in Figure 4.

Figure 4: Running Java Applications on the Palm for the first time

If you open an application suite (such as Demos), you are prompted to choose which application you want to run. Select an application to run by tapping on its arrow.

Developing New Applications

Developing new Java applications for the Palm can be easily done if you are familiar with the MIDlet programming model. If you have developed MIDlets, you can automatically turn them into Palm applications using the converter tool, which comes with the MIDP4Palm.

The development life cycle of a Palm application can be summarized in the following three steps:

• Develop a MIDlet or a MIDlet suite.
• Convert the JAR/JAD files into a PRC file (executable Palm application).
• Install the PRC file on the Palm and test the application.

Develop a MIDlet

You can use your favorite development environment to develop a MIDlet. Some of the development environments that support MIDP include:

• Zucotto's WHITEboard SDK

Now, let's develop a sample MIDlet that demonstrates how to create various GUI components. The MIDlet for this example allows you to test lists, forms, choices, gauges, text fields, and text boxes. The GuiTests MIDlet, which is similar to a MIDlet developed in the Programming the Phone Interface article, is shown in Sample 1.

Sample 1: GuiTests.java

import javax.microedition.lcdui.*;
                      

import javax.microedition.midlet.*;
                      

                       

public class GuiTests extends MIDlet
                      

implements CommandListener {
                      

    // display manager
                      

    Display display = null;
                      

    
                      

    // a menu with items
                      

    List menu = null; // main menu
                      

                       

    // list of choices
                      

    List choose = null;
                      

                       

    // textbox
                      

    TextBox input = null;
                      

                       

    // ticker
                      

    Ticker ticker = new Ticker(
                      

    "Test GUI Components");
                      

                       

    // alerts
                      

    final Alert soundAlert =
                      

    new Alert("sound Alert");
                      

                       

    // date
                      

    DateField date = new DateField("Today's date: ",
                      

    DateField.DATE);
                      

                       

    // form
                      

    Form form = new Form("Form for Stuff");
                      

     
                      

    // gauge
                      

    Gauge gauge = new Gauge(
                      

    "Progress Bar", false, 20, 9);
                      

                       

    // text field
                      

    TextField textfield = new TextField(
                      

    "TextField Label",
                      

     "abc", 50, 0);
                      

                       

    // command
                      

    static final Command backCommand =
                      

     new Command("Back", Command.BACK, 0);
                      

    static final Command mainMenuCommand =
                      

    new Command("Main", Command.SCREEN, 1);
                      

    static final Command exitCommand =
                      

     new Command("Exit", Command.STOP, 2);
                      

    String currentMenu = null;
                      

                       

    // constructor.
                      

    public GuiTests() {
                      

    }
                      

                       

    /**
                      

     * Start the MIDlet by creating a list of
                      

     items and associating the
                      

     * exit command with it.
                      

     */
                      

    public void startApp() throws
                      

    MIDletStateChangeException {
                      

      display = Display.getDisplay(this);
                      

      // open a db stock file
                      

                       

      menu = new List(
                      

      "Test Components", Choice.IMPLICIT);
                      

      menu.append("Test TextBox", null);
                      

      menu.append("Test List", null);
                      

      menu.append("Test Alert", null);
                      

      menu.append("Test Date", null);
                      

      menu.append("Test Form", null);
                      

      menu.addCommand(exitCommand);
                      

      menu.setCommandListener(this);
                      

      menu.setTicker(ticker);
                      

                       

      mainMenu();
                      

    }
                      

                       

    public void pauseApp() {
                      

      display = null;
                      

      choose = null;
                      

      menu = null;
                      

      ticker = null;
                      

      form = null;
                      

      input = null;
                      

      gauge = null;
                      

      textfield = null;      
                      

    }
                      

                       

    public void destroyApp(boolean unconditional) {
                      

      notifyDestroyed();
                      

    }
                      

                       

    // main menu
                      

    void mainMenu() {
                      

      display.setCurrent(menu);
                      

      currentMenu = "Main";
                      

    }
                      

                       

    /**
                      

     * Test the TextBox component.
                      

     */
                      

    public void testTextBox() {
                      

      input = new TextBox
                      

      ("Enter Some Text:", "", 10, TextField.ANY);
                      

      input.setTicker(new Ticker(
                      

      "Testing TextBox"));
                      

      input.addCommand(backCommand);
                      

      input.setCommandListener(this);
                      

      input.setString("");
                      

      display.setCurrent(input);
                      

      currentMenu = "input";
                      

    }
                      

   
                      

    /**
                      

     * Test the List component.
                      

     */
                      

    public void testList() {
                      

        choose = new List("Choose Items",
                      

        Choice.MULTIPLE);
                      

        choose.setTicker(new Ticker(
                      

        "Testing List"));
                      

        choose.addCommand(backCommand);
                      

        choose.setCommandListener(this);
                      

        choose.append("Item 1", null);
                      

        choose.append("Item 2", null);
                      

        choose.append("Item 3", null);
                      

        display.setCurrent(choose);
                      

        currentMenu = "list";
                      

   }
                      

                       

   /**
                      

    * Test the Alert component.
                      

    */
                      

   public void testAlert() {
                      

      soundAlert.setType(AlertType.ERROR);
                      

      //soundAlert.setTimeout(20);
                      

      soundAlert.setString("** ERROR **");
                      

      display.setCurrent(soundAlert);
                      

   }
                      

                       

   /**
                      

    * Test the DateField component.
                      

    */
                      

   public void testDate() {
                      

      java.util.Date now = new java.util.Date();
                      

      date.setDate(now);
                      

      Form f = new Form("Today's date");
                      

      f.append(date);
                      

      f.addCommand(backCommand);
                      

      f.setCommandListener(this);
                      

      display.setCurrent(f);
                      

      currentMenu = "date";
                      

   }
                      

                       

   /**
                      

    * Test the Form component.
                      

    */
                      

   public void testForm() {
                      

      form.append(gauge);
                      

      form.append(textfield);
                      

      form.addCommand(backCommand);
                      

      form.setCommandListener(this);
                      

      display.setCurrent(form);
                      

      currentMenu = "form";
                      

   }
                      

                       

   /**
                      

    * Handle events.
                      

    */  
                      

   public void commandAction(Command c,
                      

   Displayable d) {
                      

      String label = c.getLabel();
                      

      if (label.equals("Exit")) {
                      

         destroyApp(true);
                      

      } else if (label.equals("Back")) {
                      

          if(currentMenu.equals("list")
                      

          || currentMenu.equals("input") ||
                      

               currentMenu.equals("date")
                      

               || currentMenu.equals("form")) {
                      

            // go back to menu
                      

            mainMenu();
                      

          }
                      

                       

      } else {
                      

         List down = (List)display.getCurrent();
                      

         switch(down.getSelectedIndex()) {
                      

           case 0: testTextBox();break;
                      

           case 1: testList();break;
                      

           case 2: testAlert();break;
                      

           case 3: testDate();break;
                      

           case 4: testForm();break;
                      

         }
                      

            
                      

      }
                      

  }
                      

}

If you like, you can test the application using a MIDP emulator (using the J2ME Wireless Toolkit, for example) at this point.

Convert a MIDlet into a PRC file

Build the MIDlet in Sample 1 to make sure there are no compilation errors. Most development tools would create a JAR and a JAD file for you automatically. These are the two files needed to convert a MIDlet (or a MIDlet suite) into a PRC file. If you are using the J2ME Wireless Toolkit, the JAR and JAD files will be in the bin directory of your project. For example, if your project name is gui then the gui.jad and gui.jar can be found in the directory c:\j2mewtk\apps\gui\bin.

The MIDP for Palm OS comes with a converter tool to convert a MIDlet to an executable Palm application, with the extension PRC. To run the PRC converter tool, you can use the batch file ( c:\midp4palm1.0\Converter\converter.bat) distributed with the release. However, if you have set the Java_HOME environment variable on your desktop, edit the converter.bat file and change all JAVA_PATH to JAVA_HOME and then run the converter batch file. Alternatively, you can run the tool using the command: java -jar Converter.jar. The Converter.jar archive, located in c:\midp4palm1.0\Converter, contains the implementation for the PRC converter tool.

Now, select Convert from the File menu, and navigate to the directory where the JAD and JAR files are located (both files must be in the same directory). Select the JAD file to be converted, then click on the Convert button to convert the file into a PRC file. You will see a success message as shown in Figure 5.

>

Figure 5: Converting JAD/JAR to PRC

By default, the converted PRC file will be saved in the same directory as the JAD/JAR file pair. If you like, you can save all converted PRC files under another directory by choosing Preferences from the Converter's File menu, then you can select a folder of your choice for output.

Install and Test

Once the JAD/JAR file pair have been converted to a PRC file, you can install it on your Palm OS device using HotSync. Once installed, you can run it and select components to test as shown in Figure 6. Here we have tested a form (with a progress bar and a text field), an alert, and a date.

Figure 6: Testing a MIDP Application for the Palm OS

Command Line Conversion

The PRC GUI-based converter tool is easy to use. But this comes at the expense of functionality. For example, what if you wish to associate a new icon with your application rather than have the default icon? The command line converter tool offers you more flexibility and options in how you convert your MIDlets into PRC files?

The MIDP for Palm OS distribution comes with a command line tool for converting JAR to PRC files. The tool is the MakeMIDPApp application, which is part of the Converter.jar file. To use it, use the command:

c:\midp4palm1.0\converter> java -cp Converter.jar com.sun.midp.palm.database.MakeMIDPApp [options] JARfile

where options can be any of those shown in Table 1:

This command line tool can be used to produce PRC files from a single MIDlet or a MIDlet suite. For example, the following command can be used to convert a JAR file (containing one MIDlet or a MIDlet suite) to a PRC file:

c:\midp4palm1.0\converter> java -cp Converter.jar com.sun.midp.palm.database.MakeMIDPApp -type Data gui.jar

This command will produce a PRC file called gui.prc from the JAR file gui.jar.

Note that the type of application being converted can be either appl or Data (case sensitive). If you do not provide the -type option, then MakeMIDPApp uses the default type which is appl. It is important to note, however, that if you do not provide a creator ID with the -creator option, then you must set the type to Data. The creator ID specifies the unique, four-character identifier for a Palm application. Every Palm application must have a creator ID, and if you do not provide one then MakeMIDPApp will automatically generate a creator ID for your application. To find out what it is, use the -v -v option.

Note: Every Palm OS application must have a a creator ID. IDs are case-sensitive and the ones with all lower-case letters are reserved for use by Palm Inc. Palm recommends that you register your application's ID at their web site. This is important if you plan to use databases with your MIDlets, or deploy your MIDlets specifically on Palm OS

Any application converted using the GUI-based converter tool or the command line tool is, by default, not beamable from the Palm Launcher Screen as shown in Figure 7. If you use the command line tool, however, and provide a creator ID then the application will be beamable. Alternatively, an application is beamable by launching the MIDlet first, then selecting Go|Beam App....

Figure 7: An application cannot be beamed (by default)

Advanced Java Applications

We have seen how to develop a simple Java application for the Palm that creates various GUI components. What about advanced applications that use networking and databases? The MIDP for Palm OS supports all the MIDP features, including the Generic Connection Framework and Record Management System (RMS). So, now let's look at a couple of sample applications developed in the MIDP Tutorials.

First, however, if you like to test network-based applications from the Palm OS Emulator (POSE), there are two things that need to be set:

1. Redirect Netlib calls to host TCP/IP. To do this, right click on POSE window, select Setting -> Properties, and check the Redirect NetLib calls to host TCP/IP.
2. Enable Networking. To do this, tap the Java HQ icon, then tap Preferences and select Networking Enabled, as shown in Figure 8.



Figure 8: Java HQ Networking Preferences

The Java HQ allows you to set special preferences. For example, it allows you to

• Set how much memory is used to run Java applications
• Set how many colors are used
• Change the drawing speed
• Set how your device will connect to the Internet
• Choose how the controls should be displayed on the screen

All of these options can be easily set using the Java HQ. However, if you are running an application and would like to set some preferences, select the Preferences item from the Options menu. You can choose whether you want to set Application preferences or Global (or Java HQ) preferences, as shown in Figure 9. Application preferences affect only the Java application you are running; Global preferences affect every Java application running in your device.

Figure 9: Preference Settings for Java HQ and its Applications

Fetching a Page using HttpConnection

In the MIDP Network Programming article, a MIDlet was developed to retrieve the contents of a file from a remote server using the HttpConnection interface. The MIDlet that implements this functionality is the SecondExample.java. Create a new project in the J2ME Wireless Toolkit and use the SecondExample.java as its source file. Build it, locate the JAR and JAD files and use the PRC converter tool to convert them into a PRC file. Install the PRC file on POSE then run the application. You see something similar to Figure 10.

Figure 10: Retrieving a file from a remote server

Retrieving Stock Quotes and working with databases

In the MIDP Database Programming article a MIDlet was developed that allows you to create a database, add stocks (that are retrieved from Yahoo's quotes server) to the database, and view the database. Download the files Stock.java, StockDB.java, and QuotesMIDlet.java. Build the application and create JAR and JAD file pair, then use the PRC converter tool to produce an PRC file. Alternatively, you can use the StockMIDlet.prc that comes with the FCS of MIDP for Palm 1.0 that can be located in the directory c:\midp4palm\PRCfiles. Install the PRC file on POSE then run it. Add few stocks and then view the stocks from the database. You see something similar to Figure 11.

Figure 11: Stock quotes

Conclusion

The Palm OS implementation of MIDP provides a runtime environment and tools for wireless software developers that allow them to convert their MIDlets into Palm applications without writing a single line of code. I do not know of any easier way to develop fully functional Java applications for the Palm. These applications can be used just like any other Palm application; they run like any Palm program, and can be removed from your Palm device the same way you would remove any other application.

For more information

• MIDP

About the Author: Qusay H. Mahmoud provides Java consulting and training services. He has published dozens of articles on Java, and is the author of Distributed Programming with Java (Manning Publications, 1999) and Learning Wireless Java (O'Reilly & Associates, 2002).