com.tibco.ftl

## Interface EventQueue

-     public interface EventQueue

  Event queue objects hold message and timer events until listeners can process them.

  An event queue object is a FIFO queue for message and timer events. Programs can add subscribers to a queue; remove subscribers from a queue; create and destroy timers on a queue; dispatch events from a queue; and stop a queue in preparation to destroy it.

  To create an event queue object, call `Realm.createEventQueue`.

  Customers do not implement this interface.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DISCARD_NEW` Discard new events, instead of adding them to the queue.
    `static int` | `DISCARD_NONE` Do not discard events (default behavior).
    `static int` | `DISCARD_OLD` Discard old events from the head of the queue.
    `static java.lang.String` | `PROPERTY_BOOL_INLINE_MODE` Inline mode (low-latency); boolean.
    `static java.lang.String` | `PROPERTY_INT_DISCARD_POLICY` Discard policy; integer.
    `static java.lang.String` | `PROPERTY_INT_DISCARD_POLICY_DISCARD_AMOUNT` Discard amount; integer.
    `static java.lang.String` | `PROPERTY_INT_DISCARD_POLICY_MAX_EVENTS` Max events; integer.
    `static java.lang.String` | `PROPERTY_STRING_NAME` Queue name; string.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addSubscriber(Subscriber sub, SubscriberListener listen)` Add a subscriber to a queue.
    `long` | `count()` Get the number of events in the queue.
    `EventTimer` | `createTimer(double interval, EventTimerListener listen)` Create and start a timer.
    `void` | `destroy()` Destroy an event queue.
    `void` | `destroyTimer(EventTimer timer)` Stop and destroy a timer.
    `void` | `dispatch()` Dispatch message events; wait indefinitely for an event.
    `void` | `dispatch(double seconds)` Dispatch message events; wait until timeout (in seconds) for an event.
    `void` | `dispatch(long timeout, java.util.concurrent.TimeUnit units)` Dispatch message events; wait until timeout for an event.
    `void` | `dispatchNow()` Dispatch message events; do not wait.
    `java.lang.String` | `name()` Return the name of the event queue object.
    `void` | `removeSubscriber(Subscriber sub)` Remove a subscriber from a queue.

