akka.persistence

Interface Eventsourced

All Superinterfaces:

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

All Known Subinterfaces:

AtLeastOnceDelivery, AtLeastOnceDeliveryLike, PersistentActor, PersistentFSM<S,D,E>

All Known Implementing Classes:

AbstractPersistentActor, AbstractPersistentActorWithAtLeastOnceDelivery, AbstractPersistentFSM, AbstractPersistentLoggingFSM, JournalPerfSpec.BenchActor, PersistentShard, PersistentShardCoordinator, RemoveInternalClusterShardingData.RemoveOnePersistenceId, UntypedPersistentActor, UntypedPersistentActorWithAtLeastOnceDelivery

public interface Eventsourced
extends Snapshotter, PersistenceStash, PersistenceIdentity, PersistenceRecovery

INTERNAL API.

Scala API and implementation details of PersistentActor, AbstractPersistentActor and UntypedPersistentActor.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Eventsourced.AsyncHandlerInvocation does not force the actor to stash commands; Originates from either `persistAsync` or `defer` calls
static class	Eventsourced.AsyncHandlerInvocation$
static interface	Eventsourced.PendingHandlerInvocation
private static class	Eventsourced.ProcessingState
static class	Eventsourced.RecoveryTick message used to detect that recovery timed out
static class	Eventsourced.RecoveryTick$
static class	Eventsourced.StashingHandlerInvocation forces actor to stash incoming commands until all these invocations are handled
static class	Eventsourced.StashingHandlerInvocation$
static interface	Eventsourced.State

Nested classes/interfaces inherited from interface akka.actor.Actor

Actor.emptyBehavior$, Actor.ignoringBehavior$

Method Summary

Modifier and Type	Method and Description
void	aroundPostRestart(java.lang.Throwable reason) INTERNAL API.
void	aroundPostStop() INTERNAL API.
void	aroundPreRestart(java.lang.Throwable reason, scala.Option<java.lang.Object> message) INTERNAL API.
void	aroundPreStart() INTERNAL API.
void	aroundReceive(scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> receive, java.lang.Object message) INTERNAL API.
void	changeState(Eventsourced.State state)
<A> void	deferAsync(A event, scala.Function1<A,scala.runtime.BoxedUnit> handler) Defer the handler execution until all pending handlers have been executed.
void	deleteMessages(long toSequenceNr) Permanently deletes all persistent messages with sequence numbers less than or equal toSequenceNr.
void	flushBatch()
void	flushJournalBatch()
ActorRef	journal()
long	lastSequenceNr() Highest received sequence number so far or 0L if this actor hasn't replayed or stored any persistent events yet.
LoggingAdapter	log()
long	nextSequenceNr()
void	onPersistFailure(java.lang.Throwable cause, java.lang.Object event, long seqNr) Called when persist fails.
void	onPersistRejected(java.lang.Throwable cause, java.lang.Object event, long seqNr) Called when the journal rejected persist of an event.
void	onRecoveryFailure(java.lang.Throwable cause, scala.Option<java.lang.Object> event) Called whenever a message replay fails.
void	onReplaySuccess() INTERNAL API.
void	peekApplyHandler(java.lang.Object payload)
<A> void	persist(A event, scala.Function1<A,scala.runtime.BoxedUnit> handler) Asynchronously persists event.
<A> void	persist(scala.collection.immutable.Seq<A> events, scala.Function1<A,scala.runtime.BoxedUnit> handler) Deprecated. use persistAll instead. Since 2.4.
<A> void	persistAll(scala.collection.immutable.Seq<A> events, scala.Function1<A,scala.runtime.BoxedUnit> handler) Asynchronously persists events in specified order.
<A> void	persistAllAsync(scala.collection.immutable.Seq<A> events, scala.Function1<A,scala.runtime.BoxedUnit> handler) Asynchronously persists events in specified order.
<A> void	persistAsync(A event, scala.Function1<A,scala.runtime.BoxedUnit> handler) Asynchronously persists event.
<A> void	persistAsync(scala.collection.immutable.Seq<A> events, scala.Function1<A,scala.runtime.BoxedUnit> handler) Deprecated. use persistAllAsync instead. Since 2.4.
scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit>	receiveCommand() Command handler.
scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit>	receiveRecover() Recovery handler that receives persisted events during recovery.
java.lang.Object	recovering(scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> recoveryBehavior, scala.concurrent.duration.FiniteDuration timeout)
boolean	recoveryFinished() Returns true if this persistent actor has successfully finished recovery.
boolean	recoveryRunning() Returns true if this persistent actor is currently recovering.
java.lang.Object	recoveryStarted(long replayMax)
void	requestRecoveryPermit()
void	setLastSequenceNr(long value)
long	snapshotSequenceNr() Returns lastSequenceNr.
ActorRef	snapshotStore() Snapshot store plugin actor.
java.lang.String	snapshotterId() Returns persistenceId.
void	startRecovery(Recovery recovery)
void	stashInternally(java.lang.Object currMsg)
void	unhandled(java.lang.Object message) User overridable callback.
void	unstashAll() Prepends all messages in the stash to the mailbox, and then clears the stash.
void	unstashInternally(boolean all)
void	updateLastSequenceNr(PersistentRepr persistent)
java.lang.Object	waitingRecoveryPermit(Recovery recovery)

