From 96773828fcf9b92b0a53750de7980f3eb1f08178 Mon Sep 17 00:00:00 2001 From: Janne Valkealahti Date: Sun, 4 Aug 2019 08:04:05 +0100 Subject: [PATCH] Docs changes - Relates #742 --- ...pendix-reactormigration-communicating.adoc | 13 +++++++- docs/src/reference/asciidoc/sm-triggers.adoc | 33 +++++++++++++++---- .../docs/DocsConfigurationSampleTests.java | 27 ++++++++++++--- .../statemachine/docs/DocsMigrationTests.java | 7 ++++ 4 files changed, 68 insertions(+), 12 deletions(-) diff --git a/docs/src/reference/asciidoc/appendix-reactormigration-communicating.adoc b/docs/src/reference/asciidoc/appendix-reactormigration-communicating.adoc index 90731e4f..44af6541 100644 --- a/docs/src/reference/asciidoc/appendix-reactormigration-communicating.adoc +++ b/docs/src/reference/asciidoc/appendix-reactormigration-communicating.adoc @@ -11,7 +11,8 @@ include::samples/DocsMigrationTests.java[tags=snippetA] We're now solely working on a spring `Message` and reactor `Mono` and `Flux` classes. You can send a `Mono` of a `Message` and receive back a `Flux` of `StateMachineEventResult`. -Remember that nothing happens until you subscribe to this `Flux`. +Remember that nothing happens until you subscribe to this `Flux`. More about +this returned value, see <>. ==== [source,java,indent=0] @@ -38,3 +39,13 @@ do something when event handling is completed, you could do something like. include::samples/DocsMigrationTests.java[tags=snippetB3] ---- ==== + +Old API methods returning a `boolean` for accepted status are still in place +but are deprecated to get removed in future releases. + +==== +[source,java,indent=0] +---- +include::samples/DocsMigrationTests.java[tags=snippetB4] +---- +==== diff --git a/docs/src/reference/asciidoc/sm-triggers.adoc b/docs/src/reference/asciidoc/sm-triggers.adoc index 4d5f1e54..c31d9bf2 100644 --- a/docs/src/reference/asciidoc/sm-triggers.adoc +++ b/docs/src/reference/asciidoc/sm-triggers.adoc @@ -20,13 +20,13 @@ include::samples/DocsConfigurationSampleTests.java[tags=snippetO] ---- ==== -The preceding example sends an event two different ways. First, it -sends a type-safe event by using the state machine API method called -`sendEvent(E event)`. Second, it sends an event wrapped in a Spring -messaging `Message` by using the API method called `sendEvent(Message message)` -with a custom event headers. This lets us add arbitrary extra -information to an event, which is then visible to `StateContext` when -(for example) you implement actions. +IMPORTANT: Nothing happens until returned flux is subscribed. See more about it from +<>. + +The preceding example sends an events by constructing a `Mono` wrapping +a `Message` and subscribing into returned `Flux` of results. `Message` lets +us add arbitrary extra information to an event, which is then visible +to `StateContext` when (for example) you implement actions. NOTE: Message headers are generally passed on until machine runs to completion for a specific event. For example if an event is causing @@ -34,6 +34,25 @@ transition into a state `A` which have an anonymous transition into a state `B`, original event is available for actions or guards in state `B`. +It is also possible to send a `Flux` of messages instead of sending just +one with a `Mono`. + +==== +[source,java,indent=0] +---- +include::samples/DocsConfigurationSampleTests.java[tags=snippetO2] +---- +==== + +[[sm-triggers-statemachineeventresult]] +==== StateMachineEventResult + +`StateMachineEventResult` contains more detailed information about a result +of a event sending. From this you can get a `Region` which handled an event, +`Message` itself and what was an actual `ResultType`. From `ResultType` you +can see if message was accepted, denied or deferred. Generally speaking when +subscribtion completes, events are passed into a machine. + === Using `TimerTrigger` `TimerTrigger` is useful when something needs to be triggered diff --git a/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsConfigurationSampleTests.java b/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsConfigurationSampleTests.java index 9d4f3774..0b8bd127 100644 --- a/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsConfigurationSampleTests.java +++ b/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsConfigurationSampleTests.java @@ -32,6 +32,7 @@ import org.springframework.messaging.support.MessageBuilder; import org.springframework.statemachine.AbstractStateMachineTests; import org.springframework.statemachine.StateContext; import org.springframework.statemachine.StateMachine; +import org.springframework.statemachine.StateMachineEventResult; import org.springframework.statemachine.access.StateMachineAccess; import org.springframework.statemachine.action.Action; import org.springframework.statemachine.action.Actions; @@ -62,6 +63,7 @@ import org.springframework.statemachine.support.StateMachineInterceptorAdapter; import org.springframework.statemachine.transition.Transition; import org.springframework.statemachine.transition.TransitionConflictPolicy; +import reactor.core.publisher.Flux; import reactor.core.publisher.Mono; /** @@ -584,22 +586,39 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { // tag::snippetO[] @Autowired - StateMachine stateMachine; + StateMachine stateMachine; void signalMachine() { stateMachine .sendEvent(Mono.just(MessageBuilder - .withPayload(Events.E1).build())) + .withPayload("E1").build())) .subscribe(); - Message message = MessageBuilder - .withPayload(Events.E2) + Message message = MessageBuilder + .withPayload("E2") .setHeader("foo", "bar") .build(); stateMachine.sendEvent(Mono.just(message)).subscribe(); } // end::snippetO[] + void signalMachine2() { +// tag::snippetO2[] + Message message1 = MessageBuilder + .withPayload("E1") + .build(); + Message message2 = MessageBuilder + .withPayload("E2") + .build(); + + Flux> results = + stateMachine.sendEvents(Flux.just(message1, message2)); + + results.subscribe(); + +// end::snippetO2[] + } + } // tag::snippetP[] diff --git a/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsMigrationTests.java b/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsMigrationTests.java index 460517f3..e59f00be 100644 --- a/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsMigrationTests.java +++ b/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsMigrationTests.java @@ -23,6 +23,7 @@ import org.springframework.statemachine.StateMachineEventResult; import reactor.core.publisher.Flux; import reactor.core.publisher.Mono; +@SuppressWarnings({ "unused", "deprecation" }) public class DocsMigrationTests { StateMachine machine; @@ -55,4 +56,10 @@ public class DocsMigrationTests { .subscribe(); // end::snippetB3[] } + + public void sample3() { + // tag::snippetB4[] + boolean accepted = machine.sendEvent("EVENT"); + // end::snippetB4[] + } }