Package com.tangosol.net.partition

Interface VersionAwareMapListener<K,V>

All Superinterfaces:
EventListener, MapListener<K,V>
public interface VersionAwareMapListener<K,V> extends MapListener<K,V>
Direct implementations of this interface are generally considered advanced use cases, such as handling event receiver (client process) restarts. Commonly MapListener implementations simply need to suggest that they are version aware. Coherence will automatically create an implementation of this interface and track partition versions for relevant partitions and re-register to replay missed events. A more detailed description of the semantics for implementors of this interface is described below.

Implementations of this interface suggest that they are aware of event versions (partition invalid input: '&' version), such that this implementation can be asked for all partition version that were last received or is interested in receiving. Additionally, there is a convenient current version method, which is generally applicable when there is a single partition being tracked.

The primary reason to be version aware is to allow the receiver/client to track the last event it received. If the receiver ever becomes disconnected from the source of events, it allows the receiver to ask the source for all events that were missed. The source may replay:

  1. all the events from the last event received to the latest
  2. only the events that were retained, if some were purged
  3. an event representing the latest modification
  4. no events if the source does not support event history
There are several reasons why the source of events (ownership enabled members) may become disconnected from the receiver of events.
  1. Network disruption - event receiver becomes disconnected from the source / the rest of the cluster
  2. Proxy (Extend/gRPC) disruption - a proxy the client was connected to dies and therefore reconnects to a different proxy
  3. Client death - client process dies but the same logical process restarts
For cases 1 invalid input: '&' 2, having to "reconnect" to the source is automatically handled by Coherence, thus this interface allows Coherence to which version for each partition was last read and request the replay with the aforementioned considerations.

For the 3rd case it requires a call to addMapListener passing an implementation of this interface that returns the relevant versions. Clearly for the 3rd case it requires the client to persist the partition version information such that it can be recovered and replay requested from the event source.

Since:
Coherence 21.06
Author:
hr 2021.01.29

  • Field Details

    • PRIMING

      static final long PRIMING
      A constant that suggests to an event source to send the current version and all future versions.
      See Also:

    • ALL

      static final long ALL
      A constant that suggests to an event source to send all known versions (subject to the event source's retention policy) and all future versions.
      See Also:

  • Method Details

    • getVersions

      VersionedPartitions getVersions()
      Return a data structure that holds a mapping of partition -> version. The absence of a partition suggests no interest in receiving events emanating from said partition.

      The version represents the last version that was read. If this listener is being registered (either for the first or nth time) this method will be called and passed to the source to allow any missed events to be replayed. Additionally, implementations can return any of the following formally defined constants (the behavior is performed in addition to the registration of this listener with the source):

      1. HEAD - send all future versions
      2. PRIMING - send current and all future versions
      3. ALL - send all known versions

      A listener is always registered under the context of a key or a filter. A key maps to a single partition while a filter generally maps to all partitions, therefore the registrations are either targeted to a single node or multiple nodes respectively.

      When replaying events if the listener was registered under the context of a key (or many keys) the events that are replayed will only be for said key(s) and not other keys owned by the same partition. Conversely, when events are replayed for filter-based registrations events relating to all keys for the returned partitions are replayed. In both cases, only future events for the given partition versions are replayed.

      Returns:
      a data structure that holds a mapping of partition -> version representing the last received versions thus can be sent to the source to replay missing events

    • getCurrentVersion

      default long getCurrentVersion()
      A convenience method that returns a single version with the same rules as described here. Callers of this method can generally assume the partition(s) this version relates to. Often this is due to the listener being registered with a key.
      Returns:
      the last version received