ej.event

Class EventQueue

java.lang.Object

ej.event.EventQueue

public class EventQueue
extends Object

EventQueue is an asynchronous communication interface between the native world and the Java world based on events. It allows users to send events from the native world to the Java world.

A FIFO mechanism is implemented on the native side and is system specific. The user can offer events to this FIFO.

Event notifications are handled using event listeners (Observer design pattern). The application code has to register EventQueueListener to be notified when new events are coming. To do so, the user can call registerListener(EventQueueListener, int).

Then the pump automatically retrieves new events pushed in the FIFO and notifies the application via the EventQueueListener.

EventQueue runs on a dedicated Java thread to forward and process events. Application event listener's calls are done in he context of this thread. This thread is started when method getInstance() is called.

Events reading operations are done using the SNI mechanism. The thread is suspended if the events FIFO is empty. The thread resume is done by the native part when a new event is sent if the events FIFO was previously empty.

Event format

An event is composed of a type and some data. The type identifies the listener that will handle the event. The data is application specific and passed to the listener. The items stored in the FIFO buffer are integers (4 bytes). There are two kinds of events that can be sent over the Event Queue:

• Standard event: an event with data that fits on 24 bits. The event is stored in the FIFO as a single 4 bytes item.
• Extended event: an event with data that does not fit on 24 bits. The event is stored in the FIFO as multiple 4 bytes items.

 +--------------+----------+---------------------------------------------------+
 | Extended (1) | Type (7) | Data (if Extended==0), Length (if Extended==1) (24) |
 +--------------+----------+---------------------------------------------------+
 ...
 +-----------------------------------------------------------------------------+
 |                  Extended Data for extended events (32)                     | (x integers)
 +-----------------------------------------------------------------------------+
 

Format explanation:

• Extended (1 bit): event kind flag (0 for non-extended event, 1 for extended event).
• Type (7 bits): event type, which allows to find the corresponding event listener.
• Length (24 bits): length of the data in bytes (for extended events only).
• Data (24 bits): standard event data (for standard events only).
• Extended data (`Length` bytes): extended event data (for extended events only).

For more information, please have a look at our Event Queue documentation.

Method Summary

Modifier and Type	Method and Description
static EventQueue	getInstance() Gets an instance of a started EventQueue.
int	getNewType() Gets an unique Id to register a Listener.
void	offerEvent(int type, int data) Inserts an event to the FIFO.
void	offerExtendedEvent(int type, byte[] data) Inserts an extended event to the FIFO.
void	registerListener(EventQueueListener listener, int type) Registers a listener that will received the events of a type.
void	setDefaultListener(EventQueueListener listener) Sets the default listener.
void	setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler uncaughtExceptionHandler) Sets a handler for the exceptions that occur during event reading or execution.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static EventQueue getInstance()

Gets an instance of a started EventQueue.

Returns:

the instance of the queue.

getNewType

public int getNewType()

Gets an unique Id to register a Listener.

Returns:

the unique Id corresponding to the name.

Throws:

IllegalStateException - if the maximum number of types (127) has been reached.

offerEvent

public void offerEvent(int type,
                       int data)

Inserts an event to the FIFO.

The data must not exceed 24 bits. Otherwise use offerExtendedEvent(int, byte[]).

Parameters:

type - the type of the event.

data - the data of the event.

Throws:

IllegalStateException - if the FIFO is full.

IllegalArgumentException - if the given type is lower than 0.

IllegalArgumentException - if the data exceeds 24 bits.

offerExtendedEvent

public void offerExtendedEvent(int type,
                               byte[] data)

Inserts an extended event to the FIFO.

When the data exceeds 24 bits, it can be split into several integers. These integers are pushed consecutively to the FIFO. The listener will receive all these integers at once and will be able to rebuild a complex data.

Parameters:

type - the type of the events.

data - the data of the events.

Throws:

IllegalStateException - if the FIFO is full.

IllegalArgumentException - if the given type is lower than 0.

IllegalArgumentException - if the length of data buffer exceeds 24 bits.

registerListener

public void registerListener(EventQueueListener listener,
                             int type)

Registers a listener that will received the events of a type.

The same listener can be registered for several types.

Parameters:

listener - the listener to register.

type - the type handled by the listener.

Throws:

IllegalArgumentException - if the given type is lower than 0 or higher than 127.

IllegalArgumentException - if there is already a listener for the event type.

setDefaultListener

public void setDefaultListener(EventQueueListener listener)

Sets the default listener. It will receive all the events whose type is not handled by any registered listener.

Parameters:

listener - the listener to set.

setUncaughtExceptionHandler

public void setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler uncaughtExceptionHandler)

Sets a handler for the exceptions that occur during event reading or execution.

Parameters:

uncaughtExceptionHandler - the uncaught exception handler to set.