com.hazelcast.topic

## Interface ReliableMessageListener<E>

- Type Parameters:
    `E` - topic event type
  All Superinterfaces:
    EventListener, MessageListener<E>

      public interface ReliableMessageListener<E>
      extends MessageListener<E>

  A `MessageListener` to better integrate with the reliable topic.

  If a regular MessageListener is registered on a reliable topic, the message listener works fine, but it can't do much more than listen to messages.

  If a ReliableMessageListener is registered on a normal topic, only the `MessageListener` methods will be called.

  # Durable Subscription

  The ReliableMessageListener allows you to control where you want to start processing a message when the listener is registered. This makes it possible to create a durable subscription by storing the sequence of the last message and using this sequenceId as the sequenceId to start from.

  # Exception handling

  The ReliableMessageListener also gives the ability to deal with exceptions using the `isTerminal(Throwable)` method. If a plain MessageListener is used, then it won't terminate on exceptions and it will keep on running. But in some cases it is better to stop running.

  # Global order

  The ReliableMessageListener will always get all events in order (global order). It will not get duplicates and there will only be gaps if it is too slow. For more information see `isLossTolerant()`.

  # Delivery guarantees

  Because the ReliableMessageListener controls which item it wants to continue from upon restart, it is very easy to provide an at-least-once or at-most-once delivery guarantee. The storeSequence is always called before a message is processed; so it can be persisted on some non-volatile storage. When the `retrieveInitialSequence()` returns the stored sequence, then an at-least-once delivery is implemented since the same item is now being processed twice. To implement an at-most-once delivery guarantee, add 1 to the stored sequence when the `retrieveInitialSequence()` is called.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `isLossTolerant()` Checks if this ReliableMessageListener is able to deal with message loss.
    `boolean` | `isTerminal(Throwable failure)` Checks if the ReliableMessageListener should be terminated based on an exception thrown while calling `MessageListener.onMessage(com.hazelcast.core.Message)`.
    `long` | `retrieveInitialSequence()` Retrieves the initial sequence from which this ReliableMessageListener should start.
    `void` | `storeSequence(long sequence)` Informs the ReliableMessageListener that it should store the sequence.

    - ### Methods inherited from interface com.hazelcast.core.MessageListener

      `onMessage`

- - ### Method Detail

    - #### retrieveInitialSequence

          long retrieveInitialSequence()

      Retrieves the initial sequence from which this ReliableMessageListener should start.

      Return `-1` if there is no initial sequence and you want to start from the next published message.

      If you intend to create a durable subscriber so you continue from where you stopped the previous time, load the previous sequence and add 1. If you don't add one, then you will be receiving the same message twice.

      Returns:
        the initial sequence

    - #### storeSequence

          void storeSequence(long sequence)

      Informs the ReliableMessageListener that it should store the sequence. This method is called before the message is processed. Can be used to make a durable subscription.
      Parameters:
        `sequence` - the sequence

    - #### isLossTolerant

          boolean isLossTolerant()

      Checks if this ReliableMessageListener is able to deal with message loss. Even though the reliable topic promises to be reliable, it can be that a MessageListener is too slow. Eventually the message won't be available anymore.

      If the ReliableMessageListener is not loss tolerant and the topic detects that there are missing messages, it will terminate the ReliableMessageListener.

      Returns:
        `true` if the ReliableMessageListener is tolerant towards losing messages.

    - #### isTerminal

          boolean isTerminal(Throwable failure)

      Checks if the ReliableMessageListener should be terminated based on an exception thrown while calling `MessageListener.onMessage(com.hazelcast.core.Message)`.
      Parameters:
        `failure` - the exception thrown while calling `MessageListener.onMessage(com.hazelcast.core.Message)`.
      Returns:
        `true` if the ReliableMessageListener should terminate itself, `false` if it should keep on running.

Copyright © 2019. All rights reserved.