The Event Model

Chapter 3 The Event Model

This chapter describes the event-handling mechanism of the MIDP Reference Implementation. The mechanism is implemented primarily in the com.sun.midp.lcdui.DefaultEventHandler class. Because it is written in the Java™ programming language, it will run without changes on a new device. event-handling mechanism also has a few native calls that deliver events to MIDP that you might have to port. This chapter explains how the event model works so that you can better understand the reference implementation, and briefly discusses the C function that you might have to port.

This chapter contains the sections:

Event Model Overview

Events From the Virtual Machine

Events From MIDP

Native Functions

3.1 Event Model Overview

MIDP is one software layer in a Java 2 Platform, Micro Edition (J2ME™) implementation; multiple layers can generate events that MIDP must handle. MIDP’s event handling mechanism enables it to receive and process events that come from two sources:

Outside MIDP – Events, such as key presses, that originate in the device and propagate through the underlying layer to MIDP

Inside MIDP – Events, such as screen changes, that originate in MIDP and have meaning only to it

MIDP processes all events, regardless of their source, with a single thread: the event thread. In addition to the event thread, MIDP also has a single queue, the event queue, that holds all pending events, regardless of their source. The event thread serially processes events from the event queue until the queue is empty.

When the event queue is empty, the event thread goes to sleep by calling the wait method. When the event queue receives an event, it calls the notify method to wake up the event thread so that the event can be processed. The
wait/notify mechanism of the Java programming language is an efficient way to process events, in terms of battery life. If MIDP used a mechanism that had threads busy-wait, the device's battery could be drained more quickly.

Having a a single event thread operating on a single queue simplifies event handling, although putting the events in the queue introduces some complexity because the events from the inside and outside MIDP are received differently. The following sections discuss how events from the two sources are received and processed.

3.2 Events From the Virtual Machine

Passing an event from the virtual machine (VM) to MIDP is not straightforward because the VM typically is written and operates in a different computer language than the MIDP layer. The VM is often in C or C++, and MIDP is largely written in the Java programming language.

MIDP solves the problem of getting events from the VM by implementing a special data stream between the VM and MIDP. The VM writes a series of integer values into the stream for each event that occurs, then MIDP reads the values from the stream to process the events. MIDP can receive the following predefined event types from the VM: key, pointer, command, and multimedia.

MIDP has two threads that work together to get an event from the stream. One thread, the VM-event thread, gets the initial integer of the series that describes an event. The event thread (the thread that handles the events on the event queue) gets the event’s remaining integers. Both threads use blocking reads. (That is, the read method returns only when there is data available on the stream; if the stream is empty, the thread cannot do other work.)

In more detail, getting and processing an event from the VM happens like this:

The VM-event thread attempts to read an integer from the stream. When there is data on the stream, the read method unblocks and returns a single integer value. The integer identifies the type of event in the stream.

The VM-event thread places the event identifier into the event queue and waits by calling the wait method. The VM-event thread waits because it does not know how many of the subsequent integers on the stream are part of this event. It cannot yet locate the next event identifier.

The event thread processes the event on the event queue:

It reads the integers that are on the stream for the event it is processing. The event thread has access to the number of integers associated with each type of event, so it is able to read only the data for the current event. This read will not block because it is guaranteed that a specific number of integers are on the stream for each event ID.

It uses the integers to process the event.

It calls the notify method to allow the VM-event thread to read the next event identifier from the stream. (The read operation in Step a took enough data from the stream that the next integer on the stream will be an event identifier.)

The VM-event thread awakens and the process repeats from Step 1.

There is a potential problem with the data stream: if a user caused events to happen at a rate that surpassed MIDP's ability to process them, the stream could overflow and incoming events would be ignored. In practice, it has not been an issue.

3.3 Events From MIDP

Getting events from MIDP onto the event queue is more straightforward: they are placed into the event queue by the MIDP system thread or MIDlet-created thread that is executing the call that generated the event. Unlike the VM-event thread, this thread does not wait for the event to be processed; it puts the event on the event queue and returns immediately. MIDP can receive the following predefined event types from MIDP application code: repaints, screen changes, serialized callbacks, content invalidations (such as a Form), and item state change notifications.

The event queue, from which the event thread serially processes elements, has special processing to keep MIDP’s events from causing an overflow. (The chances of overflow would otherwise be greater for application-generated events, since an application might have a very tight loop that generate events.) The event queue does the following special processing:

It coalesces repaint events – If a repaint for region R1 has been scheduled but not yet processed, and a thread attempts to schedule a subsequent repaint for region R2, the end result is a single repaint event with a region that is the union of R1 and R2.

It discards any prior, unprocessed screen-change event when a new screen-change event arrives – The event queue keeps only the most recent screen-change event for processing.

Both actions are explicitly permitted by the MIDP specification. In addition to keeping the event queue from overflowing, the special processing keeps the memory footprint of the event queue at or below a small maximum limit (basically the sum of one pending event of each type).

3.4 Native Functions

The virtual machine (VM) has its own event handling mechanism, from which MIDP gets events. Part of the virtual machine’s event handling is the function GetAndStoreNextKVMEvent. Systems built on the VM, such as MIDP, must implement this method. (The Porting Guide that came with CLDC for more detailed information.)

The MIDP Reference Implementation implements the GetAndStoreNextKVMEvent function in the nativeGUI.c file, which is in the platform-specific directories midpInstallDir\src\win32\native and midpInstallDir/src/solaris/native. Because the method is device-specific, you will have to port it to your device. The following paragraphs describe its actions.

Because the MIDP Reference Implementation defines a number of events, one task that GetAndStoreNextKVMEvent performs is to determine whether an event should be passed to the Java platform event handler. The MIDP Reference Implementation typically passes key presses, button presses, mouse movement, mouse clicks (on the emulator screen and the keypad), multimedia, application shutdown, and timers. Events that are not passed to the Java platform event handler are those that occur when the system menu is displayed (the system menu is a native component controlled entirely by native code). In this case, key presses go directly to the native system menu event handler, not to the Java platform event handler.

If an event will be passed to the Java platform event handler, GetAndStoreNextKVMEvent calls the StoreMIDPEvent function. The function encodes the event and makes it available to the Java platform. The StoreMIDPEvent function is in the file midpInstallDir\src\share\native\kvm\midpEvent.c.

MIDP gains access to the event using the special data stream described in Section 3.2 "Events From the Virtual Machine" . The native methods to access the special data stream are defined in midpInstallDir\src\share\native\kvm\midpEvents.c and are called by the class com.sun.midp.lcdui.Events.

Porting MIDP
MIDP Reference Implementation, Version 2.0 FCS