org.axonframework.eventhandling.replay
Interface IncomingMessageHandler

All Known Implementing Classes:

BackloggingIncomingMessageHandler, DiscardingIncomingMessageHandler

public interface IncomingMessageHandler

Interface of a mechanism that receives Messages dispatched to a Cluster that is in Replay mode. The implementation defines if, how and when the cluster should handle events while a replay is in progress.

When replying is finished, the handler is asked to flush any backlog it may have gathered during the replay.

Implementations must ensure thread safety. The prepareForReplay(org.axonframework.eventhandling.Cluster), releaseMessage(org.axonframework.eventhandling.Cluster, org.axonframework.domain.DomainEventMessage) and processBacklog(org.axonframework.eventhandling.Cluster) methods are invoked by the thread performing the replay. The onIncomingMessages(org.axonframework.eventhandling.Cluster, org.axonframework.domain.EventMessage[]) method is invoked in the thread that attempts to publish events to a cluster while it is in replay mode.

Since:

2.0

Author:

Allard Buijze

Method Summary

List<EventMessage>	onIncomingMessages(Cluster destination, EventMessage... messages) Invoked while the ReplayingCluster is in replay mode and an Event is being dispatched to the Cluster.
void	onReplayFailed(Cluster destination, Throwable cause) Invoked when a replay has failed.
void	prepareForReplay(Cluster destination) Invoked just before replay mode is activated.
void	processBacklog(Cluster destination) Invoked when all events from the Event Store have been processed.
List<EventMessage>	releaseMessage(Cluster destination, DomainEventMessage message) Invoked when a message has been replayed from the event store.

Method Detail

prepareForReplay

void prepareForReplay(Cluster destination)

Invoked just before replay mode is activated. Any messages passed to onIncomingMessages(org.axonframework.eventhandling.Cluster, org.axonframework.domain.EventMessage[]) prior to this method invocation should be dispatched immediately to the destination cluster to prevent message loss.

This method is invoked in the thread that executes the replay process.

Parameters:

destination - The cluster on which events are about te be replayed

onIncomingMessages

List<EventMessage> onIncomingMessages(Cluster destination,
                                      EventMessage... messages)

Invoked while the ReplayingCluster is in replay mode and an Event is being dispatched to the Cluster. If the timestamp of the given message is before the timestamp of any message reported via releaseMessage(org.axonframework.eventhandling.Cluster, org.axonframework.domain.DomainEventMessage), consider discarding the incoming message.

This method returns the list of messages that must be considered as handled. May be null to indicate all given messages have been stored for processing later.

This method is invoked in the thread that attempts to publish the given messages to the given destination.

Parameters:

destination - The cluster to receive the message

messages - The messages to dispatch to the cluster

Returns:

a list of messages that may be considered as handled

releaseMessage

List<EventMessage> releaseMessage(Cluster destination,
                                  DomainEventMessage message)

Invoked when a message has been replayed from the event store. If such a message has been received with onIncomingMessages(org.axonframework.eventhandling.Cluster, org.axonframework.domain.EventMessage[]), it should be discarded.

After this invocation, any invocation of onIncomingMessages(org.axonframework.eventhandling.Cluster, org.axonframework.domain.EventMessage[]) with a message who's timestamp (minus a safety buffer to account for clock differences) is lower that this message's timestamp can be safely discarded. It is recommended that non-Domain EventMessages in the backlog are forwarded to the cluster provided, instead of discarded. They must then also be included in the returned list.

This method returns the list of EventMessages that must be considered processed, regardless of whether they have been forwarded to the original destination or not. These EventMessages have been registered in a call to onIncomingMessages(org.axonframework.eventhandling.Cluster, org.axonframework.domain.EventMessage[]).

It is highly recommended to return the instance used in the onIncomingMessages(org.axonframework.eventhandling.Cluster, org.axonframework.domain.EventMessage[]) invocation, over the given message, even if they refer to the save Event.

This method is invoked in the thread that executes the replay process

Parameters:

destination - The original destination of the message to be released

message - The message replayed from the event store

Returns:

The list of messages that have been released

processBacklog

void processBacklog(Cluster destination)

Invoked when all events from the Event Store have been processed. Any remaining backlog, as well as any messages received through onIncomingMessages(org.axonframework.eventhandling.Cluster, org.axonframework.domain.EventMessage[]) should be dispatched to the given delegate. Transactions started by the replay process have been committed or rolled back prior to the invocation of this method.

Note that onIncomingMessages(org.axonframework.eventhandling.Cluster, org.axonframework.domain.EventMessage[]) may be invoked during or after the invocation of this method. These messages must be dispatched by this handler to prevent message loss.

This method is invoked in the thread that executes the replay process

Parameters:

destination - The destination cluster to dispatch backlogged messages to

onReplayFailed

void onReplayFailed(Cluster destination,
                    Throwable cause)

Invoked when a replay has failed. Typically, this means the state of the cluster's backing data source cannot be guaranteed, and the replay should be retried.

Parameters:

destination - The destination cluster to dispatch backlogged messages to, if appropriate in this scenario

cause - The cause of the failure