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

Update docs

Browse Source
This commit is contained in:
Janne Valkealahti
2015-08-28 17:28:37 +01:00
parent b90382575c
commit 4845a6f6d0
5 changed files with 354 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

307
docs/src/reference/asciidoc/getting-started.adoc Normal file
View File

@@ -0,0 +1,307 @@
[[statemachine-getting-started]]
= Getting started
If you’re just getting started with Spring Statemachine,
this is the section for you! Here we answer the basic
“what?”, “how?” and “why?” questions. You’ll find a gentle
introduction to Spring Statemachine. We’ll then build our
first Spring Statemachine application, discussing some
core principles as we go.
== System Requirements
Spring Statemachine {revnumber} is built and tested with
JDK 7 and Spring Framework {spring-version} and doesn't
require any other dependencies outside of Spring Framework
within its core system.
Other optional parts like <<sm-distributed>> has dependencies to
a `Zookeeper`, while <<statemachine-examples>> has dependencies
to spring-shell and spring-boot which pulls other dependencies
beyond framework itself.
== Modules
The following modules are available for Spring Statemachine.
|===
|Module |Description
|spring-statemachine-core
|Core system of a Spring Statemachine.
|spring-statemachine-recipes-common
|Common recipes which doesn't require dependencies outside of a core
framework.
|spring-statemachine-zookeeper
|`Zookeeper` integration for a distributed state machine.
|spring-statemachine-test
|Support module for state machine testing.
|===
== Using Gradle
Here is a typical `build.gradle` file:
[source,groovy,indent=0]
----
buildscript {
repositories {
maven { url "http://repo.spring.io/libs-release" }
}
dependencies {
classpath("org.springframework.boot:spring-boot-gradle-plugin:1.2.3.RELEASE")
}
}
apply plugin: 'base'
apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'idea'
apply plugin: 'spring-boot'
version = '0.1.0'
archivesBaseName = 'gs-statemachine'
repositories {
mavenCentral()
maven { url "http://repo.spring.io/libs-release" }
maven { url "http://repo.spring.io/libs-milestone" }
maven { url "http://repo.spring.io/libs-snapshot" }
}
dependencies {
compile("org.springframework.statemachine:spring-statemachine-core:1.0.0.BUILD-SNAPSHOT")
compile("org.springframework.boot:spring-boot-starter:1.2.3.RELEASE")
testCompile("org.springframework.statemachine:spring-statemachine-test:1.0.0.BUILD-SNAPSHOT")
}
task wrapper(type: Wrapper) {
gradleVersion = '1.11'
}
----
Having a normal project structure you'd build this with command:
[source,text,indent=0]
----
# ./gradlew clean build
----
Expected Spring Boot packaged fat-jar would be `build/libs/gs-statemachine-0.1.0.jar`.
[NOTE]
====
You don't need repos `libs-milestone` and `libs-snapshot` for
production development.
====
== Using Maven
Here is a typical `pom.xml` file:
[source,xml,indent=0]
----
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.springframework</groupId>
<artifactId>gs-statemachine</artifactId>
<version>0.1.0</version>
<packaging>jar</packaging>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.2.3.RELEASE</version>
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.statemachine</groupId>
<artifactId>spring-statemachine-core</artifactId>
<version>1.0.0.BUILD-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
<version>1.0.0.BUILD-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.springframework.statemachine</groupId>
<artifactId>spring-statemachine-test</artifactId>
<version>1.0.0.BUILD-SNAPSHOT</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.3.2</version>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<plugin>
<artifactId>maven-failsafe-plugin</artifactId>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
<repositories>
<repository>
<id>spring-release</id>
<url>http://repo.spring.io/libs-release</url>
<snapshots><enabled>false</enabled></snapshots>
</repository>
<repository>
<id>spring-milestone</id>
<url>http://repo.spring.io/libs-milestone</url>
<snapshots><enabled>false</enabled></snapshots>
</repository>
<repository>
<id>spring-snapshot</id>
<url>http://repo.spring.io/libs-snapshot</url>
<snapshots><enabled>true</enabled></snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>spring-release</id>
<url>http://repo.spring.io/libs-release</url>
<snapshots><enabled>false</enabled></snapshots>
</pluginRepository>
</pluginRepositories>
</project>
----
Having a normal project structure you'd build this with command:
[source,text,indent=0]
----
# mvn clean package
----
Expected Spring Boot packaged fat-jar would be `target/gs-statemachine-0.1.0.jar`.
[NOTE]
====
You don't need repos `libs-milestone` and `libs-snapshot` for
production development.
====
== Developing your first Spring Statemachine application
Lets start by creating a simple Spring Boot `Application` class
implementing `CommandLineRunner`.
[source,java,indent=0]
----
@SpringBootApplication
public class Application implements CommandLineRunner {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
----
Add states and events:
[source,java,indent=0]
----
public static enum States {
SI, S1, S2
}
public static enum Events {
E1, E2
}
----
Add state machine configuration:
[source,java,indent=0]
----
@Configuration
@EnableStateMachine
static class StateMachineConfig
extends EnumStateMachineConfigurerAdapter<States, Events> {
@Override
public void configure(StateMachineConfigurationConfigurer<States, Events> config)
throws Exception {
config
.withConfiguration()
.autoStartup(true)
.listener(listener());
}
@Override
public void configure(StateMachineStateConfigurer<States, Events> states)
throws Exception {
states
.withStates()
.initial(States.SI)
.states(EnumSet.allOf(States.class));
}
@Override
public void configure(StateMachineTransitionConfigurer<States, Events> transitions)
throws Exception {
transitions
.withExternal()
.source(States.SI).target(States.S1).event(Events.E1)
.and()
.withExternal()
.source(States.S1).target(States.S2).event(Events.E2);
}
@Bean
public StateMachineListener<States, Events> listener() {
return new StateMachineListenerAdapter<States, Events>() {
@Override
public void stateChanged(State<States, Events> from, State<States, Events> to) {
System.out.println("State change to " + to.getId());
}
};
}
}
----
Implement `CommandLineRunner`, autowire `StateMachine`:
[source,java,indent=0]
----
@Autowired
private StateMachine<States, Events> stateMachine;
@Override
public void run(String... args) throws Exception {
stateMachine.sendEvent(Events.E1);
stateMachine.sendEvent(Events.E2);
}
----
Depending whether you build your application using `Gradle` or `Maven`
it's run `java -jar build/libs/gs-statemachine-0.1.0.jar` or
`java -jar target/gs-statemachine-0.1.0.jar` respectively.
What is expected for running this command is a normal Spring Boot output
but if you look closely you see lines:
[source,text,indent=0]
----
State change to SI
State change to S1
State change to S2
----

3
docs/src/reference/asciidoc/index.adoc
View File

@@ -15,9 +15,8 @@
include::preface.adoc[]
include::introduction.adoc[]
[[springandsm]]
include::getting-started.adoc[]
include::sm.adoc[]
include::recipes.adoc[]
include::sm-examples.adoc[]
include::faq.adoc[]

7
docs/src/reference/asciidoc/introduction.adoc
View File

@@ -19,13 +19,6 @@ and <<crashcourse>> to get a generic idea of what state machines are
mostly because rest of a documentation expects reader to be fairly
familiar with state machine concepts.
== Requirements
Spring Statemachine {revnumber} is built and tested with JDK 7 and Spring
Framework {spring-version} and doesn't require any other dependencies
outside of Spring Framework. Samples require spring-shell and
spring-boot which pulls other dependencies beyond framework
itself.
== Background
State machines are powerful because behaviour is always guaranteed to be
consistent and relatively easily debugged due to ways how operational

21
docs/src/reference/asciidoc/sm-examples.adoc
View File

@@ -8,7 +8,24 @@ configuration and what an application does with a state machine. For
complete examples go and study the samples repository.
Samples are build directly from a main source distribution during a
normal build cycle.
normal build cycle. Samples in this chapter are:
<<statemachine-examples-turnstile>> Turnstile.
<<statemachine-examples-showcase>> Showcase.
<<statemachine-examples-cdplayer>> CD Player.
<<statemachine-examples-tasks>> Tasks.
<<statemachine-examples-washer>> Washer.
<<statemachine-examples-persist>> Persist.
<<statemachine-examples-zookeeper>> Zookeeper.
<<statemachine-examples-web>> Web.
[source,text]
----
@@ -204,6 +221,7 @@ What happens in above sample:
match to its dummy transition without guard or action, not never
happens.
[[statemachine-examples-cdplayer]]
== CD Player
CD Player is a sample which resembles better use case of most of use have
used in a real world. CD Player itself is a really simple entity where
@@ -627,6 +645,7 @@ In above if we simulate failure for either task T2 or T3, state
machine goes to MANUAL state where problem needs to be fixed manually
before we're able to go back to READY state.
[[statemachine-examples-washer]]
== Washer
Washer is a sample demonstrating a use of a history state to recover a

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

@@ -1,18 +1,38 @@
[[statemachine]]
= Spring and Statemachine
= Using Spring Statemachine
This part of the reference documentation explains the core functionality
that Spring Statemachine provides to any Spring based application.
<<sm-config>> describes the generic configuration support.
<<sm-config>> the generic configuration support.
<<sm-factories>> describes the generic state machine factory support.
<<sm-factories>> the generic state machine factory support.
<<sm-triggers>> describes the use of triggers.
<<sm-actions>> the actions support.
<<sm-listeners>> describes the use of state machine listeners.
<<sm-guards>> the guard support.
<<sm-context>> describes the generic Spring application context support.
<<sm-extendedstate>> the extended state support.
<<sm-statecontext>> the state context support.
<<sm-triggers>> the use of triggers.
<<sm-listeners>> the use of state machine listeners.
<<sm-context>> the generic Spring application context support.
<<sm-accessor>> the state machine internal accessor support.
<<sm-interceptor>> the state machine error handling support.
<<sm-error-handling>> the state machine interceptor support.
<<sm-persist>> the state machine persisting support.
<<sm-distributed>> the distributed state machine support.
<<sm-test>> the state machine testing support.
[[sm-config]]
== Statemachine Configuration