- - ### Field Detail

    - #### PROPERTY_BOOL_INLINE_MODE

          static final java.lang.String PROPERTY_BOOL_INLINE_MODE

      Inline mode (low-latency); boolean.

      Programs that receive time-sensitive messages can use inline mode to favor low latency over high throughput. Inline mode reduces inbound message latency using inline transport I/O in the same thread as the `SubscriberListener` callback method.

      Inline mode requires that callback methods always return quickly; otherwise, long callbacks can delay message I/O (defeating the purpose of inline mode).

      Inline mode could reduce the average number of messages in the vectors that the callback receives.

      It is good practice to dispatch an inline queue from only one thread. Dispatching an inline-mode queue from several threads could result in actual wait times that are longer than the dispatch timeout arguments. For example, if thread A dispatches with timeout 10 seconds, and thread B dispatches with timeout 15 seconds, then the timer for thread B does not start until after the dispatch call returns in thread A. The apparent timeout for thread B could be as long as 25 seconds.

      When specifying inline mode, programmers must coordinate with administrators to avoid illegal state exceptions.

      To enable inline mode, pass this property to `Realm.createEventQueue` with value `true`. Otherwise, the default behavior disables inline mode.

      See Also:
        Constant Field Values

    - #### PROPERTY_INT_DISCARD_POLICY

          static final java.lang.String PROPERTY_INT_DISCARD_POLICY

      Discard policy; integer.

      This property determines the behavior of the queue on overflow (too many events).

      To enable discard on overflow, pass this property to `Realm.createEventQueue`. Otherwise, the default behavior disables discard.

      These members are the legal property values:

      - `DISCARD_NONE`
      - `DISCARD_OLD`
      - `DISCARD_NEW`
      See Also:
        `PROPERTY_INT_DISCARD_POLICY_MAX_EVENTS`, `PROPERTY_INT_DISCARD_POLICY_DISCARD_AMOUNT`, Constant Field Values

    - #### PROPERTY_INT_DISCARD_POLICY_MAX_EVENTS

          static final java.lang.String PROPERTY_INT_DISCARD_POLICY_MAX_EVENTS

      Max events; integer.

      When distributing an event to the queue would overflow this limit, the queue discards events.

      If you specify a discard policy that could actually discard events, then you must also specify a value for this maximum.

      See Also:
        `PROPERTY_INT_DISCARD_POLICY`, `PROPERTY_INT_DISCARD_POLICY_DISCARD_AMOUNT`, Constant Field Values

    - #### PROPERTY_INT_DISCARD_POLICY_DISCARD_AMOUNT

          static final java.lang.String PROPERTY_INT_DISCARD_POLICY_DISCARD_AMOUNT

      Discard amount; integer.

      When a queue overflows, this property determines the number of events to discard.

      If you specify `DISCARD_OLD`, you may also specify this value. The value must be less than `PROPERTY_INT_DISCARD_POLICY_MAX_EVENTS`. When absent, the default value is 1.

      If you specify `DISCARD_NEW`, then `Realm.createEventQueue` ignores this value. Discarding new events always discards exactly enough events so that the rest fit on the queue.

      See Also:
        `PROPERTY_INT_DISCARD_POLICY`, `PROPERTY_INT_DISCARD_POLICY_MAX_EVENTS`, Constant Field Values

    - #### PROPERTY_STRING_NAME

          static final java.lang.String PROPERTY_STRING_NAME

      Queue name; string.

      It is good practice to assign a unique name to each event queue (that is, unique within the program). If the queue discards events, the advisory message identifies the queue using this name, which can help diagnose the issue.

      See Also:
        Constant Field Values

    - #### DISCARD_NONE

          static final int DISCARD_NONE

      Do not discard events (default behavior).
      See Also:
        `PROPERTY_INT_DISCARD_POLICY`, Constant Field Values

    - #### DISCARD_OLD

          static final int DISCARD_OLD

      Discard old events from the head of the queue.
      See Also:
        `PROPERTY_INT_DISCARD_POLICY`, Constant Field Values

    - #### DISCARD_NEW

          static final int DISCARD_NEW

      Discard new events, instead of adding them to the queue.
      See Also:
        `PROPERTY_INT_DISCARD_POLICY`, Constant Field Values

  - ### Method Detail

    - #### addSubscriber

          void addSubscriber(Subscriber sub,
                             SubscriberListener listen)
                      throws FTLException

      Add a subscriber to a queue.

      Adding a subscriber to a queue associates the two objects, which yields the following behavior: Each time the subscriber receives a message, it distributes an event to the queue. The event includes the inbound message and `SubscriberListener` instance.

      You can add a subscriber to at most one queue. If you have already added a subscriber to a queue, and you attempt to add it to another queue, this call throws an exception.

      If you add several subscribers to the same queue, the queue merges their message streams.

      Parameters:
        `sub` - The call adds this subscriber to the queue.
        `listen` - Dispatching a message event invokes the callback method of this listener.
      Throws:
        `FTLException`

    - #### removeSubscriber

          void removeSubscriber(Subscriber sub)
                         throws FTLException

      Remove a subscriber from a queue.

      Removing a subscriber from a queue dissociates the two objects. The subscriber no longer distributes message events to the queue. Message events that the subscriber has already distributed to the queue remain in the queue.

      Best practice is to remove all subscribers before destroying the event queue.

      Associations between subscribers and queues are independent of one another; that is, removing one subscriber from a queue does not affect the association of other subscribers with that queue.

      Parameters:
        `sub` - The call removes this subscriber from the queue.
      Throws:
        `FTLException`

    - #### createTimer

          EventTimer createTimer(double interval,
                                 EventTimerListener listen)
                          throws FTLException

      Create and start a timer.

      This call creates a timer object associated with the queue. The timer places a timer event on the queue at every interval (in seconds).

      The interval repeats indefinitely; to stop it, the program must explicitly destroy the timer object.

      Each time `dispatch()` dispatches a timer event, the `EventTimerListener` callback processes the event.

      Parameters:
        `interval` - The timer places events on the queue at this repeating interval (in seconds).
        `listen` - Dispatching a timer event invokes the callback method of this listener.
      Returns:
        a new EventTimer object
      Throws:
        `FTLException`

    - #### destroyTimer

          void destroyTimer(EventTimer timer)
                     throws FTLException

      Stop and destroy a timer.

      This call stops a timer so it does not place additional timer events on the queue. It also attempts to remove from the queue any timer events (associated with the stopped timer) that have fired but are not yet processed.

      Parameters:
        `timer` - The call stops this timer.
      Throws:
        `FTLException`

    - #### dispatch

          void dispatch()
                 throws FTLException

      Dispatch message events; wait indefinitely for an event.

      If the queue is not empty, this call scans events from the head of the queue to obtain a sequence of events that all contain the same listener. Scanning produces a list of messages, which the dispatch call passes to the listener for processing.

      If the queue is empty, the call waits indefinitely for events to arrive.

      Throws:
        `FTLException`

    - #### dispatch

          void dispatch(long timeout,
                        java.util.concurrent.TimeUnit units)
                 throws FTLException

      Dispatch message events; wait until timeout for an event.

      If the queue is not empty, this call scans events from the head of the queue to obtain a sequence of events that all contain the same listener. Scanning produces a list of messages, which the dispatch call passes to the listener for processing.

      If the queue is empty, the call waits for events to arrive. The timeout parameter determines the maximum time it can wait. Note that this parameter does not guarantee a minimum wait time.

      If the timeout elapses before an event arrives in the queue, then the dispatch call returns normally. The call does not indicate whether or not it actually dispatched an event.

      The call converts the timeout argument from the specified units to nanoseconds, then back to seconds, then passes the result to its underlying implementation framework.

      Parameters:
        `timeout` - If the queue is empty, the call waits for an event. If an event does not arrive before this timeout elapses, the call returns.
        `units` - The program specifies the timeout in these units.
      Throws:
        `FTLException`

    - #### dispatch

          void dispatch(double seconds)
                 throws FTLException

      Dispatch message events; wait until timeout (in seconds) for an event.

      If the queue is not empty, this call scans events from the head of the queue to obtain a sequence of events that all contain the same listener. Scanning produces a list of messages, which the dispatch call passes to the listener for processing.

      If the queue is empty, the call waits for events to arrive. The timeout parameter determines the maximum time it can wait. Note that this parameter does not guarantee a minimum wait time.

      If the timeout elapses before an event arrives in the queue, then the dispatch call returns normally. The call does not indicate whether or not it actually dispatched an event.

      Parameters:
        `seconds` - If the queue is empty, the call waits for an event. If an event does not arrive before this timeout (in seconds) elapses, the call returns.
      Throws:
        `FTLException`

    - #### dispatchNow

          void dispatchNow()
                    throws FTLException

      Dispatch message events; do not wait.

      If the queue is not empty, this call scans events from the head of the queue to obtain a sequence of events that all contain the same listener. Scanning produces a list of messages, which the dispatch call passes to the listener for processing.

      If the queue is empty, this call returns immediately.

      Throws:
        `FTLException`

    - #### destroy

          void destroy()
                throws FTLException

      Destroy an event queue.

      Destroying a queue object frees all the resources associated with the queue. (However, this call does not implicitly close subscribers associated with the queue.)

      Best practice is to remove all subscribers before destroying the event queue.

      Throws:
        `FTLException`

    - #### count

          long count()
              throws FTLException

      Get the number of events in the queue.

      The count includes both message events and timer events.

      Returns:
        The number of events in the queue.
      Throws:
        `FTLException`

    - #### name

          java.lang.String name()

      Return the name of the event queue object.
      Returns:
        The name of the event queue object.
      Since:
        6.5