Spring/spring-statemachine
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Docs updates

Browse Source
This commit is contained in:
Janne Valkealahti
2015-07-05 17:36:45 +01:00
parent 24ca522802
commit 9b6caaf6b8
2 changed files with 115 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/src/reference/asciidoc/sm.adoc
View File

@@ -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

86
spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsConfigurationSampleTests.java
View File

@@ -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<States, Events> {
public static class Config1Enums
extends EnumStateMachineConfigurerAdapter<States, Events> {
@Override
public void configure(StateMachineStateConfigurer<States, Events> states)
@@ -74,12 +80,32 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
}
}
// end::snippetA[]
// end::snippetAA[]
// tag::snippetAB[]
@Configuration
@EnableStateMachine
public static class Config1Strings
extends StateMachineConfigurerAdapter<String, String> {
@Override
public void configure(StateMachineStateConfigurer<String, String> states)
throws Exception {
states
.withStates()
.initial("S1")
.end("SF")
.states(new HashSet<String>(Arrays.asList("S1","S2","S3","S4")));
}
}
// end::snippetAB[]
// tag::snippetB[]
@Configuration
@EnableStateMachine
public static class Config2 extends EnumStateMachineConfigurerAdapter<States, Events> {
public static class Config2
extends EnumStateMachineConfigurerAdapter<States, Events> {
@Override
public void configure(StateMachineStateConfigurer<States, Events> states)
@@ -101,7 +127,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
// tag::snippetC[]
@Configuration
@EnableStateMachine
public static class Config3 extends EnumStateMachineConfigurerAdapter<States, Events> {
public static class Config3
extends EnumStateMachineConfigurerAdapter<States, Events> {
@Override
public void configure(StateMachineStateConfigurer<States, Events> states)
@@ -135,7 +162,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
// tag::snippetD[]
@Configuration
@EnableStateMachine
public static class Config4 extends EnumStateMachineConfigurerAdapter<States, Events> {
public static class Config4
extends EnumStateMachineConfigurerAdapter<States, Events> {
@Override
public void configure(StateMachineTransitionConfigurer<States, Events> transitions)
@@ -170,7 +198,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
// tag::snippetE[]
@Configuration
@EnableStateMachine
public static class Config5 extends EnumStateMachineConfigurerAdapter<States, Events> {
public static class Config5
extends EnumStateMachineConfigurerAdapter<States, Events> {
@Override
public void configure(StateMachineTransitionConfigurer<States, Events> transitions)
@@ -197,11 +226,11 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
}
// end::snippetE[]
// tag::snippetF[]
// tag::snippetFA[]
@Configuration
@EnableStateMachineFactory
public static class Config6
extends EnumStateMachineConfigurerAdapter<States, Events> {
extends EnumStateMachineConfigurerAdapter<States, Events> {
@Override
public void configure(StateMachineStateConfigurer<States, Events> states)
@@ -214,12 +243,23 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
}
}
// end::snippetF[]
// end::snippetFA[]
// tag::snippetFB[]
StateMachine<String, String> buildMachine() throws Exception {
Builder<String, String> builder = StateMachineBuilder.builder();
builder.configureStates()
.withStates()
.initial("S1")
.end("SF")
.states(new HashSet<String>(Arrays.asList("S1","S2","S3","S4")));
return builder.build();
}
// end::snippetFB[]
// tag::snippetG[]
static class StateMachineApplicationEventListener
implements ApplicationListener<StateMachineEvent> {
implements ApplicationListener<StateMachineEvent> {
@Override
public void onApplicationEvent(StateMachineEvent event) {
@@ -229,7 +269,7 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
// tag::snippetH[]
static class StateMachineEventListener
extends StateMachineListenerAdapter<States, Events> {
extends StateMachineListenerAdapter<States, Events> {
@Override
public void stateChanged(State<States, Events> from, State<States, Events> to) {
@@ -330,13 +370,13 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
@Configuration
@EnableStateMachine(contextEvents = false)
public static class Config8
extends EnumStateMachineConfigurerAdapter<States, Events> {
extends EnumStateMachineConfigurerAdapter<States, Events> {
}
@Configuration
@EnableStateMachineFactory(contextEvents = false)
public static class Config9
extends EnumStateMachineConfigurerAdapter<States, Events> {
extends EnumStateMachineConfigurerAdapter<States, Events> {
}
// end::snippetN[]
@@ -392,7 +432,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
// tag::snippetQ[]
@Configuration
@EnableStateMachine
public static class Config11 extends EnumStateMachineConfigurerAdapter<States, Events> {
public static class Config11
extends EnumStateMachineConfigurerAdapter<States, Events> {
@Override
public void configure(StateMachineStateConfigurer<States, Events> states)
@@ -421,7 +462,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
// tag::snippetR[]
@Configuration
@EnableStateMachine
public static class Config12 extends EnumStateMachineConfigurerAdapter<States3, Events> {
public static class Config12
extends EnumStateMachineConfigurerAdapter<States3, Events> {
@Override
public void configure(StateMachineStateConfigurer<States3, Events> states)
@@ -445,7 +487,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
// tag::snippetS[]
@Configuration
@EnableStateMachine
public static class Config13 extends EnumStateMachineConfigurerAdapter<States, Events> {
public static class Config13
extends EnumStateMachineConfigurerAdapter<States, Events> {
@Override
public void configure(StateMachineStateConfigurer<States, Events> states)
@@ -497,7 +540,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
// tag::snippetT[]
@Configuration
@EnableStateMachine
public static class Config14 extends EnumStateMachineConfigurerAdapter<States2, Events> {
public static class Config14
extends EnumStateMachineConfigurerAdapter<States2, Events> {
@Override
public void configure(StateMachineStateConfigurer<States2, Events> states)
@@ -539,7 +583,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
// tag::snippetU[]
@Configuration
@EnableStateMachine
public static class Config15 extends EnumStateMachineConfigurerAdapter<States2, Events> {
public static class Config15
extends EnumStateMachineConfigurerAdapter<States2, Events> {
@Override
public void configure(StateMachineStateConfigurer<States2, Events> states)
@@ -580,7 +625,8 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
@Configuration
@EnableStateMachine
public static class Config16 extends EnumStateMachineConfigurerAdapter<States, Events> {
public static class Config16
extends EnumStateMachineConfigurerAdapter<States, Events> {
// tag::snippetVA[]
@Override