MIDP - Mobile Information Device Profile - version 1.0

• CLDC specifies the Java VM for very small memory devices
• MIDP specifies the application level libraries for small memory devices such as mobile phones
• MIDP 1.0 defines 3 major application libraries
  • GUI classes for monochrome/colour screens as small as 96x54 pixels
  • Persistent store for as little as 8kb of non-volatile memory
  • Networking classes including at least HTTP access
• MIDP 1.1 adds additional classes
• Current mobile phones (2003) support MIDP 1.0 - next generation phones will support MIDP 1.1
• A particular VM may define additional classes (such as serial port classes)

Portability

Networking with MIDP - Connector class

• CLDC uses a Connector class to open communication with something else

  
        Connection conn = Connector.open("...");
        

• The open() method takes a string that defines the connection type
  • HTTP: Connector.open("http://www.monash.edu.au")
  • Socket: Connector.open("socket://www.monash.edu.au:80")
  • Comms port: Connector.open("comm:0;baudrate=9600")
  • Datagram: Connector.open("datagram:www.monash.edu.au:10")
  • File: Connector.open("file:/etc/passwd")
• The open() will throw a ConnectionNotFoundException if the connection type is not supported

Connection hierachy

Connection subclasses

• If the connection supports reading, then the connection should be a subclass of InputConnection, and the input stream can be found by

  
        InputStream in = (InputConnection) conn.getInputStream();
        DataInputStream din = (DataInputStream) conn.getDataInputStream();
        

  If the connection does not support reading, then the class cast will throw an exception - guard by a class check

  
        InputStream in = null;
        if (conn instanceof InputConnection) {
            in = (InputConnection) conn.getInputStream();
            ...
        } else {...}
        

• Similarly, OutputConnection is for writing, StreamConnection for both, DatagramConnection for UDP packets
• ContentConnection is where the stream conveys a particular type of data, such as a GIF image sent by HTTP
• The StreamConnectionNotifier can be used if the device can be a server, such as a Web server: it has to wait for connections to come in

HttpConnection

