Class Eventsourced

The base class for all persistent actors.

Inheritance

object

ActorBase

Eventsourced

PersistentActor

UntypedPersistentActor

Implements

IInternalActor

IPersistentIdentity

IPersistenceStash

IWithUnboundedStash

IWithUnrestrictedStash

IActorStash

IRequiresMessageQueue<IUnboundedDequeBasedMessageQueueSemantics>

IPersistenceRecovery

Inherited Members

ActorBase.Sender

ActorBase.Self

ActorBase.Context

ActorBase.Receive(object)

ActorBase.EmptyReceive

ActorBase.Become(Receive)

ActorBase.BecomeStacked(Receive)

ActorBase.UnbecomeStacked()

ActorBase.SetReceiveTimeout(TimeSpan?)

ActorBase.PreStart()

ActorBase.PreRestart(Exception, object)

ActorBase.PostRestart(Exception)

ActorBase.PostStop()

ActorBase.SupervisorStrategy()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Akka.Persistence

Assembly: Akka.Persistence.dll

Syntax

public abstract class Eventsourced : ActorBase, IInternalActor, IPersistentIdentity, IPersistenceStash, IWithUnboundedStash, IWithUnrestrictedStash, IActorStash, IRequiresMessageQueue<IUnboundedDequeBasedMessageQueueSemantics>, IPersistenceRecovery

Constructors

Eventsourced()

Initializes a new instance of the Eventsourced class.

Declaration

protected Eventsourced()

Fields

UnstashFilterPredicate

Function used to filter out messages that should not be unstashed during recovery.

Declaration

public static readonly Func<Envelope, bool> UnstashFilterPredicate

Field Value

Type	Description
Func<Envelope, bool>

Properties

Extension

TBD

Declaration

protected PersistenceExtension Extension { get; }

Property Value

Type	Description
PersistenceExtension

InternalStashOverflowStrategy

TBD

Declaration

public virtual IStashOverflowStrategy InternalStashOverflowStrategy { get; }

Property Value

Type	Description
IStashOverflowStrategy

IsRecovering

Returns true if this persistent entity is currently recovering.

Declaration

public bool IsRecovering { get; }

Property Value

Type	Description
bool

IsRecoveryFinished

Returns true if this persistent entity has successfully finished recovery.

Declaration

public bool IsRecoveryFinished { get; }

Property Value

Type	Description
bool

Journal

TBD

Declaration

public IActorRef Journal { get; }

Property Value

Type	Description
IActorRef

JournalPluginId

TBD

Declaration

public string JournalPluginId { get; protected set; }

Property Value

Type	Description
string

LastSequenceNr

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

Declaration

public long LastSequenceNr { get; }

Property Value

Type	Description
long

Log

TBD

Declaration

protected virtual ILoggingAdapter Log { get; }

Property Value

Type	Description
ILoggingAdapter

PersistenceId

Id of the persistent entity for which messages should be replayed.

Declaration

public abstract string PersistenceId { get; }

Property Value

Type	Description
string

Recovery

Called when the persistent actor is started for the first time. The returned Recovery object defines how the actor will recover its persistent state before handling the first incoming message.

To skip recovery completely return None.

Declaration

public virtual Recovery Recovery { get; }

Property Value

Type	Description
Recovery

SnapshotPluginId

TBD

Declaration

public string SnapshotPluginId { get; protected set; }

Property Value

Type	Description
string

SnapshotSequenceNr

Returns LastSequenceNr

Declaration

public long SnapshotSequenceNr { get; }

Property Value

Type	Description
long

SnapshotStore

TBD

Declaration

public IActorRef SnapshotStore { get; }

Property Value

Type	Description
IActorRef

SnapshotterId

Returns PersistenceId.

Declaration

public string SnapshotterId { get; }

Property Value

Type	Description
string

Stash

TBD

Declaration

public IStash Stash { get; set; }

Property Value

Type	Description
IStash

Methods

AroundPostRestart(Exception, object)

Can be overridden to intercept calls to PostRestart. Calls PostRestart by default.

Declaration

public override void AroundPostRestart(Exception reason, object message)

Parameters

Type	Name	Description
Exception	reason
object	message	The message.

Overrides

ActorBase.AroundPostRestart(Exception, object)

AroundPostStop()

Can be overridden to intercept calls to PostStop. Calls PostStop by default..

Declaration

public override void AroundPostStop()

Overrides

ActorBase.AroundPostStop()

AroundPreRestart(Exception, object)

Can be overridden to intercept calls to PreRestart. Calls PreRestart by default.

Declaration

public override void AroundPreRestart(Exception cause, object message)

