Java Wireless Overview
Peter Komisar ©  Conestoga College  version  1.1 /  2009
reference: Learning Wireless Java, Qusay H. Mahmoud,
O'Reilly, User’s Guide Sun JavaTM Wireless Toolkit for
CLDC Version 2.5.2, Sun MicroSystems, 'Java 2ME and
MIDP Development', John Muchow, The Mobile Information
Device Profile and MIDlets, Part 2, Kim Topley, onjava.com

Overview

Welcome to the world of J2ME, Java's Micro Edition.
The micro edition is aimed at the portable market
which generally uses wireless to connect to networks.
As time has gone by the Micro moniker has been
giving way to the 'Wireless' name.

Typical devices that the Micro edition is aimed at
serving are also called 'embedded devices' and
include the following:


Embedded Devices
Java Community Process

The Java Community Process is Sun's equivalent
of the democratization of development akin to the
Open Source movement. While Sun, maintains it's
proprietary role, they have generally been good
stewarts of Java and the JCP process has worked
well.

Who's Involved

Over 600 companies support J2ME. Some of the
names of major companies are Nokia, Motorola, RIM
and Palm. There is no doubt that Java's port into the
world of cellular phones has been a major boost for
it's widespread acceptance.

Java's design, where it runs on a virtual machine on
top of a processor has facilitated it's acceptance as
each company can create a thin JVM for whatever
processor they use in their portable device.


Micro Architecture

The high level look at the Micro edition is that it is
like regular Java but it add two layers, 'profiles' and
'configurations'.  In fact we will see the JVMs are
different too.

J2ME Architecture

JVMs and Operating Systems

The virtual machines and OSes are the same
sorts of things we are use to with regular Java
however the CPUs are small powerful processers
like those supplied by 'ARM' and the operating
systems are typically proprietary OSes or slimmed
down versions of Windows or Linux.

Companies provide their own JVMs specifically
for their portable platforms.

Configurations

Configurations are horizontal grouping of products
which have a similar memory resources and
processing power.  Following are the sorts of things
that a configuration specifies:

Configuration Specifications
At this time two configurations are available,
the CDC and CLDC.

The CDC Configuration

CDC devices are relatively powerful. The CDC
supports devices such as set-top boxes, Internet
TVs and car navigation systems. The configuration
uses a fully functional Java Virtual Machine.
Following are the details of the resources the
CDC specifies.

CDC Resource Specification

The CDLC // think of the L as light, less or little

The CLDC is more common and describes the
smaller footprint of embedded devices such as
cell phones.  It was introduced in 1999 and is
described as a 'lowest common denominator'
Java environment.

CDLC Resource Specification
 You can see the primary difference in the two
configuration is in memory and processing
power available.

As processors continue to increase in power the
the configurations will continually be colliding with
each other.

Micro Virtual Machines

The size and power required by the different
configurations differs as well. The CLDC requires
a very small virtual machine which is called the
KVM. The CDC uses a larger interpreter called
the CVM.

// CLDC --> KVM , CDC --> CVM

The KVM

The KVM or the 'Kilo Virtual Machine' is a full
-fledged JVM however it is specifically stream
-lined for  'resource constrained' devices.

The CVM

The CVM is more powerful and is equivalent
to a Java 1.3 virtual machine. It supports the
following features:

CVM Feature Support
The reference implementation of the CVM runs
on Linux and VxWorks operating systems.

Profiles

Profiles are thought of as vertical classifications.
They describe devices that might use one configuration
or another, however they require specialized features.
Practically, this means that a profile will describe a
particular API or set of APIs that will run on top of
a given implementation.

Two profiles are described, the well known MIDP
and the less developed PDA profile.

The MIDP

The MIDP or Mobile Device Profile has been the
most popular profile to date. It is used to create
'midlets'. MIDP supports building UIs, networking
and storing data persistently.

Other Profiles

Downloading the Wireless Toolkit

