Chapter 2:

The MIDlet

The MIDlet Life Cycle

When we develop a MIDlet, we simply develop a class that extends the MIDlet class and let the JAM (Java Application Manager) instantiating it and invoking different methods on it.The different methods that the JAM invokes on the midlet change the midlet state. As a result of that, the midlet goes through different states in its life cycle. The midlet states during its life cycle are as follows:

When the JAM receives the class (a class we declared as one that extends the MIDlet class) it instantiates it and positions it in the Paused state.

When the JAM invokes the startApp() method (on the midlet) the midlet moves to the Active state.

While the midlet in its Active state the JAM can invoke the pauseApp() method on it and by doing so, moves it back to the Paused state. If the active midlet wants to return back to the Paused state it can call the notifyPaused() method. By doing so, it will be moved back to the Pause state.

While the midlet in its Active state the JAM can invoke the destroyApp() method on it and by doing so, moves it to the Destroyed state(in other words: destroy it). If the active midlet wants be Destroyed it can do it self by calling the notifyDestroyed() method. Calling the notifyDestroyed() method doesn’t invoke the destroyApp() method. The midlet must have performed the same operations (clean up, releasing of resources etc...) it would have if the MIDlet.destroyApp() had been called. Once a midlet enters the Destroyed state, it cannot reenter any other state.

The midlet in its Paused state can call the resumeRequest() method and signal (by doing so) to the JAM that it wants to become active again. In response to that the JAM will call the startApp() method on that midlet.

The startApp() method might get called more than once. Therefore, any operations that must be performed only once when the application is launched should be placed in the constructor. The startApp() method may be called by the system under different circumstances and its purpose is to prepare the midlet to handle dofferent events as well as reaquire the needed resources. Eacn time, the midlet is resumed the startApp() method is called.

The pauseApp() method job is usually releasing as many resources as possible toward the next midlet restart (when the startApp() method is invoked). Placing nulls in variables the midlet has will cause indirectly the garbage collector to free these memory spaces. When the midlet is in the Paused state it should hold as few resources as possible. A midlet in the Paused state can receive asynchronous notifications (from a timer firing, for instance).

The destroyApp() method job is performing all the necessary clean up operations to release all the resources the midlet had allocated during its execution (closing network connections, database records etc…). The destroyApp() method has one boolean parameter that indicates wheter the midlet termination is unconditional (true) or not. If the boolean parameter’s value is false then the midlet might throw MIDletStateChangeException and by doing so, indicate the device that it wants to stay alive.

The following diagram demonstrates the different states in which the midlet can be.

The following midlet demonstrates the different states in which the midlet can be. Even though the System.out.println() commands are not seen when the midlet runs on a real device, when the midlet is tested using one of the existing emulators the System.out.println() commands are seen in the command line. Parts of the following example deal with GUI and events handling. These topics will be explained later.

//filename:HelloIsrael.java

//reproduced or transmitted in any form or by any means without the

//written permission of the publisher.

import javax.microedition.midlet.*;

import javax.microedition.lcdui.*;

public class MIDletStates extends MIDlet implements CommandListener

