diff --git a/build.gradle b/build.gradle index e9b55cbe..143b1383 100644 --- a/build.gradle +++ b/build.gradle @@ -149,7 +149,15 @@ configure(rootProject) { dependencies { // for integration tests } - + + task copyDocsSamples(type: Copy) { + from 'spring-statemachine-core/src/test/java/org/springframework/statemachine/docs' + include '*.java' + into 'docs/src/reference/asciidoc/samples' + } + + asciidoctor.dependsOn copyDocsSamples + task api(type: Javadoc) { group = 'Documentation' description = 'Generates aggregated Javadoc API documentation.' diff --git a/docs/src/reference/asciidoc/appendix.adoc b/docs/src/reference/asciidoc/appendix.adoc index aefe0aeb..c269bea6 100644 --- a/docs/src/reference/asciidoc/appendix.adoc +++ b/docs/src/reference/asciidoc/appendix.adoc @@ -3,14 +3,99 @@ :numbered!: +[appendix] +== Support Content +This appendix provides generic information about used classes and +material in this reference documentation. + +=== Classes Used in This Document + +[source,java,indent=0] +---- +include::samples/MyStates.java[tags=snippetA] +---- + +[source,java,indent=0] +---- +include::samples/MyEvents.java[tags=snippetA] +---- + [appendix] == State Machine Concepts This appendix provides generic information about state machines. + +[glossary] === Glossary -state machine:: -machine of sort. +State Machine:: +Main entity driving a collection of states together with regions, +transitions and events. + +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:: +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:: +An entity which is send to a state machine which then drives a various +state changes. + +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:: +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:: +A region is an orthogonal part of either a composite state or a state +machine. It contains states and transitions. + +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:: +A action is a behaviour executed during the triggering of the +transition. + +=== A State Machines Crash Course +TBD. + +==== States +TBD. + +==== Guard Conditions +TBD. + +==== Events +TBD. + +==== Transitions +TBD. + +==== Actions +TBD. + +==== Hierarchical State Machines +TBD. + +==== Regions +TBD. -state:: -a stage in a state machine. diff --git a/docs/src/reference/asciidoc/index.adoc b/docs/src/reference/asciidoc/index.adoc index 3dc1ac1a..60400118 100644 --- a/docs/src/reference/asciidoc/index.adoc +++ b/docs/src/reference/asciidoc/index.adoc @@ -32,6 +32,8 @@ include::preface.adoc[] include::introduction.adoc[] -[[springandhadoop]] +[[springandsm]] include::sm.adoc[] + +include::sm-examples.adoc[] include::appendix.adoc[] diff --git a/docs/src/reference/asciidoc/introduction.adoc b/docs/src/reference/asciidoc/introduction.adoc index c6129e8e..25b1fce2 100644 --- a/docs/src/reference/asciidoc/introduction.adoc +++ b/docs/src/reference/asciidoc/introduction.adoc @@ -2,4 +2,6 @@ = Introduction == Requirements -TBD + +Spring Statemachine {revnumber} is built and tested with JDK 7, Spring +Framework {spring-version}. diff --git a/docs/src/reference/asciidoc/preface.adoc b/docs/src/reference/asciidoc/preface.adoc index c2e716ca..86c36454 100644 --- a/docs/src/reference/asciidoc/preface.adoc +++ b/docs/src/reference/asciidoc/preface.adoc @@ -1,4 +1,31 @@ [preface] == Preface -Spring Statemachine is a framework for application developers to use +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 +when gentlements Warren McCulloch and Walter Pitts wrote a paper about +it. Later George H. Mealy presented a state machine concept in 1955 +which is known as a Mealy Machine. A year later in 1956 Edward F. +Moore presented another paper which is known as a Moore Machine. If +you're ever read anything about state machines, names Mealy and Moore +should have popped up at some point. + +Traditionally state machines are added to a existing project when +developer realizes that code base is starting to look like a plate +full of spaghetti. Spaghetti code looks like never ending hierarchical +structure of IFs, ELSEs and BREAK clauses and probably compiler should +ask developer to go home when things are starting to look too complex. + +This reference documentations contains following parts. + +<> introduction to this reference documentation + +<> describes the usage of Spring State Machine(SSM) + +<> more detailed state machine samples + +<> generic info about used material and state machines + diff --git a/docs/src/reference/asciidoc/samples/.gitignore b/docs/src/reference/asciidoc/samples/.gitignore new file mode 100644 index 00000000..6bf63602 --- /dev/null +++ b/docs/src/reference/asciidoc/samples/.gitignore @@ -0,0 +1,2 @@ +*.java + diff --git a/docs/src/reference/asciidoc/sm-examples.adoc b/docs/src/reference/asciidoc/sm-examples.adoc new file mode 100644 index 00000000..829c0cfc --- /dev/null +++ b/docs/src/reference/asciidoc/sm-examples.adoc @@ -0,0 +1,10 @@ +[[statemachine-examples]] += Statemachine Examples + +This part of the reference documentation explains the use of state +machines as sample code together with a uml state charts. + +== Simple Statemachine + +TBD + diff --git a/docs/src/reference/asciidoc/sm.adoc b/docs/src/reference/asciidoc/sm.adoc index 8c282753..c9bb9522 100644 --- a/docs/src/reference/asciidoc/sm.adoc +++ b/docs/src/reference/asciidoc/sm.adoc @@ -1,5 +1,33 @@ [[statemachine]] -= State Machine += Spring and Statemachine + +This part of the reference documentation explains the core functionality +that Spring Statemachine provides to any Spring based application. + +<> describes the generic configuration 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 +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 + +[source,java,indent=0] +---- +include::samples/DocsConfigurationSampleTests.java[tags=snippetA] +---- + + +== Context Ingregration + TBD +=== Annotation Support + +TBD 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 new file mode 100644 index 00000000..ca043315 --- /dev/null +++ b/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsConfigurationSampleTests.java @@ -0,0 +1,51 @@ +/* + * Copyright 2015 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.springframework.statemachine.docs; + +import java.util.EnumSet; + +import org.springframework.context.annotation.Configuration; +import org.springframework.statemachine.AbstractStateMachineTests; +import org.springframework.statemachine.config.EnableStateMachine; +import org.springframework.statemachine.config.EnumStateMachineConfigurerAdapter; +import org.springframework.statemachine.config.builders.StateMachineStateConfigurer; + +/** + * Tests for state machine configuration. + * + * @author Janne Valkealahti + * + */ +public class DocsConfigurationSampleTests extends AbstractStateMachineTests { + +// tag::snippetA[] + @Configuration + @EnableStateMachine + public static class Config1 extends EnumStateMachineConfigurerAdapter { + + @Override + public void configure(StateMachineStateConfigurer states) throws Exception { + states + .withStates() + .initial(MyStates.S1) + .end(MyStates.SF) + .states(EnumSet.allOf(MyStates.class)); + } + + } +// end::snippetA[] + +} diff --git a/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/MyEvents.java b/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/MyEvents.java new file mode 100644 index 00000000..332e5a3f --- /dev/null +++ b/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/MyEvents.java @@ -0,0 +1,7 @@ +package org.springframework.statemachine.docs; + +//tag::snippetA[] +public enum MyEvents { + E1,E2,E3,E4,EF +} +//end::snippetA[] diff --git a/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/MyStates.java b/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/MyStates.java new file mode 100644 index 00000000..f2b6bae1 --- /dev/null +++ b/spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/MyStates.java @@ -0,0 +1,7 @@ +package org.springframework.statemachine.docs; + +//tag::snippetA[] +public enum MyStates { + SI,S1,S2,S3,S4,SF +} +//end::snippetA[]