The main page for the wireless toolkit is found at the
following link. A few more clicks and you will find the
toolkit download page.


Java Wireless Toolkit Home

http://java.sun.com/products/sjwtoolkit/index.html


Here is the link to the download page.


Java Wireless Toolkit Download Page

http://java.sun.com/javame/downloads/index.jsp


The API installs like a typical software program. The
User Interface is found under 'All Programs' in Windows.
It allows you to open the development console.


Getting Started

On Microsoft Windows choose Start > Programs >
Sun Java Wireless Toolkit 2.5.2 for CLDC >
Wireless Toolkit 2.5.2.1

// Check the User Guide for Linux. It's ./ktoolbar
// under toolkit/bin.


The Toolkit User Interface comes up.
Try some of the examples. Remember all the controls
are on the virtual device which you access via the mouse.


Development Cycle from the Command Line

For the sake of completeness we describe how
to use the Micro edition at the command line.
Next week we will find a much easier way of
creating MIDlets to run on our wireless devices.


Setting Paths

Following are the path setting that were made on this
computer. The second part of the statement is for the
Java Standard Toolkit and the last part is for the
commands in the Wireless Toolkit. This was set in
the 'Environmental Variables' Tab, under:

'Start/Control Panel/System/Advanced/Environmental Variables/Edit'.



Path Settings Example

C:\Sun\SDK\bin;C:\Program Files\Java\jdk1.6.0_07\bin;C:\WTK2.5.2\bin;

// can set with Set Path

Check if Paths are Set

To confirm your path is working, try the preverify
command at the command line. If your path is set
you will see the usage commands.


Preverify Command Output

C:\>preverify
Usage: preverify [options] classnames|dirnames ...