Methods inherited from interface akka.persistence.Snapshotter

deleteSnapshot, deleteSnapshots, loadSnapshot, saveSnapshot

Methods inherited from interface akka.persistence.PersistenceStash

internalStashOverflowStrategy

Methods inherited from interface akka.actor.Actor

context, postRestart, preStart, receive, self, sender, supervisorStrategy

Methods inherited from interface akka.actor.StashSupport

actorCell, clearStash, context, enqueueFirst, mailbox, prepend, self, stash, unstash, unstashAll

Methods inherited from interface akka.actor.StashFactory

createStash

Methods inherited from interface akka.persistence.PersistenceIdentity

journalPluginId, persistenceId, snapshotPluginId

Methods inherited from interface akka.persistence.PersistenceRecovery

recovery

Method Detail

journal

ActorRef journal()

snapshotStore

ActorRef snapshotStore()

Description copied from interface: Snapshotter

Snapshot store plugin actor.

Specified by:

snapshotStore in interface Snapshotter

snapshotterId

java.lang.String snapshotterId()

Returns persistenceId.

Specified by:

snapshotterId in interface Snapshotter

Returns:

(undocumented)

lastSequenceNr

long lastSequenceNr()

Highest received sequence number so far or 0L if this actor hasn't replayed or stored any persistent events yet.

Returns:

(undocumented)

snapshotSequenceNr

long snapshotSequenceNr()

Returns lastSequenceNr.

Specified by:

snapshotSequenceNr in interface Snapshotter

Returns:

(undocumented)

onReplaySuccess

void onReplaySuccess()

INTERNAL API. Called whenever a message replay succeeds. May be implemented by subclass.

onRecoveryFailure

void onRecoveryFailure(java.lang.Throwable cause,
                       scala.Option<java.lang.Object> event)

Called whenever a message replay fails. By default it logs the error.

Subclass may override to customize logging.

The actor is always stopped after this method has been invoked.

Parameters:

cause - failure cause.

event - the event that was processed in receiveRecover, if the exception was thrown there

onPersistFailure

void onPersistFailure(java.lang.Throwable cause,
                      java.lang.Object event,
                      long seqNr)

Called when persist fails. By default it logs the error. Subclass may override to customize logging and for example send negative acknowledgment to sender.

The actor is always stopped after this method has been invoked.

Note that the event may or may not have been saved, depending on the type of failure.

Parameters:

cause - failure cause.

event - the event that was to be persisted

seqNr - (undocumented)

onPersistRejected

void onPersistRejected(java.lang.Throwable cause,
                       java.lang.Object event,
                       long seqNr)

Called when the journal rejected persist of an event. The event was not stored. By default this method logs the problem as a warning, and the actor continues. The callback handler that was passed to the persist method will not be invoked.

Parameters:

cause - failure cause

event - the event that was to be persisted

seqNr - (undocumented)

stashInternally

void stashInternally(java.lang.Object currMsg)

