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).

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 the 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.
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.
int	registerListener(EventQueueListener listener) Registers a listener that will receive 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.
void	unregisterListener(int type) Unregisters listener for the provided event type

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.

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 or greater than 127.

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 or greater than 127.

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

registerListener

public int registerListener(EventQueueListener listener)
                     throws IllegalStateException

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

The same listener can be registered for several types.

Parameters:

listener - the listener to register.

Returns:

the event type that will be listened by the listener.

Throws:

IllegalStateException - if there is no type left for a new listener.

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.

Throws:

IllegalArgumentException - if listener is null.

setUncaughtExceptionHandler

@Nullable
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.

unregisterListener

public void unregisterListener(int type)
                        throws IllegalArgumentException

Unregisters listener for the provided event type

Parameters:

type - type of listener to be unregistered

Throws:

IllegalArgumentException - if the given type does not correspond to any registered listener.