Package org.apache.pekko.persistence

Interface AtLeastOnceDelivery

All Superinterfaces:

Actor, AtLeastOnceDeliveryLike, Eventsourced, PersistenceIdentity, PersistenceRecovery, PersistenceStash, PersistentActor, RequiresMessageQueue<DequeBasedMessageQueueSemantics>, Snapshotter, Stash, StashFactory, StashSupport, UnrestrictedStash

public interface AtLeastOnceDelivery
extends PersistentActor, AtLeastOnceDeliveryLike

Scala API: Mix-in this trait with your PersistentActor to send messages with at-least-once delivery semantics to destinations. It takes care of re-sending messages when they have not been confirmed within a configurable timeout. Use the AtLeastOnceDeliveryLike#deliver method to send a message to a destination. Call the AtLeastOnceDeliveryLike.confirmDelivery(long) method when the destination has replied with a confirmation message.

At-least-once delivery implies that original message send order is not always retained and the destination may receive duplicate messages due to possible resends.

The interval between redelivery attempts can be defined by AtLeastOnceDeliveryLike.redeliverInterval(). After a number of delivery attempts a AtLeastOnceDelivery.UnconfirmedWarning message will be sent to self. The re-sending will still continue, but you can choose to call AtLeastOnceDeliveryLike.confirmDelivery(long) to cancel the re-sending.

The AtLeastOnceDelivery trait has a state consisting of unconfirmed messages and a sequence number. It does not store this state itself. You must persist events corresponding to the deliver and confirmDelivery invocations from your PersistentActor so that the state can be restored by calling the same methods during the recovery phase of the PersistentActor. Sometimes these events can be derived from other business level events, and sometimes you must create separate events. During recovery calls to deliver will not send out the message, but it will be sent later if no matching confirmDelivery was performed.

Support for snapshots is provided by AtLeastOnceDeliveryLike.getDeliverySnapshot() and AtLeastOnceDeliveryLike.setDeliverySnapshot(org.apache.pekko.persistence.AtLeastOnceDelivery.AtLeastOnceDeliverySnapshot). The AtLeastOnceDeliverySnapshot contains the full delivery state, including unconfirmed messages. If you need a custom snapshot for other parts of the actor state you must also include the AtLeastOnceDeliverySnapshot. It is serialized using protobuf with the ordinary Akka serialization mechanism. It is easiest to include the bytes of the AtLeastOnceDeliverySnapshot as a blob in your custom snapshot.

See Also:

AtLeastOnceDeliveryLike

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	AtLeastOnceDelivery.AtLeastOnceDeliverySnapshot	Snapshot of current AtLeastOnceDelivery state.
static class	AtLeastOnceDelivery.AtLeastOnceDeliverySnapshot$
static class	AtLeastOnceDelivery.Internal$	INTERNAL API
static class	AtLeastOnceDelivery.MaxUnconfirmedMessagesExceededException
static class	AtLeastOnceDelivery.UnconfirmedDelivery	Information about a message that has not been confirmed.
static class	AtLeastOnceDelivery.UnconfirmedDelivery$
static class	AtLeastOnceDelivery.UnconfirmedWarning
static class	AtLeastOnceDelivery.UnconfirmedWarning$

Nested classes/interfaces inherited from interface org.apache.pekko.actor.Actor

Actor.emptyBehavior$, Actor.ignoringBehavior$

Nested classes/interfaces inherited from interface org.apache.pekko.persistence.Eventsourced

Eventsourced.AsyncHandlerInvocation, Eventsourced.AsyncHandlerInvocation$, Eventsourced.PendingHandlerInvocation, Eventsourced.RecoveryTick, Eventsourced.RecoveryTick$, Eventsourced.StashingHandlerInvocation, Eventsourced.StashingHandlerInvocation$, Eventsourced.State

Method Summary

Modifier and Type	Method	Description
void	deliver(ActorPath destination, scala.Function1<java.lang.Object,java.lang.Object> deliveryIdToMessage)	Scala API: Send the message created by the deliveryIdToMessage function to the destination actor.
void	deliver(ActorSelection destination, scala.Function1<java.lang.Object,java.lang.Object> deliveryIdToMessage)	Scala API: Send the message created by the deliveryIdToMessage function to the destination actor.

Methods inherited from interface org.apache.pekko.actor.Actor

context, org$apache$pekko$actor$Actor$_setter_$context_$eq, org$apache$pekko$actor$Actor$_setter_$self_$eq, postRestart, preStart, self, sender, supervisorStrategy

Methods inherited from interface org.apache.pekko.persistence.AtLeastOnceDeliveryLike