Parameters

Type	Name	Description
Exception	cause	The cause.
object	message	The message.

Overrides

ActorBase.AroundPreRestart(Exception, object)

AroundPreStart()

Can be overridden to intercept calls to PreStart. Calls PreStart by default.

Declaration

public override void AroundPreStart()

Overrides

ActorBase.AroundPreStart()

AroundReceive(Receive, object)

TBD

Declaration

protected override bool AroundReceive(Receive receive, object message)

Parameters

Type	Name	Description
Receive	receive	TBD
object	message	TBD

Returns

Type	Description
bool	TBD

Overrides

ActorBase.AroundReceive(Receive, object)

DeferAsync<TEvent>(TEvent, Action<TEvent>)

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<TEvent>(TEvent, Action<TEvent>) calls. That is, if PersistAsync<TEvent>(TEvent, Action<TEvent>) was invoked before DeferAsync<TEvent>(TEvent, Action<TEvent>), the corresponding handlers will be invoked in the same order as they were registered in.

This call will NOT result in evt being persisted, use Persist<TEvent>(TEvent, Action<TEvent>) or PersistAsync<TEvent>(TEvent, Action<TEvent>) instead if the given evt should be 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.

Declaration

public void DeferAsync<TEvent>(TEvent evt, Action<TEvent> handler)

Parameters

Type	Name	Description
TEvent	evt	TBD
Action<TEvent>	handler	TBD

Type Parameters

Name	Description
TEvent	TBD

DeleteMessages(long)

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.

The given toSequenceNr must be less than or equal to LastSequenceNr, otherwise DeleteMessagesFailure is sent to the actor without performing the delete. All persistent messages may be deleted without specifying the actual sequence number by using MaxValue as the toSequenceNr.

Declaration

public void DeleteMessages(long toSequenceNr)

Parameters

Type	Name	Description
long	toSequenceNr	Upper sequence number bound of persistent messages to be deleted.

DeleteSnapshot(long)

Deletes the snapshot identified by sequenceNr.

The PersistentActor will be notified about the status of the deletion via an DeleteSnapshotSuccess or DeleteSnapshotFailure message.

Declaration

public void DeleteSnapshot(long sequenceNr)

Parameters

Type	Name	Description
long	sequenceNr	TBD

DeleteSnapshots(SnapshotSelectionCriteria)

Deletes all snapshots matching criteria.

The PersistentActor will be notified about the status of the deletion via an DeleteSnapshotsSuccess or DeleteSnapshotsFailure message.

Declaration

public void DeleteSnapshots(SnapshotSelectionCriteria criteria)

Parameters

Type	Name	Description
SnapshotSelectionCriteria	criteria	TBD

LoadSnapshot(string, SnapshotSelectionCriteria, long)

Instructs the snapshot store to load the specified snapshot and send it via an SnapshotOffer to the running PersistentActor.

Declaration

public void LoadSnapshot(string persistenceId, SnapshotSelectionCriteria criteria, long toSequenceNr)

Parameters

Type	Name	Description
string	persistenceId	TBD
SnapshotSelectionCriteria	criteria	TBD
long	toSequenceNr	TBD

OnPersistFailure(Exception, object, long)

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.

Declaration

protected virtual void OnPersistFailure(Exception cause, object @event, long sequenceNr)

Parameters

Type	Name	Description
Exception	cause	TBD
object	event	TBD
long	sequenceNr	TBD

OnPersistRejected(Exception, object, long)

Called when the journal rejected Persist<TEvent>(TEvent, Action<TEvent>) of an event. The event was not stored. By default this method logs the problem as an error, and the actor continues. The callback handler that was passed to the Persist<TEvent>(TEvent, Action<TEvent>) method will not be invoked.

Declaration

protected virtual void OnPersistRejected(Exception cause, object @event, long sequenceNr)

Parameters

Type	Name	Description
Exception	cause	TBD
object	event	TBD
long	sequenceNr	TBD

OnRecoveryFailure(Exception, object)

Called whenever a message replay fails. By default it log the errors.

Declaration

protected virtual void OnRecoveryFailure(Exception reason, object message = null)

Parameters

Type	Name	Description
Exception	reason	Reason of failure
object	message	Message that caused a failure

OnReplaySuccess()

Called whenever a message replay succeeds.

Declaration

protected virtual void OnReplaySuccess()

PersistAllAsync<TEvent>(IEnumerable<TEvent>, Action<TEvent>)

Asynchronously persists series of events in specified order. This is equivalent of multiple calls of PersistAsync<TEvent>(TEvent, Action<TEvent>) calls with the same handler, except that events are persisted atomically with this method.