• CLDC does not require any connection types - the VM may not do networking, file I/O etc
• MIDP requires support for HttpConnection

  
        HttpConnection conn = (HttpConnection)
                              Connector.open("http://www.monash.edu.au);
        

• The HttpConnection class is similar to the java.net.URLConnection class in J2SE
• You can find the content type, read the content, etc

HttpConnection example

    void getFromHttpConnection(String url) throws IOException {
         HttpConnection conn = null;
         InputStream is = null;
         try {
             conn = (HttpConnection )Connector.open(url);
 
             // Getting the InputStream will open the connection
             // and read the HTTP headers. They are stored until
             // requested.
             is = conn.openInputStream();
 
             // Get the ContentType
             String type = conn.getType();
 
             // Get the length and process the data
             int len = (int) conn.getLength();
             if (len > 0) {
                 byte[] data = new byte[len];
                 int actual = is.read(data);
                 ...
             } else {
                 int ch;
                 while ((ch = is.read()) != -1) {
                     ...
                 }
             }
         } finally {
             if (is != null)
                 is.close();
             if (conn != null)
                 conn.close();
         }
     }

Two-way communication using HttpConnection

• A MIDP device acting as a client can make an HTTP connection to a server
• This connection can include extra information, to be processed on the server side just like a CGI script

  
        HttpConnection conn = (HttpConnection)
                              Connector.open("http://www.monash.edu.au?x=abcd");
        

• This may not be efficient, but is all that is guaranteed by MIDP

MIDlet class

• Any MIDP application must subclass MIDlet
• This is the MIDP equivalent of an applet, where starting/stopping is under the control of the environment
• When a MIDlet is started, the environment calls

  
        MIDlet.startApp()
        

  The application startup code goes in this method (draw windows, start threads, etc)

• 
        public class MyApp extends MIDlet {
            public void startApp() {
                // we get going here
            }
        
            public void pauseApp() {
                // we aren't showing any more
            }
  
            public void destroyApp(boolean unconditional) {
                // clean up
            }
        }
        

Application structure

Application shell

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

public class Shell extends MIDlet {

    protected Display display;
    protected Displayable displayable;

    public Shell() {
	display = Display.getDisplay(this);
	displayable = new Form("a form");
    }

    public void startApp() {
	display.setCurrent(displayable);
    }

    public void pauseApp() {
    }

    public void destroyApp(boolean unconditional) {
	display = null;
	displayable = null;
    }
}

Compiling and running

Assume you have unpacked the J2ME wireless toolkit into a directory such as WTK=/usr/local/personaljava/WTK2.0

• Compile by javac -bootclasspath $WTK/lib/midpapi20.zip Shell.java
• Preverify by $WTK/bin/preverify -classpath .:$WTK/lib/midpapi20.zip -d classes Shell
• Run by $WTK/bin/emulator -cp classes:$WTK/lib/midpapi20.zip Shell
• Different emulators may be chosen using the -Xdevice:device option, where device is one of DefaultColorPhone, DefaultGrayPhone, MediaControlSkin or QwertyDevice

Lists

• Lists can be created to show strings, images or both
• The list elements can be set in the constructor, or added/deleted afterwards
• A typical list is

  
  
  import javax.microedition.midlet.*;
  import javax.microedition.lcdui.*;
  
  public class List1 extends MIDlet {
  
      protected Display display;
      protected List list;
  
      public List1() {
  	display = Display.getDisplay(this);
  	list = new List("Sample list",
  			//List.IMPLICIT,
  			//List.EXCLUSIVE,
  			List.MULTIPLE,
  			new String[] {"One", "Two", "Three"},
  			null);
      }
  
      public void startApp() {
  	display.setCurrent(list);
      }
  
      public void pauseApp() {
      }
  
      public void destroyApp(boolean unconditional) {
  	display = null;
  	list = null;
      }
  }
  
  
  

List types

• IMPLICIT The selection follows the up/down arrow keys
• EXCLUSIVE The arrow keys move focus, but do not select
• MULTIPLE The arrow keys move focus, but do not select
• On the Sun emulator, elements are selected/deselected by pressing the centre arrow key

Command

• The Command class places "buttons" on the screen to interact with the application, such as an "Okay" button
• The commands are of different types: BACK, CANCEL, HELP, EXIT, ITEM, OK, SCREEN and STOP
• The ITEM command refers to a particular item on the screen, such as a part of a form
• The SCREEN command means some application-specific action based on the current screen, such as "ring the user now"
• Commands are assigned to keys based on their type - these are device dependent
• Commands have a priority, which can also affect their assignment - these are device dependent

• 
        Command comm = new Command("Ok", Command.OK, 1)
        

CommandListener

• A command listener plays the same role as listeners for AWT/Swing applications
• Commands are added to Displayable objects like List
• Command listeners are added to the same objects (e.g. List) so that the application can respond to events to that occur in commands attached to the displayable
• The command listener can be any object - simple programs will probably use the application itself
• The listener must implement the CommandListener interface, and implement the method

  
        public void commandAction(Command c, Displayable d)
        

Command listener example

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

public class Command1 extends MIDlet implements CommandListener {

    protected Display display;
    protected List list;
    protected Command okCmd;
    protected Command helpCmd;

    public Command1() {
	display = Display.getDisplay(this);
	list = new List("Sample list",
			List.IMPLICIT,
			new String[] {"One", "Two", "Three"},
			null);

	okCmd = new Command("Okay", Command.OK, 1);
	helpCmd = new Command("Help", Command.HELP, 1);
	list.addCommand(okCmd);
	list.addCommand(helpCmd);
	list.setCommandListener(this);
    }

    public void commandAction(Command c, Displayable d) {
	// d == list
	if (c == okCmd) {
	    int index = list.getSelectedIndex();
	    String item = list.getString(index);
	    Alert selectedScr = new Alert("Selected item", 
				      "Item selected was " + item, 
				      null,
				      AlertType.INFO);
	    selectedScr.setTimeout(5000); // milliseconds
	    display.setCurrent(selectedScr);

	} else {
	    Alert helpScr = new Alert("Help", 
				      "Scroll to any item and press the select key", 
				      null,
				      AlertType.INFO);
	    display.setCurrent(helpScr);
	}
	// System.out.println("Selected index is " + list.getSelectedIndex());
    } 

    public void startApp() {
	System.out.println("Starting");
	display.setCurrent(list);
    }

    public void pauseApp() {
    }

    public void destroyApp(boolean unconditional) {
	display = null;
	list = null;
    }
}

TextBox

• A TextBox gives a full-screen (!) text editor
• A text box can have a title, initial contents, size, and type of text entered
• The text constraint can restrict the text entered to
  • phone number
  • url
  • email address
  • number
  • password
  • any text

TextBox example

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

public class Text1 extends MIDlet {

    protected Display display;
    protected Displayable displayable;

    public Text1() {
	display = Display.getDisplay(this);
	displayable = new TextBox("Phone number", "+61",
				  12, TextField.PHONE);
    }

    public void startApp() {
	display.setCurrent(displayable);
    }

    public void pauseApp() {
    }

    public void destroyApp(boolean unconditional) {
	display = null;
	displayable = null;
    }
}

Form

• Form is the only "container" class in MIDP
• A Form can contain Item objects
• Elements are added using Form.append()

  
        form.append(item);
        form.append("string");
        

• Whenever an item changes state, it generates an ItemStateChanged event
• These events can be caught by an ItemStateListener which is set on the form
• The state change calls the ItemStateListener method

  
        public void itemStateChanged(Item item)
        

Form example

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

public class Form1 extends MIDlet implements ItemStateListener {

    protected Display display;
    protected Form form;

    public Form1() {
	display = Display.getDisplay(this);
	form = new Form("Info entry form");
	form.append(new TextField("Name", "", 10, TextField.ANY));
	form.append(new Gauge("Age (0-100)", true, 10, 2));
	form.append(new ChoiceGroup("Job", Choice.EXCLUSIVE,
				 new String[] {"nerd", "student"},
				 null));
	form.setItemStateListener(this);
    }

    public void itemStateChanged(Item item) {
	System.out.println("State changed on item " +
			   item.toString());
    }

    public void startApp() {
	display.setCurrent(form);
    }

    public void pauseApp() {
    }

    public void destroyApp(boolean unconditional) {
	display = null;
	form = null;
    }
}

Canvas

• Canvas is used for all drawing operations
• An application that wants to draw things will subclass Canvas
• The primary methods for drawing are

  
        public void repaint(); // call this to redraw the screen
        public void paint(Graphics g); // override this to draw your things
        

Graphics

• The Graphics object has methods to draw lines, text, etc

• 
        public class Graphics {
            void drawChar(char character, int x, int y, int anchor);
            void drawLine(int x1, int y1, int x2, int y2);
            void drawRect(int x, int y, int width, int height);
            void fillArc(int x, int y, int width, int height,
                         int startAngle, int arcAngle);
            void fillRect(int x, int y, int width, int height);
            void setColor(int red, int green, int blue);
            void setFont(Font font);
            // etc
        }
        

Canvas drawing example

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

public class Canvas1 extends MIDlet {

    protected Display display;
    protected Displayable displayable;

    public Canvas1() {
	display = Display.getDisplay(this);
	displayable = new MyCanvas();
    }

    public void startApp() {
	display.setCurrent(displayable);
    }

    public void pauseApp() {
    }

    public void destroyApp(boolean unconditional) {
	display = null;
	displayable = null;
    }
}

import javax.microedition.lcdui.*;

public class MyCanvas1 extends Canvas {

    public void paint(Graphics g) {
	g.setColor(255, 0, 0);
	g.drawRect(10, 10, 100, 100);
	g.setColor(0, 255, 0);
	g.fillRect(20, 20, 80, 80);
    }
}

Canvas Listeners

• Canvas can monitor low-level events such as key presses and visibility changes
• Canvas subclasses can override methods

  
        public class Canvas {
            void keyPressed(int keyCode);
            void keyReleased(int keyCode);
            void keyRepeated(int keyCode);
            void showNotify();
            void hideNotify();
            void pointerDragged(int x, int y);
            // etc
        }
        

Keycodes

• Keycodes are integers corresponding to keys on the keyboard/keypad
• If the key represents a Unicode character, then the keycode is the Unicode value. It can be cast to a char
• If the keycode does not represent a Unicode character (e.g. an arrow key) then it has a negative value
• There are 65,000 Unicode characters, but MIDP only defines a few: KEY_NUM0, KEY_NUM1, KEY_NUM2, KEY_NUM3, KEY_NUM4, KEY_NUM5, KEY_NUM6, KEY_NUM7, KEY_NUM8, KEY_NUM9, KEY_STAR, and KEY_POUND
• A readable version of a keycode is given by the Graphics method String getKeyName(int keycode)

Game actions

• Games have their own special keys: UP, DOWN, LEFT, RIGHT, FIRE, GAME_A, GAME_B, GAME_C, and GAME_D
• There may be special keys for these, or they may be mapped onto "ordinary" keys
• The method int getGameAction(int keycode) translates keycodes to game actions

Canvas key example

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

public class Canvas2 extends MIDlet {

    protected Display display;
    protected Displayable displayable;

    public Canvas2() {
	display = Display.getDisplay(this);
	displayable = new MyCanvas2();
    }

    public void startApp() {
	display.setCurrent(displayable);
    }

    public void pauseApp() {
    }

    public void destroyApp(boolean unconditional) {
	display = null;
	displayable = null;
    }
}

import javax.microedition.lcdui.*;

public class MyCanvas2 extends Canvas {

    public void paint(Graphics g) {

    }

    protected void keyPressed(int keycode) {
	System.out.println("Keycode: " + keycode);
	System.out.println("Key (Unicode): " + getKeyName(keycode));
	System.out.println("Game action code: " + getGameAction(keycode));
	String gameAction = null;
	switch (getGameAction(keycode)) {
	case Canvas.DOWN: gameAction = "DOWN"; break;
	case Canvas.UP: gameAction = "UP"; break;
	case Canvas.LEFT: gameAction = "LEFT"; break;
	case Canvas.RIGHT: gameAction = "RIGHT"; break;
	case Canvas.FIRE: gameAction = "FIRE"; break;
	    // should be more valid cases here
	default: gameAction = "duh"; break;
	}
	System.out.println("Action: " + gameAction);
    }
}

Persistent store

• MIDP has a simple "flat file" mechanism for storing persistent data in RAM, so that it can be kept between application runs - like persistent files
• MIDP uses a RecordStore to store records of binary data
• The content and structure of the binary data is controlled by the application, and is unknown to RecordStore
• There is a small amount of control over how information is stored and retrieved, but not much

Binary data

• Information is stored in binary format
• Often a record will be the fields of an object, stored in binary format
• J2SE has a class ObjectOutputStream (and input equivalent) to serialize a class
• MIDP doesn't, you have to write methods yourself

Binary data example

import java.io.*;

public class Person {

    public String firstName; // should be private
    public String lastName;  // ditto
    public int age;           // ditto

    public Person(String first, String last, int ag) {
	firstName = first;
	lastName = last;
	age = ag;
    }

    public Person(byte[] data) throws IOException {
	super();
	ByteArrayInputStream bis = new ByteArrayInputStream(data);
	DataInputStream dis = new DataInputStream(bis);
	firstName = DataInputStream.readUTF(dis);
	lastName = DataInputStream.readUTF(dis);
	age = dis.readInt();
    }

    public byte[] toBytes() {
	try {
	    ByteArrayOutputStream bos = new ByteArrayOutputStream();
	    DataOutputStream dos = new DataOutputStream(bos);
	    dos.writeUTF(firstName);
	    dos.writeUTF(lastName);
	    dos.writeInt(age);
	    dos.close();
	    return bos.toByteArray();
	}  catch(IOException e) {
	    // will only happen if e.g. out of memory - return empty
	    return new byte[] {};
	}
    }
}

Creating/opening RecordStore

• A record store can be opened/created by the static method

  
        RecordStore.openRecordStore(String name, boolean createIfNeeded)
        

• Where the record store actually is stored, is implementation dependent
• A record store can be deleted by

  
        RecordStore.deleteRecordStore(String recordStoreName)
        

• There is no backup, rename or restore method
• There is a hierarchy of record store exceptions, with toplevel RecordStoreException

Adding records

• 
        public int addRecord(byte[] data,
                       int offset,
                       int numBytes)
                throws RecordStoreNotOpenException,
                       RecordStoreException,
                       RecordStoreFullException
        

• The offset into the byte array is usually zero
• It would be easy to throw an exception by a wrong offset or numBytes

Record enumerator

• The best way to get information out of a record store is to use an iterator

  
         RecordEnumeration enumerateRecords(RecordFilter filter,
                                            RecordComparator comparator,
                                            boolean keepUpdated) 
        

• The RecordEnumeration has methods including

  
        boolean hasNextElement();
        byte[] nextRecord();
        

Record store example

import javax.microedition.midlet.*;
import javax.microedition.lcdui.*;
import javax.microedition.rms.*;
import java.io.*;

public class PersonBook extends MIDlet {

    protected Display display;
    protected List list;
    Person[] people;

    public PersonBook() {
	display = Display.getDisplay(this);
	list = new List("People list", List.IMPLICIT);
	// setup dummy data
	Person[] people = new Person[2];
	people[0] = new Person("Bill", "Smith", 30);
	people[1] = new Person("Fred", "Bloggs", 21);
	try {
	    saveToStore("personStore", people);
	} catch(RecordStoreException e) {
	    // ignore
	}
    }

    protected void saveToStore(String storeName, Person[] people)
	throws RecordStoreException {
	try {
	    // should backup first - but no copy/rename methods exist
	    RecordStore.deleteRecordStore(storeName);
	} catch(RecordStoreNotFoundException e) {
	    // ignore
	}

	RecordStore rs = RecordStore.openRecordStore(storeName, true);
	for (int n = 0; n < people.length; n++) {
	    byte[] data = people[n].toBytes();
	    int len = data.length;
	    rs.addRecord(data, 0, len);
	}
    }

    protected Person[] loadFromStore(String storeName)
	throws RecordStoreException {
	RecordStore rs = null;
	try {
	    rs = RecordStore.openRecordStore(storeName, false);
	} catch(RecordStoreException e) {
	    return null;
	}

	int numPeople = rs.getNumRecords();
	Person[] people = new Person[numPeople];
	int count = 0;
	RecordEnumeration enumerator = rs.enumerateRecords(null, null, false);
	while (enumerator.hasNextElement()) {
	    byte[] data = enumerator.nextRecord();
	    try {
		people[count] = new Person(data);
		count++;
	    } catch(IOException e) {
		people[count] = null;
	    }
	}
	return people;
    }

    public void startApp() {
	try {
	    people = loadFromStore("personStore");
	} catch(RecordStoreException e) {
	    // leave people as null
	}
	for (int n = 0; n < people.length; n++) {
	    if (people[n] != null)
		list.append(people[n].lastName, null);
	}
	display.setCurrent(list);
    }

    public void pauseApp() {
    }

    public void destroyApp(boolean unconditional) {
	display = null;
    }
}

What's missing?

• Where is the wireless stuff? e.g. what is the wireless node id?
  doesn't exist - MIDP means mobile, not necessarily wireless; could be e.g. infrared
• We can download HTML (etc) documents using the HTTP connection. Where is the HTML viewer? the WML viewer (for WAP phones)? the cHTML viewer (for Docomo Imode phones)? the XML parser?
  they don't exist - you have to write your own, adapt J2SE source to run using the MIDP libraries, or see if your vendor has added these classes
• Where is RMI (Remote Method Invocation), for mobile code?
  RMI is not part of the CLDC or MIDP. It has its own profile, and may not be supported by MIDP devices
• Where is JDBC?
  Missing - make do locally with RecordStore, or do your d/b updates

References

• Yu Feng and Jun Zhu Wireless Java Programming with J2ME SAMS Press (call no. 621.3845 R569 P 2001)
• Roger Riggs, Antero Taivalsaari and Mark VandenBrink Programming wireless devices with the J2ME platform Addison-Wesley (call no. 621.3845 F332 W 2001)
• Knudsen, Jonathan Wireless Java : developing with Java 2, micro edition Apress (call no. 005.133 J41 KNU 2001)