Running Java Applications on the Palm Devices

This book uses MIDP 1.0 for developing Java applications on the Palm. To compile Java source code to deploy on the Palm devices, we need to go through a few simple steps. First, we compile the Palm source code using a Java 1.1 compiler (since MIDP and CLDC are based on Java 1.1 bytecodes). The CompilePalm Ant build target performs this step.

<target name="CompilePalm" depends="CompileDesktop">
  <!-- Compile the Palm source code -->
  <javac srcdir="${palmsource}"
    target="1.1"
    bootclasspath="${wtk-base}\lib\midpapi.zip"
    destdir="${palmunverified}"
    fork="true"
    executable="${jdk-base}\bin\javac"
    compiler="javac1.1">
    <classpath>
      <pathelement path="${palmunverified}"/>
      <pathelement path="${palmverified}"/>
      <pathelement location="${palmlib}\${palmsoaplib}"/>
    </classpath>
  </javac>
</target>

This target compiles the Java source code and puts the resulting class files into a special directory. Because with the KVM verification is a two-part process, the first part of which is done on the desktop (and is called "preverification") rather than the device, the class files just produced must be preverified. This is done by the PreverifyPalm Ant build target.

<target name="PreverifyPalm" depends="CompilePalm">
  <!-- Preverify the Palm classes -->
  <exec dir=".\" executable="${wtk-base}\bin\preverify.exe"
    failonerror="true">
    <arg line="-classpath
       ${wtk-base}\lib\midpapi.zip;${palmlib}\${palmsoaplib}
       -d ${palmverified} ${palmunverified}"/>
  </exec>
</target>

This process takes the unverified class files from ${palmunverified}, verifies them using the preverification tool from the J2ME Wireless Toolkit, and puts the output class files into ${palmverified}.

The application may make use of external class libraries that may be supplied as JAR files. In this case, the Ant build target UnjarExternalLibraries unbundles the JARs into class files and puts them into the ${palmunjar} directory. This is done so that we can produce a single JAR file for deploying to the Palm.

<target name="UnjarExternalLibraries" depends="PreverifyPalm">
  <unjar dest="${palmunjar}">
    <patternset>
        <include name="**/*.class"/>
    </patternset>
    <fileset dir="${palmlib}">
        <include name="**/*.jar"/>
    </fileset>
  </unjar>
</target>

Now we are ready to create the Palm JAR. To create the JAR file we need a special manifest file that describes the MIDlet application. The manifest file describes:

• The application's name, the icon file to use, and the class name of the application.

• Vendor and version information.

• The J2ME version required.

The manifest below is from one of the applications we will be building in a subsequent chapter.

MIDlet-1: SOAPClient, , com.javaonpdas.webservices.clients.wingfoot.SOAPClient
MIDlet-Name: SOAPClient
MIDlet-Vendor: Daryl Wilding-McBride
MIDlet-Version: 1.0
MicroEdition-Configuration: CLDC-1.0
MicroEdition-Profile: MIDP-1.0

The Ant build target SOAPClientJAR is an example target that builds a JAR.

[View full width]
<target name="SOAPClientJAR" depends="UnjarExternalLibraries">
  <jar destfile="${palmverified}\SOAPClient.jar" manifest="${palmresources}\
SOAPClient-manifest.txt">
    <fileset dir="${palmverified}"
      includes="com\javaonpdas\webservices\clients\wingfoot/*.class com\javaonpdas\*.
class"
    />
    <fileset dir="${palmunjar}"
      includes="**/*.class"
    />
    <fileset dir="${palmresources}"
      includes="**/*.png"
    />
  </jar>
  <updatejad jad="${palmresources}\SOAPClient.jad" relativePath="true" />
</target>

This target also updates the JAD file. The JAD file describes the MIDP deployment package.

MIDlet-Version: 1.0
MIDlet-Vendor: Daryl Wilding-McBride
MIDlet-Jar-URL: ../classes/SOAPClient.jar
MIDlet-Jar-Size: 42726
MIDlet-Name: SOAPClient

The JAD file can be prepared prior to the JAR file being built, but the MIDlet-Jar-Size item must be populated after the JAR is present. This requirement is addressed by a special Ant task called updatejad (see http://www.stampysoft.com/). updatejad updates the JAR file size entry in the JAD file.

Now that we have a JAR and JAD pair, we can create the PRC for downloading to the Palm device. An example of a build target that performs this task is SOAPClientPRC.

[View full width]
<target name="SOAPClientPRC" depends="SOAPClientJAR">
  <java
  classname="com.sun.midp.palm.database.MakeMIDPApp"
  dir="."
  fork="true"
  failonerror="true">
  <classpath>
      <pathelement location="${prcconverter}"/>
  </classpath>
  <arg line="-jad ${palmresources}\SOAPClient.jad -type Data -o ${palmdeploy}\SOAPClient.
prc ${palmverified}\SOAPClient.jar"/>
  </java>
</target>

This task uses the MakeMIDPApp application from MIDP for Palm, located in the Converter.jar JAR file. The other command line options for MakeMIDPApp are:

Usage: java com.sun.midp.palm.database.MakeMIDPApp [-options] <JAR file>

where options include:

-v                 Verbose output (-v -v gives even more information)
-verbose           Same as -v
-icon <file>       File containing icon for application. Must be in
                   bmp, pbm, or bin (Palm Resource) format.
-smallicon <file>  Same as -smallicon
-name <name>       Short name of application, seen in the launcher
-longname <name>   Long name for the application, seen in beaming, etc.
-creator <crid>    Creator ID for the application
-type <type>       File type for application (default is appl)
-outfile <outfile> Name of file to create on local disk; this is the
                   file that is downloaded to the Palm
-o <outfile>       Same as -outfile
-version <string>  Change version
-help              Print this message
-jad <file>        Specify a file for JAD, MIDlet Suite Packaging

Palm recommends that Palm developers use a unique Creator ID for their applications. Creator IDs are a four-character identifier and can be registered on the Palm developer Web site at http://dev.palmos.com/creatorid/.

Once registered, developers can set the Creator ID for their applications using the -creator option. If this option is not specified, a unique identifier will be created automatically.

The PRC file resulting from this step is put into the ${palmdeploy} directory, and it can be copied to the Palm using the Install tool in Palm Desktop.

If we want to run the Palm application on the emulator, there are two choices. First, we can use the Wireless Toolkit's emulator script, which is how the Ant build target SOAPClient works:

[View full width]
<target name="SOAPClient" depends="SOAPClientJAR">
  <exec dir=".\" executable="${wtk-base}\bin\emulatorw.exe">
    <arg line="-Xdevice:PalmOS_Device -Xdescriptor:${palmresources}\SOAPClient.jad 
-Xprefs:${palmresources}\emulator-prefs.txt"/>
  </exec>
</target>

This target does not use the PRC file, but rather uses the JAD we created previously. The benefit of using this method is that the emulator starts and runs the application automatically.

The other option is to start the emulator and load the PRC manually. To load the PRC, start the emulator and right-click on the screen. Select "Install Application/Database" and navigate to the directory in which the PRC is located. This will load the PRC into the Unfiled category (unless you have loaded the application previously and moved it elsewhere). Find the icon and tap on it to run the application.