Appendix A

Legacy Tools

This appendix contains information about building and running applications with the Oracle Java ME Embedded Client. The techniques described here have been superseded by the information in Chapter 3, Developing Applications.

A.1 Tools

This section describes basic methods for building applications for Oracle Java ME Embedded Client. Chapter 3, Developing Applications describes simpler methods based on NetBeans and an emulator. Even so, reading this section helps you understand what is happening behind the scenes.

The fundamental tools you need are in the Java 2 Platform, Standard Edition Software Development Kit (J2SE SDK) version 1.4.2. At this stage JDK 1.4.2 is end-of-life’d and version 1.4.2_19 is archived here:

http://java.sun.com/products/archive/j2se/1.4.2_19/index.html

You also need some kind of scripting tool to automate your builds. You can use shell scripts or make, but this chapter describes the process using Ant. Ant reads XML build scripts and is useful for automating Java platform development tasks. Ant is available here:

http://ant.apache.org/

After you install the J2SE SDK 1.4.2 and Ant, you can test your installation like this:

$ java -version
java version "1.4.2_19"
Java(TM) 2 Runtime Environment, Standard Edition
    (build 1.4.2_19-b04)
Java HotSpot(TM) Client VM (build 1.4.2_19-b04, mixed mode)
$ ant -version
Apache Ant version 1.7.1 compiled on October 1 2008

Building an application for Oracle Java ME Embedded Client is a simple matter of using javac to compile source files. Because Oracle Java ME Embedded Client is based on a different software stack than the J2SE platform, use the -bootclasspath option to tell the compiler where to find the classes for Oracle Java ME Embedded Client.

When the classes are compiled, use jar to create an archive of them. Transfer this archive to your Oracle Java ME Embedded Client device. Then run your application with the Oracle Java ME Embedded Client virtual machine (cvm).

The next section shows how to create and run a simple application. The subsequent section describes how to automate the development cycle using Ant.

A.2 Compiling the Hard Way

Start with the Main.java source files described in 3.5 A First Xlet. Create a directory named src and save Main.java there.

This section describes how to compile, package, and run your application directly from the command line. You should read it just so you understand how it all works. The next section includes an Ant build script that makes everything much cleaner.

To keep things neat as you’re building, place the compiled bytecode (.class files) in a HelloXlet/build/classes directory.

At the command line, you can compile the source files like this (long lines are split for clarity):

$ export OJEC=/usr/local/Oracle_JavaME_Embedded_Client/1.0/emulator-platform
$ mkdir build
$ mkdir build/classes
$ javac -sourcepath src -bootclasspath $OJEC/lib/btclasses.zip 
  -classpath $OJEC/lib/basis.jar src/*.java -d build/classes

It’s tidier as part of an Ant script, as shown in the next section.

The next step in building your application is bundling the class files. In a more complex application, resource files like images and sounds are also bundled with your class files.

At the command line, use the jar tool to create your application package, HelloXlet/dist/HelloXlet.jar:

$ mkdir dist
$ jar cvf dist/HelloXlet.jar -C build/classes/ . 
added manifest
adding: helloxlet/(in = 0) (out= 0)(stored 0%)
adding: helloxlet/Main.class(in = 2498) (out= 1355)(deflated 45%)

Finally, to run this application, invoke cvm. You have to supply a security policy, which details which operations the application is allowed to perform. Save the following wide-open security policy as HelloXlet/unsafe.policy:

grant {
  permission java.security.AllPermission;
};

Now you are ready to run your application as follows (with newlines for readability):

$ $OJEC/bin/cvm 
  -Djava.security.policy=unsafe.policy com.sun.xlet.XletRunner 
  -name helloxlet.Main
  -path dist/HelloXlet.jar
@@XletRunner starting Xlet helloxlet.Main

You’ll see a window the with words “Hello Java World”.

A.3 Automating With Ant

You can automate these complicated command lines using any kind of scripting tool. This section describes a build script that automates the process using Ant.

The Ant script contains the three main targets that are described on the command line in the previous section. The compile target takes care of compiling the source code. Packaging occurs in jar. Finally, the run target launches your application using cvm.

A fourth target, clean, removes compiled classes and the packaged application.

To use the following script, just edit the value of the ojec property near the top so it points to your installation of Oracle Java ME Embedded Client.

<?xml version="1.0" encoding="UTF-8"?>
<project name="helloxlet.Main" default="run" basedir=".">
  <!-- Modify this property to point to your installation. -->
  <property name="ojec"
     value="/usr/local/Oracle_JavaME_Embedded_Client/1.0/emulator-platform/"/>
   <property name="jarname" value="HelloXlet"/>
   <target name="run" depends="jar">
      <exec executable="${ojec}/bin/cvm">
          <arg line="-Djava.security.policy=unsafe.policy"/>
          <arg line="com.sun.xlet.XletRunner"/>
          <arg line="-name ${ant.project.name}"/>
          <arg line="-path dist/${jarname}.jar"/>
      </exec>
   </target>
   <target name="jar" depends="compile">
      <mkdir dir="dist"/>
      <jar basedir="build/classes"
      jarfile="dist/${jarname}.jar"/>
   </target>
   <target name="compile">
      <mkdir dir="build/classes"/>
      <javac destdir="build/classes" srcdir="src"
      bootclasspath="${ojec}/btclasses.zip"
      classpath="${ojec}/lib/basis.jar"/>
   </target>
   <target name="clean">
      <delete dir="build"/>
      <delete dir="dist"/>      
   </target>
</project>

To compile, package, and run in one easy step, just type ant run at the command line.