Package ej.event

Class EventQueue

  • public class EventQueue
extends java.lang.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 Detail

      • setUncaughtExceptionHandler

        @Nullable
public void setUncaughtExceptionHandler​(java.lang.Thread.UncaughtExceptionHandler uncaughtExceptionHandler)
        Sets a handler for the exceptions that occur during event reading or execution.
        Parameters:
        uncaughtExceptionHandler - the uncaught exception handler to set.

      • 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:
        java.lang.IllegalArgumentException - if listener is null.

      • registerListener

        public int registerListener​(EventQueueListener listener)
                     throws java.lang.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:
        java.lang.IllegalStateException - if there is no type left for a new listener.

      • unregisterListener

        public void unregisterListener​(int type)
                        throws java.lang.IllegalArgumentException
        Unregisters listener for the provided event type
        Parameters:
        type - type of listener to be unregistered
        Throws:
        java.lang.IllegalArgumentException - if the given type does not correspond to any registered listener.

      • 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:
        java.lang.IllegalStateException - if the FIFO is full.
        java.lang.IllegalArgumentException - if the given type is lower than 0 or greater than 127.
        java.lang.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:
        java.lang.IllegalStateException - if the FIFO is full.
        java.lang.IllegalArgumentException - if the given type is lower than 0 or greater than 127.
        java.lang.IllegalArgumentException - if the length of data buffer exceeds 24 bits.

      • getInstance

        public static EventQueue getInstance()
        Gets an instance of a started EventQueue.
        Returns:
        the instance of the queue.