aroundPostStop, aroundPreRestart, aroundReceive, cancelRedeliveryTask, confirmDelivery, deliverySequenceNr_$eq, getDeliverySnapshot, internalDeliver, internalDeliver, maxUnconfirmedMessages, nextDeliverySequenceNr, numberOfUnconfirmed, onReplaySuccess, redeliverInterval, redeliverOverdue, redeliverTask_$eq, redeliveryBurstLimit, send, setDeliverySnapshot, startRedeliverTask, super$aroundPostStop, super$aroundPreRestart, super$aroundReceive, super$onReplaySuccess, unconfirmed_$eq, warnAfterNumberOfUnconfirmedAttempts

Methods inherited from interface org.apache.pekko.persistence.Eventsourced

_lastSequenceNr_$eq, aroundPostRestart, aroundPreStart, batchAtomicWrite, changeState, currentState_$eq, deleteMessages, eventBatch_$eq, flushBatch, flushJournalBatch, internalDefer, internalDeferAsync, internalDeleteMessagesBeforeSnapshot, internalPersist, internalPersistAll, internalPersistAllAsync, internalPersistAsync, journal, journalBatch_$eq, lastSequenceNr, log, nextSequenceNr, onPersistFailure, onPersistRejected, onRecoveryFailure, peekApplyHandler, pendingStashingPersistInvocations_$eq, receiveCommand, receiveRecover, recovering, recoveryFinished, recoveryRunning, recoveryStarted, requestRecoveryPermit, sendBatchedEventsToJournal, sequenceNr_$eq, setLastSequenceNr, snapshotSequenceNr, snapshotStore, snapshotterId, startRecovery, stash, stashInternally, super$aroundPostRestart, super$aroundPreStart, super$stash, super$unhandled, unhandled, unstashAll, unstashInternally, updateLastSequenceNr, waitingRecoveryPermit, writeEventFailed, writeEventRejected, writeEventSucceeded, writeInProgress_$eq

Methods inherited from interface org.apache.pekko.persistence.PersistenceIdentity

journalPluginId, persistenceId, snapshotPluginId

Methods inherited from interface org.apache.pekko.persistence.PersistenceRecovery

recovery

Methods inherited from interface org.apache.pekko.persistence.PersistenceStash

internalStashOverflowStrategy

Methods inherited from interface org.apache.pekko.persistence.PersistentActor

defer, deferAsync, persist, persistAll, persistAllAsync, persistAsync, receive

Methods inherited from interface org.apache.pekko.persistence.Snapshotter

deleteSnapshot, deleteSnapshots, loadSnapshot, saveSnapshot

Methods inherited from interface org.apache.pekko.actor.StashFactory

createStash

Methods inherited from interface org.apache.pekko.actor.StashSupport

actorCell, clearStash, context, enqueueFirst, mailbox, org$apache$pekko$actor$StashSupport$_setter_$mailbox_$eq, prepend, self, theStash_$eq, unstash, unstashAll

Methods inherited from interface org.apache.pekko.actor.UnrestrictedStash

postStop, preRestart, super$postStop, super$preRestart

Method Detail

deliver

void deliver(ActorPath destination,
             scala.Function1<java.lang.Object,java.lang.Object> deliveryIdToMessage)

Scala API: Send the message created by the deliveryIdToMessage function to the destination actor. It will retry sending the message until the delivery is confirmed with AtLeastOnceDeliveryLike.confirmDelivery(long). Correlation between deliver and confirmDelivery is performed with the deliveryId that is provided as parameter to the deliveryIdToMessage function. The deliveryId is typically passed in the message to the destination, which replies with a message containing the same deliveryId.

The deliveryId is a strictly monotonically increasing sequence number without gaps. The same sequence is used for all destinations of the actor, i.e. when sending to multiple destinations the destinations will see gaps in the sequence if no translation is performed.

During recovery this method will not send out the message, but it will be sent later if no matching confirmDelivery was performed.

This method will throw AtLeastOnceDelivery.MaxUnconfirmedMessagesExceededException if AtLeastOnceDeliveryLike.numberOfUnconfirmed() is greater than or equal to AtLeastOnceDeliveryLike.maxUnconfirmedMessages().

deliver

void deliver(ActorSelection destination,
             scala.Function1<java.lang.Object,java.lang.Object> deliveryIdToMessage)

Scala API: Send the message created by the deliveryIdToMessage function to the destination actor. It will retry sending the message until the delivery is confirmed with AtLeastOnceDeliveryLike.confirmDelivery(long). Correlation between deliver and confirmDelivery is performed with the deliveryId that is provided as parameter to the deliveryIdToMessage function. The deliveryId is typically passed in the message to the destination, which replies with a message containing the same deliveryId.

The deliveryId is a strictly monotonically increasing sequence number without gaps. The same sequence is used for all destinations of the actor, i.e. when sending to multiple destinations the destinations will see gaps in the sequence if no translation is performed.

During recovery this method will not send out the message, but it will be sent later if no matching confirmDelivery was performed.

This method will throw AtLeastOnceDelivery.MaxUnconfirmedMessagesExceededException if AtLeastOnceDeliveryLike.numberOfUnconfirmed() is greater than or equal to AtLeastOnceDeliveryLike.maxUnconfirmedMessages().