From 9b6caaf6b827ee1dfefe992a29c9f59c3b86207d Mon Sep 17 00:00:00 2001 From: Janne Valkealahti Date: Sun, 5 Jul 2015 17:36:45 +0100 Subject: [PATCH] Docs updates --- docs/src/reference/asciidoc/sm.adoc | 52 ++++++++++- .../docs/DocsConfigurationSampleTests.java | 86 ++++++++++++++----- 2 files changed, 115 insertions(+), 23 deletions(-) diff --git a/docs/src/reference/asciidoc/sm.adoc b/docs/src/reference/asciidoc/sm.adoc index b51925d5..a0730914 100644 --- a/docs/src/reference/asciidoc/sm.adoc +++ b/docs/src/reference/asciidoc/sm.adoc @@ -39,9 +39,27 @@ possible states, choose initial and optional end state. [source,java,indent=0] ---- -include::samples/DocsConfigurationSampleTests.java[tags=snippetA] +include::samples/DocsConfigurationSampleTests.java[tags=snippetAA] ---- +It's also possible to use strings instead of enums as states and +events by using `StateMachineConfigurerAdapter` as shown below. Most +of a configuration examples is using enums but generally speaking +strings and enums can be just interchanged. + +[source,java,indent=0] +---- +include::samples/DocsConfigurationSampleTests.java[tags=snippetAB] +---- + +[NOTE] +==== +Using enums will bring more safe set of states and event types but +limits possible combinations to compile time. Strings don't have this +limitation and allows user to use more dynamic ways to build state +machine configurations but doesn't allow same level of safety. +==== + === Configuring Hierarchical States Hierarchical states can be defined by using multiple `withStates()` calls where `parent()` can be used to indicate that these @@ -203,13 +221,14 @@ Configuration for state machine factory is exactly same as you've seen in various examples in this document where state machine configuration is hard coded. +=== Factory via Adapter Actually creating a state machine using _@EnableStateMachine_ will work via factory so _@EnableStateMachineFactory_ is merely exposing that factory via its interface. [source,java,indent=0] ---- -include::samples/DocsConfigurationSampleTests.java[tags=snippetF] +include::samples/DocsConfigurationSampleTests.java[tags=snippetFA] ---- Now that you've used _@EnableStateMachineFactory_ to create a factory @@ -221,7 +240,7 @@ request new state machines. include::samples/DocsConfigurationSampleTests.java[tags=snippetL] ---- -=== Factory Limitations +==== Adapter Factory Limitations Current limitation of factory is that all actions and guard it is associating with created state machine will share a same instances. This means that from your actions and guard you will need to @@ -229,6 +248,33 @@ specifically handle a case that same bean will be called by a different state machines. This limitation is something which will be resolved in future releases. +=== Factory via Builder +Using adapters shown above has a limitation imposed by its +requirement to work via Spring `@Configuration` classes and +application context. While this is a very clear model to configure a +state machine instances it will limit configuration at a compile time +which is not always what a user wants to do. If there is a requirement +to build more dynamic state machines, a simple builder patter can be +used to construct similar instances. Using strings as states and +events this builder patter can be used to build fully dynamic state +machines outside of a Spring application context as shown above. + +[source,java,indent=0] +---- +include::samples/DocsConfigurationSampleTests.java[tags=snippetFB] +---- + +Builder is using same configuration interfaces behind the scenes that +the `@Configuration` model using adapter classes. Same model goes to +configuring transitions via builder's `configureTransitions()` method. + +[NOTE] +==== +Currently `builder.configureStates()` and +`builder.configureTransitions()` cannot be chained together meaning +builder methods needs to be called individually. +==== + [[sm-actions]] == Using Actions Actions are one of the most useful components from user perspective to 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 176cbd36..d434112d 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 @@ -19,7 +19,9 @@ import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +import java.util.Arrays; import java.util.EnumSet; +import java.util.HashSet; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.context.ApplicationListener; @@ -40,7 +42,10 @@ import org.springframework.statemachine.annotation.WithStateMachine; import org.springframework.statemachine.config.EnableStateMachine; import org.springframework.statemachine.config.EnableStateMachineFactory; import org.springframework.statemachine.config.EnumStateMachineConfigurerAdapter; +import org.springframework.statemachine.config.StateMachineBuilder; +import org.springframework.statemachine.config.StateMachineConfigurerAdapter; import org.springframework.statemachine.config.StateMachineFactory; +import org.springframework.statemachine.config.StateMachineBuilder.Builder; import org.springframework.statemachine.config.builders.StateMachineStateConfigurer; import org.springframework.statemachine.config.builders.StateMachineTransitionConfigurer; import org.springframework.statemachine.config.configurers.StateConfigurer.History; @@ -58,10 +63,11 @@ import org.springframework.statemachine.transition.Transition; */ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { -// tag::snippetA[] +// tag::snippetAA[] @Configuration @EnableStateMachine - public static class Config1 extends EnumStateMachineConfigurerAdapter { + public static class Config1Enums + extends EnumStateMachineConfigurerAdapter { @Override public void configure(StateMachineStateConfigurer states) @@ -74,12 +80,32 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { } } -// end::snippetA[] +// end::snippetAA[] + +// tag::snippetAB[] + @Configuration + @EnableStateMachine + public static class Config1Strings + extends StateMachineConfigurerAdapter { + + @Override + public void configure(StateMachineStateConfigurer states) + throws Exception { + states + .withStates() + .initial("S1") + .end("SF") + .states(new HashSet(Arrays.asList("S1","S2","S3","S4"))); + } + + } +// end::snippetAB[] // tag::snippetB[] @Configuration @EnableStateMachine - public static class Config2 extends EnumStateMachineConfigurerAdapter { + public static class Config2 + extends EnumStateMachineConfigurerAdapter { @Override public void configure(StateMachineStateConfigurer states) @@ -101,7 +127,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { // tag::snippetC[] @Configuration @EnableStateMachine - public static class Config3 extends EnumStateMachineConfigurerAdapter { + public static class Config3 + extends EnumStateMachineConfigurerAdapter { @Override public void configure(StateMachineStateConfigurer states) @@ -135,7 +162,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { // tag::snippetD[] @Configuration @EnableStateMachine - public static class Config4 extends EnumStateMachineConfigurerAdapter { + public static class Config4 + extends EnumStateMachineConfigurerAdapter { @Override public void configure(StateMachineTransitionConfigurer transitions) @@ -170,7 +198,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { // tag::snippetE[] @Configuration @EnableStateMachine - public static class Config5 extends EnumStateMachineConfigurerAdapter { + public static class Config5 + extends EnumStateMachineConfigurerAdapter { @Override public void configure(StateMachineTransitionConfigurer transitions) @@ -197,11 +226,11 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { } // end::snippetE[] -// tag::snippetF[] +// tag::snippetFA[] @Configuration @EnableStateMachineFactory public static class Config6 - extends EnumStateMachineConfigurerAdapter { + extends EnumStateMachineConfigurerAdapter { @Override public void configure(StateMachineStateConfigurer states) @@ -214,12 +243,23 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { } } -// end::snippetF[] +// end::snippetFA[] +// tag::snippetFB[] + StateMachine buildMachine() throws Exception { + Builder builder = StateMachineBuilder.builder(); + builder.configureStates() + .withStates() + .initial("S1") + .end("SF") + .states(new HashSet(Arrays.asList("S1","S2","S3","S4"))); + return builder.build(); + } +// end::snippetFB[] // tag::snippetG[] static class StateMachineApplicationEventListener - implements ApplicationListener { + implements ApplicationListener { @Override public void onApplicationEvent(StateMachineEvent event) { @@ -229,7 +269,7 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { // tag::snippetH[] static class StateMachineEventListener - extends StateMachineListenerAdapter { + extends StateMachineListenerAdapter { @Override public void stateChanged(State from, State to) { @@ -330,13 +370,13 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { @Configuration @EnableStateMachine(contextEvents = false) public static class Config8 - extends EnumStateMachineConfigurerAdapter { + extends EnumStateMachineConfigurerAdapter { } @Configuration @EnableStateMachineFactory(contextEvents = false) public static class Config9 - extends EnumStateMachineConfigurerAdapter { + extends EnumStateMachineConfigurerAdapter { } // end::snippetN[] @@ -392,7 +432,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { // tag::snippetQ[] @Configuration @EnableStateMachine - public static class Config11 extends EnumStateMachineConfigurerAdapter { + public static class Config11 + extends EnumStateMachineConfigurerAdapter { @Override public void configure(StateMachineStateConfigurer states) @@ -421,7 +462,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { // tag::snippetR[] @Configuration @EnableStateMachine - public static class Config12 extends EnumStateMachineConfigurerAdapter { + public static class Config12 + extends EnumStateMachineConfigurerAdapter { @Override public void configure(StateMachineStateConfigurer states) @@ -445,7 +487,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { // tag::snippetS[] @Configuration @EnableStateMachine - public static class Config13 extends EnumStateMachineConfigurerAdapter { + public static class Config13 + extends EnumStateMachineConfigurerAdapter { @Override public void configure(StateMachineStateConfigurer states) @@ -497,7 +540,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { // tag::snippetT[] @Configuration @EnableStateMachine - public static class Config14 extends EnumStateMachineConfigurerAdapter { + public static class Config14 + extends EnumStateMachineConfigurerAdapter { @Override public void configure(StateMachineStateConfigurer states) @@ -539,7 +583,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { // tag::snippetU[] @Configuration @EnableStateMachine - public static class Config15 extends EnumStateMachineConfigurerAdapter { + public static class Config15 + extends EnumStateMachineConfigurerAdapter { @Override public void configure(StateMachineStateConfigurer states) @@ -580,7 +625,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { @Configuration @EnableStateMachine - public static class Config16 extends EnumStateMachineConfigurerAdapter { + public static class Config16 + extends EnumStateMachineConfigurerAdapter { // tag::snippetVA[] @Override