Declaration

public void PersistAllAsync<TEvent>(IEnumerable<TEvent> events, Action<TEvent> handler)

Parameters

Type	Name	Description
IEnumerable<TEvent>	events	TBD
Action<TEvent>	handler	TBD

Type Parameters

Name	Description
TEvent	TBD

PersistAll<TEvent>(IEnumerable<TEvent>, Action<TEvent>)

Asynchronously persists series of events in specified order. This is equivalent of multiple calls of Persist<TEvent>(TEvent, Action<TEvent>) calls with the same handler, except that events are persisted atomically with this method.

Declaration

public void PersistAll<TEvent>(IEnumerable<TEvent> events, Action<TEvent> handler)

Parameters

Type	Name	Description
IEnumerable<TEvent>	events	TBD
Action<TEvent>	handler	TBD

Type Parameters

Name	Description
TEvent	TBD

PersistAsync<TEvent>(TEvent, Action<TEvent>)

Asynchronously persists an event. On successful persistence, the handler is called with the persisted event. Unlike Persist<TEvent>(TEvent, Action<TEvent>) method, this one will continue to receive incoming commands between calls and executing it's event handler.

This version should be used in favor of Persist<TEvent>(TEvent, Action<TEvent>) method when throughput is more important that commands execution precedence.

An event handler may close over eventsourced actor state and modify it. Sender of the persistent event is considered a sender of the corresponding command. That means, one can respond to sender from 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(Exception, 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 event 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.

Declaration

public void PersistAsync<TEvent>(TEvent @event, Action<TEvent> handler)

Parameters

Type	Name	Description
TEvent	event	TBD
Action<TEvent>	handler	TBD

Type Parameters

Name	Description
TEvent	TBD

Persist<TEvent>(TEvent, Action<TEvent>)

Asynchronously persists an event. On successful persistence, the handler is called with the persisted event. This method guarantees that no new commands will be received by a persistent actor between a call to Persist<TEvent>(TEvent, Action<TEvent>) and execution of its handler. It also holds multiple persist calls per received command. Internally this is done by stashing. The stash used for that is an internal stash which doesn't interfere with the inherited user stash.

An event handler may close over eventsourced actor state and modify it. Sender of the persistent event is considered a sender of the corresponding command. That means one can respond to sender from 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(Exception, 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 event 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.

Declaration

public void Persist<TEvent>(TEvent @event, Action<TEvent> handler)

Parameters

Type	Name	Description
TEvent	event	TBD
Action<TEvent>	handler	TBD

Type Parameters

Name	Description
TEvent	TBD

ReceiveCommand(object)

Command handler. Typically validates commands against current state - possibly by communicating with other actors. On successful validation, one or more events are derived from command and persisted.

Declaration

protected abstract bool ReceiveCommand(object message)

Parameters

Type	Name	Description
object	message	TBD

Returns

Type	Description
bool	TBD

ReceiveRecover(object)

Recovery handler that receives persistent 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 offer itself.

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.

Declaration

protected abstract bool ReceiveRecover(object message)

Parameters

Type	Name	Description
object	message	TBD

Returns

Type	Description
bool	TBD

RunTask(Func<Task>)

Runs an asynchronous task for incoming messages in context of ReceiveCommand(object) . The actor will be suspended until the task returned by action completes, including the Persist<TEvent>(TEvent, Action<TEvent>) and PersistAll<TEvent>(IEnumerable<TEvent>, Action<TEvent>) calls.

Declaration

protected void RunTask(Func<Task> action)

Parameters

Type	Name	Description
Func<Task>	action	Async task to run

SaveSnapshot(object)

Saves snapshot of current ISnapshotter state.

The PersistentActor will be notified about the success or failure of this via an SaveSnapshotSuccess or SaveSnapshotFailure message.

Declaration

public void SaveSnapshot(object snapshot)

Parameters

Type	Name	Description
object	snapshot	TBD

Unhandled(object)

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

Declaration

protected override void Unhandled(object message)

Parameters

Type	Name	Description
object	message	The unhandled message.

Overrides

ActorBase.Unhandled(object)

Exceptions

Type	Condition
DeathPactException	This exception is thrown if the given message is a Terminated message.

Implements

IInternalActor

IPersistentIdentity

IPersistenceStash

IWithUnboundedStash

IWithUnrestrictedStash

IActorStash

IRequiresMessageQueue<T>

IPersistenceRecovery

Extension Methods

ObjectExtensions.IsDefaultForType<T>(T)

ObjectExtensions.AsOption<T>(T)

Extensions.AsInstanceOf<T>(object)