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

Updates to docs

Browse Source
This commit is contained in:
Janne Valkealahti
2015-03-06 15:01:23 +00:00
parent de848cda20
commit ed81b1b578
24 changed files with 673 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
docs/src/reference/asciidoc/appendix.adoc
View File

@@ -12,12 +12,12 @@ material in this reference documentation.
[source,java,indent=0]
----
include::samples/MyStates.java[tags=snippetA]
include::samples/States.java[tags=snippetA]
----
[source,java,indent=0]
----
include::samples/MyEvents.java[tags=snippetA]
include::samples/Events.java[tags=snippetA]
----
[appendix]
@@ -28,55 +28,56 @@ This appendix provides generic information about state machines.
[glossary]
=== Glossary
State Machine::
*State Machine*::
Main entity driving a collection of states together with regions,
transitions and events.
State::
*State*::
A state models a situation during which some invariant condition
holds. State is the main entity of a state machine where state changes
are driven by an events.
Transition::
*Transition*::
A transition is a relationship between a source state and a target
state. It may be part of a compound transition, which takes the state
machine from one state configuration to another, representing the complete
response of the state machine to an occurrence of an event of a
particular type.
Event::
*Event*::
An entity which is send to a state machine which then drives a various
state changes.
Initial State::
*Initial State*::
A special state in which the state machine starts. Initial state is
always bound to a particulal state machine or a region. A state
machine with a multiple regions may have a multiple initial states.
End State::
*End State*::
Also called as a final state is a special kind of state signifying
that the enclosing region is completed. If the enclosing region is
directly contained in a state machine and all other regions in the
state machine also are completed, then it means that the entire state
machine is completed.
Region::
*Region*::
A region is an orthogonal part of either a composite state or a state
machine. It contains states and transitions.
Guard::
*Guard*::
Is a boolean expression evaluated dynamically based on the value of
extended state variables and event parameters. Guard conditions affect
the behavior of a state machine by enabling actions or transitions
only when they evaluate to TRUE and disabling them when they evaluate
to FALSE.
Action::
*Action*::
A action is a behaviour executed during the triggering of the
transition.
=== A State Machines Crash Course
TBD.
This appendix provides generic crash course to a state machine
concepts.
==== States
TBD.

BIN
docs/src/reference/asciidoc/images/statechart1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.3 KiB

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

@@ -1,6 +1,9 @@
[[introduction]]
= Introduction
Spring State Machine(SSM) is a framework for application developers to
use state machine concepts with Spring.
== Requirements
Spring Statemachine {revnumber} is built and tested with JDK 7, Spring

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

@@ -1,8 +1,5 @@
[preface]
== Preface
Spring State Machine(SSM) is a framework for application developers to use
state machine concepts with Spring.
Concept of a state machine is most likely older that any of a reader
of this reference documentation and definitely older than a Java
language itself. Description of finite automate dates back to 1943

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

@@ -1,10 +1,77 @@
[[statemachine-examples]]
= Statemachine Examples
= State Machine Examples
This part of the reference documentation explains the use of state
machines as sample code together with a uml state charts.
machines as sample code together with a uml state charts. We do few
shortcuts when representing relationship between a state chart, SSM
configuration and what an application does with a state machine. For
complete examples go and study the samples repository.
== Simple Statemachine
== Turnstile
TBD
Turnstile is a simple device which gives you an access if payment is
made and is a very simple to model using a state machine. In its
simples form there are only two states, `LOCKED` and `UNLOCKED`. Two
events, `COIN` and `PUSH` can happen if you try to go through it or
you make a payment.
image::images/statechart1.png[]
.States
[source,java,indent=0]
----
include::samples/demo/turnstile/Application.java[tags=snippetB]
----
.Events
[source,java,indent=0]
----
include::samples/demo/turnstile/Application.java[tags=snippetC]
----
.Configuration
[source,java,indent=0]
----
include::samples/demo/turnstile/Application.java[tags=snippetA]
----
You can see how this sample state machine interacts with event by
running `turnstile` sample.
[source,text]
----
$ java -jar spring-statemachine-samples-turnstile-1.0.0.BUILD-SNAPSHOT.jar
sm>sm print
+----------------------------------------------------------------+
| SM |
+----------------------------------------------------------------+
| |
| +----------------+ +----------------+ |
| *-->| LOCKED | | UNLOCKED | |
| +----------------+ +----------------+ |
| +---| entry/ | | entry/ |---+ |
| | | exit/ | | exit/ | | |
| | | | | | | |
| PUSH| | |---COIN-->| | |COIN |
| | | | | | | |
| | | | | | | |
| | | |<--PUSH---| | | |
| +-->| | | |<--+ |
| | | | | |
| +----------------+ +----------------+ |
| |
+----------------------------------------------------------------+
sm>sm start
State changed to LOCKED
State machine started
sm>sm event COIN
State changed to UNLOCKED
Event COIN send
sm>sm event PUSH
State changed to LOCKED
Event PUSH send
----

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

