Using the J2ME Wireless Toolkit

Using the J2ME Wireless Toolkit
22
This section shows you how to use the J2ME Wireless Toolkit from Sun's Java Software division
to perform all the steps of the development cycle that you did manually. You can download the
J2ME Wireless Toolkit free of charge from the Java Software Web site at Sun Microsystems,
http://java.sun.com. Download the version appropriate for your OS platform, and follow the
installation instructions provided with the download.
Creating a Project
The Wireless Toolkit features and functions are based on projects. A project represents the
development of a suite of one or more MIDlets. Completion of the project development cycle
results in the creation of application JAR and JAD files and a manifest file that describes the JAR
file.
The KToolbar is the main utility of the Wireless Toolkit. Figure 2.1 shows the KToolbar main
window. Notice that, upon startup, it prompts you to create a new project or open an existing one
and reuse the source code that you've already seen referenced in the command-line examples.
Figure 2.1. The KToolbar is the main window from which you access all of the
Wireless Toolkit's functions.
The first step, then, is to create a new project. I'm going to create a HelloWorld project and reuse
the source code that you've already seen. Figure 2.2 shows the window that pops up when you
select New Project… from the KToolbar menu bar.
Figure 2.2. To create a new project, you must define at least one MIDlet. You must
supply the project name and the name of the main Java class for the first MIDlet.
After you enter and submit the project name and MIDlet class name, the window shown in Figure
2.3 appears. This window prompts you for required information about your project, which will be
used to create the JAR manifest and JAD files. Notice that the Required tab is always shown
initially when this window appears. The attributes you see correspond to those in Table 2.4, the
required application descriptor attributes. You can modify the default information, for example,
the MIDlet-Vendor or MIDlet-Jar-URL attributes.
23
Figure 2.3. The Wireless Toolkit creates a manifest and JAD file for you based on
the information you supply in this screen, which represents the required
application descriptor fields.
Figure 2.4 shows the panel that appears when you select the Optional tab. It allows you to enter
information about the optional MIDlet attribute fields you saw previously in Table 2.5.
Figure 2.4. This panel lets you edit the optional meta-information attributes of your
MIDlet's application descriptor file.
24
After completing this step, the KToolbar main window prints three lines of informational
messages in its diagnostics output panel. It tells you where to place your Java source files,
application resource files, and application library files. Figure 2.5 shows the updated KToolbar
window.
Figure 2.5. After you complete the entry of the required MIDlet suite information,
the KToolbar indicates where to place application specific files. Notice that
resource files go in the application's res/ directory, not the bin/ directory.
25
Version 1.0.3 of the J2MEWTK adds a User Defined tab to the main Settings panel. You can see
this User Defined tab in Figures 2.3 and 2.4. Figure 2.6 shows the User Defined panel that appears
when you click the User Defined tab.
Figure 2.6. Application developers can define attributes that are specific to one or
more MIDlets in the MIDlet suite.
The panel shown in Figure 2.6 lets you define application attributes. Notice that the panel provides
an Add button, which lets you add additional attributes. Chapter 9 contains some examples that
show you how to add custom attributes using the Wireless Toolkit and how to use the attributes in
your applications.
If you look again at Figures 2.3 and 2.4, you'll see that the Required and Optional panels don't let
you add any attributes to them. You can only edit the values of the attributes that are already
present. You can't add a required field, because these are standardized. The set of optional fields is
also standardized, even though their presence is optional.
After you've finished this initial MIDlet suite definition cycle, you can always edit the values of
any of the MIDlet attributes. Select the Settings button on the KToolbar menu bar. When you do,
the window in Figure 2.3 appears again. Make the desired changes and click OK.
Placing Source Code in the Project
26
Now it's time to place the application source file inside the project, as directed by the KToolbar
diagnostic output panel. When you create a new project, the KToolbar creates the corresponding
directories under its installation directory structure, as you saw previously when using the
command-line shell. Recall that on my system, this directory is located at
/cygdrive/c/J2mewtk/apps.
Under this directory exists the HelloWorld project directory. Your next step is to manually place
the HelloWorld.java source file under the HelloWorld/src/ directory. Of course, if you were
really building a project from scratch, you would first create the source using your favorite text
editor.
Compiling the Project
Now you're ready to compile. Click the Build button on the KToolbar button panel of the
KToolbar main window. The Wireless Toolkit compiles the Hello-World.java source and
produces the diagnostic output in the KToolbar main window, which appears in Figure 2.7. Of
course, if your compilation fails, the usually friendly compiler output would appear in this panel.
Figure 2.7. Compiling your project produces additional diagnostic output in the
KToolbar main window.
If you're not convinced of the results of your compilation, you can use your command shell to
verify the existence of the .class files in the tmpclasses/ and classes/ directories:
$ pwd
/cygdrive/c/J2mewtk/apps/HelloWorld/tmpclasses
$ ls -l
total 8
-rw-r--r-- 1 vartan None 2036 HelloWorld.class
$
$ cd ../classes/
$ pwd
/cygdrive/c/J2mewtk/apps/HelloWorld/classes
$ ls -l
total 8
-rw-r--r-- 1 vartan None 2036 HelloWorld.class
As you learned already, the tmpclasses/ directory contains the .class files produced by the
compilation itself. The classes/ directory contains the preverified files produced by the
preverify utility. The J2MEWTK runs the preverify utility automatically when you click
the KToolbar Build button.
27
Packaging the Project
After you compile, you must package the application as you did using the command-line tools.
There is no Package button on the KToolbar button panel. Instead, pull down the Project menu on
the KToolbar menu bar, and select the Package menu item as shown in Figure 2.8.
Figure 2.8. Select the Package menu option to package your application. This step
produces the application JAD and JAR files.
Figure 2.9 shows the diagnostic output produced when you've completed the packaging step.
Notice that it indicates that the Wireless Toolkit has produced a HelloWorld.jar and a
HelloWorld.jad file.
Figure 2.9. The packaging step actually compiles the application before packaging
it. The diagnostics output reflects the execution of the compilation and packaging
steps.
Once again, you can verify the existence of these files by manually listing the contents of the
project's bin/ directory:
$ pwd
/cygdrive/c/J2mewtk/apps/HelloWorld/bin
$ ls -l
total 3
-rw-r--r-- 1 vartan None 282 HelloWorld.jad
-rw-r--r-- 1 vartan None 6960 HelloWorld.jar
-rw-r--r-- 1 vartan None 297 MANIFEST.MF
$
28
Actually, packaging your application using the J2MEWTK first compiles and preverifies your
program and then packages it. So you can skip the explicit compilation step described in the
previous section and just package your application before deploying and testing it. The explicit
compilation step is important, however, if you want to compile your program without packaging it.
Deploying the Application
There is really no separate deployment step when you use the Wireless Toolkit. The toolkit goes
as far as creating the entities that you would have to deploy in a real system, namely, the
application descriptor file and the application JAR file. Chapter 10 discusses what you would do
with these files in a real-world system that offers MIDP applications for download to real devices.
Executing the Application
Executing the application means emulating the runtime environment of an actual mobile device.
One of the nice features of the Wireless Toolkit Emulator is that it can emulate several real
devices, as well as some default devices that represent some lowest-common-denominator device
features.
The KToolbar button panel contains a combo box labeled Device underneath the main menu bar.
You can select one of six devices from the combo box. The selected item specifies to the emulator
which device to emulate when running applications. Figure 2.10 shows the list of devices that you
see when you select the combo box.
Figure 2.10. The Wireless Toolkit can emulate five devices. Two of these are real
devices.
After selecting your device of choice, you're ready to run your application. To run your
application in the emulator, simply click the Run button on the KToolbar button panel. I chose the
Default Color Phone emulator. Figure 2.11 shows the window that appears simulating the real
device environment.
Figure 2.11. The AMS main screen enables you to select the MIDlet you wish to
execute. If more than one MIDlet is present in the MIDlet suite, you'll see a list of all
of them. Notice the Launch button provided by the AMS system.
29
Figure 2.11 represents the main application management software screen that you would see on a
real device. It enables you to select the MIDlet you want to execute. Typically, you would start the
AMS system from a menu on your mobile device. Figure 2.12 shows the display after you select
the HelloWorld item listed on the display. This is the screen displayed by the MIDlet.
Figure 2.12. This is the single screen displayed by the HelloWorld application.
Notice that there is no button to exit the application. You can click the red Hang Up
button to return to the AMS main screen.
30
Figure 2.12 is the same figure as Figure 3.1 in chapter 3. Chapter 3 discusses the HelloWorld
application source code and its variants in detail. In this chapter, I discuss only the application
development process.
Figure 2.13 shows the J2MEWTK emulator main window after you complete emulation of the
HelloWorld MIDlet. Notice that it produces some diagnostics information about the emulation
process.
Figure 2.13. The emulator writes diagnostics output to the console.
31
It's important to run your MIDlets using different devices in the emulator to help you identify and
understand portability issues. Each device has unique display dimensions, buttons, soft key
support, and so forth. Furthermore, there are other portability issues for which no emulator can
possibly supply a realistic device environment for all devices. For example, each device's native
software platform has different support time zone support, locale support, communications
protocol support, and so forth. You'll learn about these areas throughout this book.
Testing your applications on an emulator is an important first step.
However, it is not enough to ensure accurate operation and portability,
and it's never an acceptable substitute for testing on a real device.
Making your applications portable is the key to their success.