where options include:
   -classpath     <directories separated by ';'>
                  Directories in which to look for classes
   -d <directory> Directory in which output is written (default is ./output/)
   [ -cldc1.0 | -cldc ]
                  Checks for existence of language features prohibited
                  by CLDC 1.0 (native methods, floating point and finalizers)
   -target <CLDC1.1 | CLDC1.0>
                  Which preverifier to run
   -nofinalize    No finalizers allowed
   -nonative      No native methods allowed
   -nofp          No floating point operations allowed
   @<filename>    Read command line arguments from a text file
                  Command line arguments must all be on a single line
                  Directory names must be enclosed in double quotes (")


Now we need a MIDlet to compile. The following
example is from O'Reilly's 'Learning Wireless Java'.


First MIDlet Examples

Before going forward, we can point out some of the
hallmarks of the midlet. First of all there are the imports
which are used by MIDlets. Notice they are like applets
or servlets where a set of life cycle methods are
automatically invoked by actions processed by the
container. The way the MIDlet is customized for our
own use is to override these methods, essentially
changing their contents and leaving their signatures
in tact.


HelloMidlet Example

// An Example by Quasay Mahmoud

import javax.microedition.midlet.*;
import javax.microedition.lcdui.*;

public class HelloMidlet extends MIDlet{
  // the display for this MIDlet
private Display display;

// TextBox to diplay text
TextBox box=null;

public HelloMidlet(){}

public void startApp(){
 display = Display.getDisplay(this);
 box = new TextBox("Simple Example", "Hello World", 20,0);
 display.setCurrent(box);
 }

/**
 * Pause is a no-op since there are no background
 * activities or record stores that need to be
 * closed.
 */


public void pauseApp(){
  }

/**
 * Destroy must cleanup everthing not handled
 * by garbage collector. In this case there is
 * nothing to cleanup.
 */

public void destroyApp(boolean unconditional){
   }
}


Following is the form the command line takes when
compiling a MIDlet. The command is more complicated
than is used in the standard edition. The -bootclasspath
option tells the compiler to use the MIDP APIs. The  -d
option to tell the compiler where to put the compiled class
files. Here we have created a temporary directory called
'tempclasses' to store the classes. This directory is called
'tempclasses' because the classes created are not in a
final form.

// put the following command all on one line before you cut and paste it
// into the command line

Command Line Compile

C:\W>javac -bootclasspath c:\WTK2.5.2\lib\cldcapi10.jar;c:\WTK2.5.2\lib\midpapi20.jar -d  tempclasses *.java

If the command returns without error you should see the
associated class file in the temp directory.



Second Approach
On a second pass I have placed the source code in:

C:\Documents and Settings\Peter\j2mewtk\2.5.2\apps\XPMidlet\sr

after creating a project with that name in the WTK toolkit.
I went to that directory and compiled the source code there from the
command line.


Preverification

The next step is called preverification. You do not need
to preverify with a regular JVM as it is big enough to
accomodate the preverification process. This is the
security and the 'good form' screening that goes automatically
in standard Java. The KVMs are too small to do this job
so it is parcelled out to a preverification stage.


Some Preverification Tasks

We saw the preverify command earlier. A simplified
view of it's form is shown below including it's most
used options.


Preverify Command

- preverify [options] files | directories

- main options

In our example the following command does the preverification.
Notice both source and target directories are specified.


Example   // You have type this all on one line at the command line

C:\W>preverify -classpath C:\WTK2.5.2\lib\cldcapi10.jar;C:\WTK2.5.2\lib\midpapi20.jar -d classes tempclasses


Second Approach

The following preverification occured successfully from inside
the directory we had placed the source file in.

C:\Documents and Settings\Peter\j2mewtk\2.5.2\apps\XPMidlet\src>preverify -class
path C:\WTK2.5.2\lib\cldcapi10.jar;C:\WTK2.5.2\lib\midpapi20.jar XPMidlet


Packaging With JAR and JAD Files

We are not 'out of the woods' yet with the old style 'hand-
balming' of MIDlets. We still need to do some packaging.
What is meant here, is we compress the class file into a
jar file.

The manifest file function is to indicate to a device, the name
and version of a MIDlet suite and to specify the class files that
map to the individual MIDlets.


Lightweight JADs suffice for JARs for Information Lookups

A catch though is that the JAR must be downloaded and
data must be extracted to make this information available.
If the MIDlet is large this may make for  an unreasonable
download.

The MIDlet designers have provided a work around where
information is duplicated in a lightweight JAD file that can
be downloaded with little cost to view this information.

Following are the essential attributes of the manifest file.


Essential MIDLet Manifest File Attributes
Optional Attributes

The JAD file parallels the attributes found in the manifest
file and adds a few more.


JAD File Attributes

Following is an example from the J2WTK User Guide.


Example

MIDlet-1: My MIDlet, MyMIDlet.png, MyMIDlet
MIDlet-Name: MyMIDlet
MIDlet-Vendor: My Organization
MIDlet-Version: 1.0
MicroEdition-Configuration: CLDC-1.0
MicroEdition-Profile: MIDP-2.0

// the numbering is used to allow multiple MIDlets
// The png file indicates an image file is used.


We can use the above info to create our own
Manifest and JAD files.


The HelloMIDlet Manifest File

MIDlet-1: HelloMidlet
MIDlet-Name: HelloMidlet
MIDlet-Vendor: WiCo
MIDlet-Version: 1.0
MicroEdition-Configuration: CLDC-1.0
MicroEdition-Profile: MIDP-2.0


Second Approach
The following was entered into a simple text editor and
saved as "manifest" with All Files as type.

MIDlet-1: XPMidlet
MIDlet-Name: XPMidlet
MIDlet-Vendor: PK
MIDlet-Version: 1.0
MicroEdition-Configuration: CLDC-1.0
MicroEdition-Profile: MIDP-2.0


The JAR File

We now need to zip the file. The jar command takes
the following form.


The jar Command

jar cfm file manifest -C class-directory . -C resource-directory

Following is the execution for our example.

Example Jar Execution

C:\W>C:\W>jar cvfm HelloMidlet.jar manifest -C .\classes .
added manifest
adding: HelloMidlet.class(in = 890) (out= 469)(deflated 47%)
adding: X.class(in = 393) (out= 271)(deflated 31%)


Second Approach
Once the manifest was created the following jar command was run
inside the src directory.

C:\Documents and Settings\Peter\j2mewtk\2.5.2\apps\XPMidlet\src>jar cvfm XPMidle
t.jar manifest -C .\output .
added manifest
adding: XPMidlet.class(in = 883) (out= 470)(deflated 46%)


We need to check the size of the JAR file using the
dir (or ls command in Linux) and use this value in the
JAD file.


JAD file Example

MIDlet-Name: HelloMidlet
MIDlet-Vendor: WiCo
MIDlet-Version: 1.0
MIDlet-Jar-URL: HelloMidlet.jar
MIDlet-Jar-Size: 1400


Second Approach
  Her is the JAD file for XPMidlet.jar file.

MIDlet-1: XPMidlet, XPMidlet.png, XPMidlet
MIDlet-Jar-Size: 100
MIDlet-Jar-URL: XPMidlet.jar
MIDlet-Name: XPMidlet
MIDlet-Vendor: Unknown
MIDlet-Version: 1.0
MicroEdition-Configuration: CLDC-1.1
MicroEdition-Profile: MIDP-2.1




Here is where the command line gets messy. In the latest
version of the WTK you should be able to run the emulator
from the command line.

The emulator is in the bin directory of the WTK. Following
is the command output without arguments.

C:\WTK2.5.2\bin>emulator
Syntax:

emulator [arguments] <Application>

Arguments are:

-classpath, -cp    The class path for the VM
-D<property=value> Property definitions
-version           Display version information about the emulator
-help              Display list of valid arguments
-Xverbose[: allocation | gc | gcverbose | class | classverbose |
         verifier | stackmaps | bytecodes | calls |
         callsverbose | frames | stackchunks | exceptions |
         events | threading | monitors | networking | all
                   enable verbose output
-Xquery
                   Query options
-Xdebug            Use a remote debugger
-Xrunjdwp:[transport=<transport>,address=<address>,server=<y/n>
           suspend=<y/n>]
                   Debugging options
-Xdevice:<device name>
                   Name of the device to be emulated
-Xdescriptor:<JAD file name>
                   The JAD file to be executed
-Xjam[:install=<JAD file url> | force | list | storageNames |
           run=[<storage name> | <storage number>] |
           remove=[<storage name> | <storage number> | all] |
           transient=<JAD file url>]
                   Java Application Manager and support
                   for Over The Air provisioning (OTA)
-Xautotest:<JAD file url>
                   Run in autotest mode
-Xheapsize:<size>  (e.g. 65536 or 128k or 1M)
                   specifies the VM heapsize
                   (overrides default value)
-Xprefs:<filename> Override preferences by properties in file
-Xnoagent          Supported for backwards compatibility
-Xdomain:<domain_name>
                   Set the MIDlet suite's security domain


We need something like the following to get the emulator
to do the job from the command line.

Example

C:\WTK2.5.2\bin>emulator -classpath C:\WTK2.5.2\lib\cldcapi10.jar;C:\WTK2.5.2\li
b\midpapi20.jar C:\Documents and Settings\Peter\j2mewtk\2.5.2\apps\XPMidlet\bin\
XPMidlet.jad

I have run out of time so if you will allow it,  we can cheat
this at this point and open the WTK UI and run the MIDlet.
You will notice it is listed as a viable  project and runs.

To run from the command line, the emulator needs
the correct classpaths supplied.

Next week we see we can forget all this hard work as
the WTK does it all for us!

Optional Assignment

Next week we will investigate what options we have
for developing MIDlets using IDEs. You may wish to
try to run a HelloWorld via the command line as in the
above note.