unstashInternally

void unstashInternally(boolean all)

startRecovery

void startRecovery(Recovery recovery)

aroundReceive

void aroundReceive(scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> receive,
                   java.lang.Object message)

INTERNAL API.

Specified by:

aroundReceive in interface Actor

Parameters:

receive - current behavior.

message - current message.

aroundPreStart

void aroundPreStart()

INTERNAL API.

Specified by:

aroundPreStart in interface Actor

requestRecoveryPermit

void requestRecoveryPermit()

aroundPreRestart

void aroundPreRestart(java.lang.Throwable reason,
                      scala.Option<java.lang.Object> message)

INTERNAL API.

Specified by:

aroundPreRestart in interface Actor

Parameters:

reason - (undocumented)

message - (undocumented)

aroundPostRestart

void aroundPostRestart(java.lang.Throwable reason)

INTERNAL API.

Specified by:

aroundPostRestart in interface Actor

Parameters:

reason - (undocumented)

aroundPostStop

void aroundPostStop()

INTERNAL API.

Specified by:

aroundPostStop in interface Actor

unhandled

void unhandled(java.lang.Object message)

Description copied from interface: Actor

User overridable callback.

Is called when a message isn't handled by the current behavior of the actor by default it fails with either a DeathPactException (in case of an unhandled Terminated message) or publishes an UnhandledMessage to the actor's system's EventStream

Specified by:

unhandled in interface Actor

Parameters:

message - (undocumented)

changeState

void changeState(Eventsourced.State state)

updateLastSequenceNr

void updateLastSequenceNr(PersistentRepr persistent)

setLastSequenceNr

void setLastSequenceNr(long value)

nextSequenceNr

long nextSequenceNr()

flushJournalBatch

void flushJournalBatch()

log

LoggingAdapter log()

receiveRecover

scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> receiveRecover()

Recovery handler that receives persisted events during recovery. If a state snapshot has been captured and saved, this handler will receive a SnapshotOffer message followed by events that are younger than the offered snapshot.

This handler must not have side-effects other than changing persistent actor state i.e. it should not perform actions that may fail, such as interacting with external services, for example.

If there is a problem with recovering the state of the actor from the journal, the error will be logged and the actor will be stopped.

Returns:

(undocumented)

See Also:

Recovery

receiveCommand

scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> receiveCommand()

Command handler. Typically validates commands against current state (and/or by communication with other actors). On successful validation, one or more events are derived from a command and these events are then persisted by calling persist.

Returns:

(undocumented)

persist

<A> void persist(A event,
                 scala.Function1<A,scala.runtime.BoxedUnit> handler)

Asynchronously persists event. On successful persistence, handler is called with the persisted event. It is guaranteed that no new commands will be received by a persistent actor between a call to persist and the execution of its handler. This also holds for multiple persist calls per received command. Internally, this is achieved by stashing new commands and unstashing them when the event has been persisted and handled. The stash used for that is an internal stash which doesn't interfere with the inherited user stash.

An event handler may close over persistent actor state and modify it. The sender of a persisted event is the sender of the corresponding command. This means that one can reply to a command sender within an event handler.

Within an event handler, applications usually update persistent actor state using persisted event data, notify listeners and reply to command senders.

If persistence of an event fails, onPersistFailure(java.lang.Throwable, java.lang.Object, long) will be invoked and the actor will unconditionally be stopped. The reason that it cannot resume when persist fails is that it is unknown if the even was actually persisted or not, and therefore it is in an inconsistent state. Restarting on persistent failures will most likely fail anyway, since the journal is probably unavailable. It is better to stop the actor and after a back-off timeout start it again.

Parameters:

event - event to be persisted

handler - handler for each persisted event

persistAll

<A> void persistAll(scala.collection.immutable.Seq<A> events,
                    scala.Function1<A,scala.runtime.BoxedUnit> handler)

Asynchronously persists events in specified order. This is equivalent to calling persist[A](event: A)(handler: A => Unit) multiple times with the same handler, except that events are persisted atomically with this method.

Parameters:

events - events to be persisted

handler - handler for each persisted events

persist

