From b5eb18a033f785c9b9368c2464adc033ae2b8a80 Mon Sep 17 00:00:00 2001 From: Christopher Batey Date: Tue, 15 Oct 2019 11:22:14 +0100 Subject: [PATCH] Document using an EventSourcedBehavior as a PersistentFSM (#27931) Re-uses the code from the migration guide as the mgiration logic is in adapters. Almost seems very obvious you can do this but can't hurt to have. * Apply suggestions from code review Co-Authored-By: Helena Edelson --- .../main/paradox/typed/index-persistence.md | 1 + .../src/main/paradox/typed/persistence-fsm.md | 57 +++++++++++++++++++ 2 files changed, 58 insertions(+) create mode 100644 akka-docs/src/main/paradox/typed/persistence-fsm.md diff --git a/akka-docs/src/main/paradox/typed/index-persistence.md b/akka-docs/src/main/paradox/typed/index-persistence.md index 002e940c32..ce957f42f4 100644 --- a/akka-docs/src/main/paradox/typed/index-persistence.md +++ b/akka-docs/src/main/paradox/typed/index-persistence.md @@ -12,6 +12,7 @@ project.description: Event Sourcing with Akka Persistence enables actors to pers * [persistence-style](persistence-style.md) * [persistence-snapshot](persistence-snapshot.md) * [persistence-testing.md](persistence-testing.md) +* [persistence-fsm.md](persistence-fsm.md) * [persistence-schema-evolution](../persistence-schema-evolution.md) * [persistence-query](../persistence-query.md) * [persistence-query-leveldb](../persistence-query-leveldb.md) diff --git a/akka-docs/src/main/paradox/typed/persistence-fsm.md b/akka-docs/src/main/paradox/typed/persistence-fsm.md new file mode 100644 index 0000000000..56d4bdae59 --- /dev/null +++ b/akka-docs/src/main/paradox/typed/persistence-fsm.md @@ -0,0 +1,57 @@ +# EventSourced behaviors as finite state machines + +An @apidoc[EventSourcedBehavior] can be used to represent a persistent FSM. If you're migrating an existing classic +persistent FSM to EventSourcedBehavior see the @ref[migration guide](../persistence-fsm.md#migration-to-eventsourcedbehavior). + +To demonstrate this consider an example of a shopping application. A customer can be in the following states: + +* Looking around +* Shopping (has something in their basket) +* Inactive +* Paid + +Scala +: @@snip [PersistentFsmToTypedMigrationSpec.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/PersistentFsmToTypedMigrationSpec.scala) { #state } + +Java +: @@snip [PersistentFsmToTypedMigrationCompileOnlyTest.java](/akka-persistence-typed/src/test/java/jdocs/akka/persistence/typed/PersistentFsmToTypedMigrationCompileOnlyTest.java) { #state } + + +And the commands that can result in state changes: + +* Add item +* Buy +* Leave +* Timeout (internal command to discard abandoned purchases) + +And the following read only commands: + +* Get current cart + +Scala +: @@snip [PersistentFsmToTypedMigrationSpec.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/PersistentFsmToTypedMigrationSpec.scala) { #commands } + +Java +: @@snip [PersistentFsmToTypedMigrationCompileOnlyTest.java](/akka-persistence-typed/src/test/java/jdocs/akka/persistence/typed/PersistentFsmToTypedMigrationCompileOnlyTest.java) { #commands } + +The command handler of the EventSourcedBehavior is used to convert the commands that change the state of the FSM +to events, and reply to commands. + +@scala[The command handler:]@java[The `forStateType` command handler can be used:] + +Scala +: @@snip [PersistentFsmToTypedMigrationSpec.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/PersistentFsmToTypedMigrationSpec.scala) { #command-handler } + +Java +: @@snip [PersistentFsmToTypedMigrationCompileOnlyTest.java](/akka-persistence-typed/src/test/java/jdocs/akka/persistence/typed/PersistentFsmToTypedMigrationCompileOnlyTest.java) { #command-handler } + +The event handler is used to change state once the events have been persisted. When the EventSourcedBehavior is restarted +the events are replayed to get back into the correct state. + +Scala +: @@snip [PersistentFsmToTypedMigrationSpec.scala](/akka-persistence-typed/src/test/scala/docs/akka/persistence/typed/PersistentFsmToTypedMigrationSpec.scala) { #event-handler } + +Java +: @@snip [PersistentFsmToTypedMigrationCompileOnlyTest.java](/akka-persistence-typed/src/test/java/jdocs/akka/persistence/typed/PersistentFsmToTypedMigrationCompileOnlyTest.java) { #event-handler } + +