From db5a1ab3f7765bdf562ed2d6b456ebd7329f9bf3 Mon Sep 17 00:00:00 2001 From: Janne Valkealahti Date: Sun, 12 Jul 2015 17:19:46 +0100 Subject: [PATCH] Update docs --- docs/src/reference/asciidoc/sm.adoc | 43 ++++++++++++++++--- .../docs/DocsConfigurationSampleTests.java | 25 +++++++++++ 2 files changed, 62 insertions(+), 6 deletions(-) diff --git a/docs/src/reference/asciidoc/sm.adoc b/docs/src/reference/asciidoc/sm.adoc index a0730914..683fd8db 100644 --- a/docs/src/reference/asciidoc/sm.adoc +++ b/docs/src/reference/asciidoc/sm.adoc @@ -144,7 +144,7 @@ This can be done max one time per individual sub-machine or region. [source,java,indent=0] ---- -include::samples/DocsConfigurationSampleTests.java[tags=snippetA] +include::samples/DocsConfigurationSampleTests.java[tags=snippetAA] ---- ==== History State @@ -208,6 +208,34 @@ states from a regions. include::samples/DocsConfigurationSampleTests.java[tags=snippetU] ---- +=== Configuring Common Settings +Some of a common state machine configuration can be set via a +`ConfigurationConfigurer`. This allows to set `BeanFactory`, +`TaskExecutor`, `TaskScheduler`, autostart flag for a state machine +and register `StateMachineListener` instances. + +[source,java,indent=0] +---- +include::samples/DocsConfigurationSampleTests.java[tags=snippetY] +---- + +State machine `autoStartup` flag is disabled by default because all +instances handling sub-states are controlled by a state machine itself +and cannot be started automatically. Also it is much safer to leave +this decision to a user whether a machine should be started +automatically or not. This flag will only control an autostart of a +top-level state machine. + +Setting a `BeanFactory`, `TaskExecutor` or `TaskScheduler` exist for +conveniance for a user and are also use within a framework itself. + +Registering `StateMachineListener` instances is also partly for +convenience but is required if user wants to catch callback during a +state machine lifecycle like getting notified of a state machine +start/stop events. Naturally it is not possible to listen a state +machine start events if `autoStartup` is enabled unless listener can +be registered during a configuration phase. + [[sm-factories]] == State Machine Factories There are use cases when state machine needs to be created dynamically @@ -248,7 +276,7 @@ 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 +=== State Machine 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 @@ -266,13 +294,16 @@ 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. +configuring transitions, states and common configuration via builder's +methods. This simply means that whatever you can use with a normal +`EnumStateMachineConfigurerAdapter` or `StateMachineConfigurerAdapter` +can be used dynamically via a builder. [NOTE] ==== -Currently `builder.configureStates()` and -`builder.configureTransitions()` cannot be chained together meaning -builder methods needs to be called individually. +Currently `builder.configureStates()`, +`builder.configureTransitions()` and other interface methods cannot be +chained together meaning builder methods needs to be called individually. ==== [[sm-actions]] 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 d434112d..8c1a77fc 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 @@ -24,14 +24,17 @@ import java.util.EnumSet; import java.util.HashSet; import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.beans.factory.support.StaticListableBeanFactory; import org.springframework.context.ApplicationListener; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; +import org.springframework.core.task.SyncTaskExecutor; import org.springframework.expression.Expression; import org.springframework.expression.ExpressionParser; import org.springframework.expression.spel.standard.SpelExpressionParser; import org.springframework.messaging.Message; import org.springframework.messaging.support.MessageBuilder; +import org.springframework.scheduling.concurrent.ConcurrentTaskScheduler; import org.springframework.statemachine.AbstractStateMachineTests; import org.springframework.statemachine.StateContext; import org.springframework.statemachine.StateMachine; @@ -46,6 +49,7 @@ 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.StateMachineConfigurationConfigurer; import org.springframework.statemachine.config.builders.StateMachineStateConfigurer; import org.springframework.statemachine.config.builders.StateMachineTransitionConfigurer; import org.springframework.statemachine.config.configurers.StateConfigurer.History; @@ -731,4 +735,25 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests { } +// tag::snippetY[] + @Configuration + @EnableStateMachine + public static class Config17 + extends EnumStateMachineConfigurerAdapter { + + @Override + public void configure(StateMachineConfigurationConfigurer config) + throws Exception { + config + .withConfiguration() + .autoStartup(true) + .beanFactory(new StaticListableBeanFactory()) + .taskExecutor(new SyncTaskExecutor()) + .taskScheduler(new ConcurrentTaskScheduler()) + .listener(new StateMachineListenerAdapter()); + } + + } +// end::snippetY[] + }