@@ -6,24 +6,93 @@ that Spring Statemachine provides to any Spring based application.
<<sm-config>> describes the generic configuration support.
<<sm-factories>> describes the generic state machine factory support.
<<sm-listeners>> describes the generic state machine listener support.
<<sm-context>> describes the generic Spring application context support.
[[sm-config]]
== Statemachine Configuration
One of the common tasks when using a Statemachine is to design its
runtime configuration. This chapter will focus on How Spring
runtime configuration. This chapter will focus on how Spring
Statemachine is configured and how it leverages Spring's lightweight
IoC containers to simplify the application internals to make it more
manageable.
=== Using the Spring Statemachine JavaConfig
=== Configuring States
We'll get into more complex configuration examples a bit later but
lets first start with a something simple. For most simple state
machine you
[source,java,indent=0]
----
include::samples/DocsConfigurationSampleTests.java[tags=snippetA]
----
=== Configuring Hierarchical States
== Context Ingregration
[source,java,indent=0]
----
include::samples/DocsConfigurationSampleTests.java[tags=snippetB]
----
=== Configuring Transitions
[source,java,indent=0]
----
include::samples/DocsConfigurationSampleTests.java[tags=snippetC]
----
=== Configuring Guards
[source,java,indent=0]
----
include::samples/DocsConfigurationSampleTests.java[tags=snippetD]
----
=== Configuring Actions
[source,java,indent=0]
----
include::samples/DocsConfigurationSampleTests.java[tags=snippetE]
----
[[sm-factories]]
== State Machine Factories
There are use cases when state machine needs to be created dynamically
instead of defining static configuration at compile time. For example
if there are custom components which are using its own state machines
and these components are created dynamically it is impossible to have
a static state machined build during the application start. Internally
state machines are always build via a factory interfaces and this then
gives user an option to use this feature programmatically.
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.
[source,java,indent=0]
----
include::samples/DocsConfigurationSampleTests.java[tags=snippetF]
----
=== Factory Limitations
xxx
[[sm-listeners]]
== State Machine Listeners
There are use cases where you just want to know what is happening with
a state machine, react to something or simply get logging for
debugging purposes. SSM provides interfaces for adding listeners which
then gives an option to get callback when various state changes,
actions, etc are happening.
[[sm-context]]
== Context Integration
TBD
@@ -31,3 +100,9 @@ TBD
TBD
=== Context Events
[source,java,indent=0]
----
include::samples/DocsConfigurationSampleTests.java[tags=snippetG]
----

19
docs/src/statecharts/statechart1.txt Normal file
View File

@@ -0,0 +1,19 @@
+----------------------------------------------------------------+
| SM |
+----------------------------------------------------------------+
| |
| +----------------+ +----------------+ |
| *-->| LOCKED | | UNLOCKED | |
| +----------------+ +----------------+ |
| +---| entry/ | | entry/ |---+ |
| | | exit/ | | exit/ | | |
| | | | | | | |
| PUSH| | |---COIN-->| | |COIN |
| | | | | | | |
| | | | | | | |
| | | |<--PUSH---| | | |
| +-->| | | |<--+ |
| | | | | |
| +----------------+ +----------------+ |
| |
+----------------------------------------------------------------+