{

private Display display;

private Command exitCommand;

private TextBox textBox;

public MIDletStates()

{

System.out.println("The MIDletStates constructor is invoked");

exitCommand = new Command("Exit", Command.EXIT, 1);

textBox = new TextBox("MIDlet's states demo", "Hello:)", 15,0);

textBox.addCommand(exitCommand);

textBox.setCommandListener(this);

}

public void startApp()

{

System.out.println("The startApp method is invoked");

display = Display.getDisplay(this);

display.setCurrent(textBox);

}

public void pauseApp()

{

System.out.println("The pauseApp method is invoked");

}

public void destroyApp(boolean cond)

{

System.out.println("The destroyApp method is invoked");

}

public void commandAction(Command command, Displayable displayable)

{

if(exitCommand==command)

{

destroyApp(true);

}

MIDlet Suites

A MIDlet suite is composed of two files.

The first is a simple text file (.jad) that describes the MIDlet suite.

The second is a JAR file that contains all the class files as well as the resource files needed for the midlet and a MANIFEST file.

The steps in getting a MIDlet suite are the following. First, the class files as well as the resource files are packaged into one JAR file. Together with these files, a MANIFEST file is packaged as well. After the JAR file was created, the MIDlet suite descriptor file (*.jad) is created. The JAM uses the jad file in its decisions.

The MIDlet manifest file consists of name and value pairs and should include the following attributes:

MIDlet-Name – The name of the entire MIDlet suite.

MIDlet-Version – This describes the version of the MIDlet suite. You choose this number. The format of this attribute is as described in the JDK Product Versioning Specification. The format is major.mino.micro (1.1.2 for instance). The value of the MIDlet-Version attribute ca be used by the system for installation and upgrade uses.

MIDlet-Vendor – This is the name of the company that developed this MIDlet suite.

MIDlet-n – The MIDlet suite can holds more than one MIDlet. Each MIDlet in the suite can have a number(starting at 1), the displayable name(this name will be used by the user), icon file (PNG file) and the class name. The MIDlet in the MIDlet suite should be numbered starting from 1 and counting up.

MicroEdition-Configuration – The J2ME configuration needed to run the MIDlet suite. CLDC-1.0 will be the MicroEdition-Configuration when using the MIDP1.0.

MicroEdition-Profile – The profile required by this MIDlet suite. When using the MIDP1.0, the value of this attribute should be MIDP1.0.

More attributes can be added in addition to the required manifest attributes:

MIDlet-Data-Size – The number of bytes of persistent data that are required by the MIDlet suite.

MIDlet-Description – Textual description of the MIDlet suite.

MIDlet-Icon – The icon to represent the entire MIDlet suite. The file is a PNG one.

MIDlet-Info-URL – The URL that has additional information about the MIDlet suite.

Manifest-Version – The manifest file version.

Given that the HelloIsrael class from chapter 1 belongs to the com.zindell.j2me package, the following can be the manifest file of that HelloIsrael MIDlet:

Manifest-Version: 1.0

MIDlet-1: HelloIsrael, HelloIsrael.png, com.zindell.j2me.HelloIsrael

MIDlet-Name: HelloIsrael

MIDlet-Version: 1.0

MIDlet-Vendor: ZINDELL

MicroEdition-Configuration: CLDC-1.0

MicroEdition-Profile: MIDP-1.0

The JAM can manage more then one MIDlet. The information within the JAR file (especially in its MANIFEST files) helps him in doing so.

The MIDlet suite descriptor file is a file that has a MIME type of text/vnd.sun.j2me.app-descriptor and a file extension of .jad. The device uses the jad file in its decision whether loading the MIDlet suite or not.

Some of the information that the application descriptor file (the jad file) contains exists in the MANIFEST file as well. The attributes the jad file must have are:

MIDlet-Name

MIDlet-Version

MIDlet-Vendor

MIDlet-Jar-URL

MIDlet-Jar-Size

The jad file can also have the other attributes the MANIFEST file can have.

Given that the HelloIsrael class from chapter 1 belongs to the com.zindell.j2me package, the following can be the jad file of that HelloIsrael MIDlet suite:

Manifest-Version: 1.0

MIDlet-1: HelloIsraelProject, HelloIsraelProject.png, com.zindell.j2me.HelloIsrael

MIDlet-Jar-Size: 1056

MIDlet-Jar-URL: HelloIsraelProject.jar

MIDlet-Name: HelloIsraelProject

MIDlet-Vendor: ZINDELL

MIDlet-Version: 1.0

If the MIDlet-Name, MIDlet-Version and the MIDlet-Vendor attributes are not identical in the MANIFEST and the jad files then the MIDlet suite won’t be installed. If the other attributes that exist in the two files (The MANIFEST & the jad files) then the attributes in the jad file will count.

MIDlet Properties

It is possible adding attributes and their values as well to the manifest file or\and the application descriptor file. Later, the midlet will be able retrieving these attributes’ values using the getAddProperty() method, that was declared in the MIDlet class. Placing these attributes in the application descriptor file (the jad file) enables a better separation between the coding and the deployment. The attribute names are case sensitive.

The following example presents the use of this mechanism. The following midlet needs to have in its jad file the property: MIDPSuiteProperties.toWhom with a value the midlet will retrieve and display. Working with the KToolbar easiest the creation of the MIDlet suite descriptor file (the jad file).

//filename:HelloIsrael.java

//reproduced or transmitted in any form or by any means without the

//written permission of the publisher.

import javax.microedition.midlet.*;

import javax.microedition.lcdui.*;

public class HelloToWhom extends MIDlet

{

private Display display;

private Form form;

public HelloToWhom()

{

String str = getAppProperty("MIDPSuiteProperties.toWhom");

form = new Form(str);

}

public void startApp()

{

display = Display.getDisplay(this);

display.setCurrent(form);

}

public void pauseApp()

{

}

public void destroyApp(boolean cond)

{

}

The MIDlet suite Environment

The MID profile specification defines the MIDlet suite environment.

Only the classes and the native code that implement the CLDC and MIDP are shared by all of the MIDlet suites on the device.

The MIDlet suite is the basic unit of J2ME(CLDC\MIDP) application. The class files (the different midlets) as well as the resource files within the MIDlet suite can’t be manipulated (installed, updated or removed) individually. They must be manipulated as a whole. The MIDP specification does not allow for individual MIDlets to be upgraded to newer version. The entire MIDlet suite must be upgraded as a unit. Thanks to that, the original intent of the MIDlet suite provider is not changed.

The MIDlet suite has a common name space for its midlets. This common name space is used for the Object Heap and the static fields (of the different classes) only. Each midlet can interact with the other midlets that reside in the same MIDlet suite.

The record stores have separated name spaces (The RMS topic will be introduced later).

The class files can’t be manipulated (can’t be read nor extracted for re-use). The other non-class files within the JAR file can be accessed using the java.lang.Class.getResourceAsStream method:

public InputStream getResourceAsStream(String name)

The getResourceAsStream method

The other non-class files within the JAR files can be accessed using the java.lang.Class.getAsResourceAsStream method:

public InputStream getResourceAsStream(String name)

This method finds a resource with a given name. This method returns null if no resource with this name is found. The rules for searching resources are as follows: If name starts with a ‘/’, the search for the resource begins at the ‘root’ of the JAR file. If it doesn’t begin with a ‘/’, the resource is searched for along a path relative to the class instance retrieving the resource.

Given the details.txt file consists of the following:

ZINDELL.COM

The following example demonstrates the use of the getResourceAsStream() method.

//filename:ResourceDemo.java

//reproduced or transmitted in any form or by any means without the

//written permission of the publisher.

import javax.microedition.midlet.*;

import javax.microedition.lcdui.*;

import java.io.*;

public class ResourceDemo extends MIDlet

{

private Display display;

private Command exitCommand, stopCommand;

private TextBox textBox;

public ResourceDemo()

{

try

{

Class theClass = Class.forName("ResourceDemo");

InputStream is = theClass.getResourceAsStream("/details.txt");

StringBuffer sb = new StringBuffer();

int temp = is.read();

while(temp!=-1)

{

sb.append((char)temp);

temp = is.read();

}

String str = sb.toString();

System.out.println("str="+str);

textBox = new TextBox("Welcome To", str, 15,0);

}

catch(Exception e)

{

}

public void startApp()

{

display = Display.getDisplay(this);

display.setCurrent(textBox);

}

public void pauseApp()

{

}

public void destroyApp(boolean cond)

{

}

The JAM

The JAM (Java Application Manager) or in its other name, the Application Management Software, in the MIDP specification consists of different software pieces on the device that provide a framework in which the MIDlet suites are manages. The typical application management operations include the following:

Retrieval

Retrieving a MIDlet suite. This can be done from PC, wireless network, infrared connection or another source according to what the device enables.

Installation

Installing the MIDlet suite on the device. This step might include some kind of verification process.

Launching

Launching the midlet on the device (instantiating the midlet class).

Version Management

Installed MIDlet suites have versions. The JAM manage its MIDlet suites and enable their upgrade to newer versions.

Removal

Removing MIDlet suites that were installed on the device. The deletion of the MIDlet suite includes the deletion of its resource files.

Table of Contents

Chapter 1 : Let’s Start

Chapter 2 : The MIDlet

Chapter 3 : GUI

Chapter 4 : Persistent Storage

Chapter 5 : Networking

Chapter 6 : The Canvas class

Chapter 7 : Performance

Chapter 8 : XML

Haim Michael & Zindell Publishing House Ltd.

No parts of the contents of this paper may be reproduced or transmitted

in any form by any means without the written permission of the publisher !

This book can be used for personal use only !!!

Brought to you by ZINDELL

http://www.zindell.com