<A> void persist(scala.collection.immutable.Seq<A> events,
                 scala.Function1<A,scala.runtime.BoxedUnit> handler)

Deprecated. use persistAll instead. Since 2.4.

persistAsync

<A> void persistAsync(A event,
                      scala.Function1<A,scala.runtime.BoxedUnit> handler)

Asynchronously persists event. On successful persistence, handler is called with the persisted event.

Unlike persist the persistent actor will continue to receive incoming commands between the call to persist and executing it's handler. This asynchronous, non-stashing, version of of persist should be used when you favor throughput over the "command-2 only processed after command-1 effects' have been applied" guarantee, which is provided by the plain persist method.

An event handler may close over persistent actor state and modify it. The sender of a persisted event is the sender of the corresponding command. This means that one can reply to a command sender within an event handler.

If persistence of an event fails, onPersistFailure(java.lang.Throwable, java.lang.Object, long) will be invoked and the actor will unconditionally be stopped. The reason that it cannot resume when persist fails is that it is unknown if the even was actually persisted or not, and therefore it is in an inconsistent state. Restarting on persistent failures will most likely fail anyway, since the journal is probably unavailable. It is better to stop the actor and after a back-off timeout start it again.

Parameters:

event - event to be persisted

handler - handler for each persisted event

persistAllAsync

<A> void persistAllAsync(scala.collection.immutable.Seq<A> events,
                         scala.Function1<A,scala.runtime.BoxedUnit> handler)

Asynchronously persists events in specified order. This is equivalent to calling persistAsync[A](event: A)(handler: A => Unit) multiple times with the same handler, except that events are persisted atomically with this method.

Parameters:

events - events to be persisted

handler - handler for each persisted events

persistAsync

<A> void persistAsync(scala.collection.immutable.Seq<A> events,
                      scala.Function1<A,scala.runtime.BoxedUnit> handler)

Deprecated. use persistAllAsync instead. Since 2.4.

deferAsync

<A> void deferAsync(A event,
                    scala.Function1<A,scala.runtime.BoxedUnit> handler)

Defer the handler execution until all pending handlers have been executed. Allows to define logic within the actor, which will respect the invocation-order-guarantee in respect to persistAsync calls. That is, if persistAsync was invoked before deferAsync, the corresponding handlers will be invoked in the same order as they were registered in.

This call will NOT result in event being persisted, use persist or persistAsync instead if the given event should possible to replay.

If there are no pending persist handler calls, the handler will be called immediately.

If persistence of an earlier event fails, the persistent actor will stop, and the handler will not be run.

Parameters:

event - event to be handled in the future, when preceding persist operations have been processes

handler - handler for the given event

deleteMessages

void deleteMessages(long toSequenceNr)

Permanently deletes all persistent messages with sequence numbers less than or equal toSequenceNr.

If the delete is successful a DeleteMessagesSuccess will be sent to the actor. If the delete fails a DeleteMessagesFailure will be sent to the actor.

Parameters:

toSequenceNr - upper sequence number bound of persistent messages to be deleted.

recoveryRunning

boolean recoveryRunning()

Returns true if this persistent actor is currently recovering.

Returns:

(undocumented)

recoveryFinished

boolean recoveryFinished()

Returns true if this persistent actor has successfully finished recovery.

Returns:

(undocumented)

unstashAll

void unstashAll()

Description copied from interface: StashSupport

Prepends all messages in the stash to the mailbox, and then clears the stash.

Messages from the stash are enqueued to the mailbox until the capacity of the mailbox (if any) has been reached. In case a bounded mailbox overflows, a MessageQueueAppendFailedException is thrown.

The stash is guaranteed to be empty after calling unstashAll().

Specified by:

unstashAll in interface StashSupport

waitingRecoveryPermit

java.lang.Object waitingRecoveryPermit(Recovery recovery)

recoveryStarted

java.lang.Object recoveryStarted(long replayMax)

recovering

java.lang.Object recovering(scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> recoveryBehavior,
                            scala.concurrent.duration.FiniteDuration timeout)

flushBatch

void flushBatch()

peekApplyHandler

void peekApplyHandler(java.lang.Object payload)