Update docs

- Relates to #194
This commit is contained in:
Janne Valkealahti
2016-04-10 15:53:42 +01:00
parent cb7005b445
commit b5da16ac82
11 changed files with 334 additions and 1 deletions

View File

@@ -344,6 +344,8 @@ configure(rootProject) {
from 'spring-statemachine-test/src/test/java/org/springframework/statemachine/test/docs'
from 'spring-statemachine-recipes/src/test/java/org/springframework/statemachine/recipes/docs'
from 'spring-statemachine-zookeeper/src/test/java/org/springframework/statemachine/zookeeper/docs'
from 'spring-statemachine-uml/src/test/java/org/springframework/statemachine/uml/docs'
from 'spring-statemachine-uml/src/test/resources/org/springframework/statemachine/uml/docs'
from 'spring-statemachine-samples/src/main/java/'
from 'spring-statemachine-samples/washer/src/main/java/'
from 'spring-statemachine-samples/tasks/src/main/java/'
@@ -355,6 +357,7 @@ configure(rootProject) {
from 'spring-statemachine-samples/security/src/main/java/'
from 'spring-statemachine-samples/eventservice/src/main/java/'
include '**/*.java'
include '**/*.uml'
into 'docs/src/reference/asciidoc/samples'
}

View File

@@ -42,6 +42,12 @@ framework.
|spring-statemachine-test
|Support module for state machine testing.
|spring-statemachine-cluster
|Support module for Spring Cloud Cluster.
|spring-statemachine-uml
|Support module for UI uml modeling.
|===
== Using Gradle

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.2 KiB

View File

@@ -0,0 +1,16 @@
<?xml version="1.0" encoding="UTF-8"?>
<uml:Model xmi:version="20131001" xmlns:xmi="http://www.omg.org/spec/XMI/20131001" xmlns:uml="http://www.eclipse.org/uml2/5.0.0/UML" xmi:id="_AMP3IP8fEeW45bORGB4c_A" name="RootElement">
<packagedElement xmi:type="uml:StateMachine" xmi:id="_AMRFQP8fEeW45bORGB4c_A" name="StateMachine">
<region xmi:type="uml:Region" xmi:id="_AMRsUP8fEeW45bORGB4c_A" name="Region1">
<transition xmi:type="uml:Transition" xmi:id="_chgcgP8fEeW45bORGB4c_A" source="_EZrg4P8fEeW45bORGB4c_A" target="_FAvg4P8fEeW45bORGB4c_A">
<trigger xmi:type="uml:Trigger" xmi:id="_hs5jUP8fEeW45bORGB4c_A" event="_NeH84P8fEeW45bORGB4c_A"/>
</transition>
<transition xmi:type="uml:Transition" xmi:id="_egLIoP8fEeW45bORGB4c_A" source="_Fg0IEP8fEeW45bORGB4c_A" target="_EZrg4P8fEeW45bORGB4c_A"/>
<subvertex xmi:type="uml:State" xmi:id="_EZrg4P8fEeW45bORGB4c_A" name="S1"/>
<subvertex xmi:type="uml:State" xmi:id="_FAvg4P8fEeW45bORGB4c_A" name="S2"/>
<subvertex xmi:type="uml:Pseudostate" xmi:id="_Fg0IEP8fEeW45bORGB4c_A"/>
</region>
</packagedElement>
<packagedElement xmi:type="uml:Signal" xmi:id="_L01D0P8fEeW45bORGB4c_A" name="E1"/>
<packagedElement xmi:type="uml:SignalEvent" xmi:id="_NeH84P8fEeW45bORGB4c_A" name="SignalEventE1" signal="_L01D0P8fEeW45bORGB4c_A"/>
</uml:Model>

View File

@@ -346,6 +346,38 @@ include::samples/DocsConfigurationSampleTests.java[tags=snippetYC]
More about config model, refer to section <<devdocs-configmodel>>.
=== Configuring Model
`StateMachineModelFactory` is a hook to configure statemachine model
without using a manual configuration. Essentially it is a thirt party
integration to integrate into a configuration model.
`StateMachineModelFactory` can be hooked into a configuration model by
using a `StateMachineModelConfigurer` as shown above.
[source,java,indent=0]
----
include::samples/DocsConfigurationSampleTests8.java[tags=snippetA]
----
As a custom example `CustomStateMachineModelFactory` would simply
define two states, _S1_ and _S2_ and an event _E1_ between those
states.
[source,java,indent=0]
----
include::samples/DocsConfigurationSampleTests8.java[tags=snippetB]
----
[NOTE]
====
Defining a custom model is usually not what end user is looking for,
although it is possible, however it is a central concept of allowing
external access to this configuration model.
====
Example of using this model factory integration can be found from
<<sm-papyrus>>. More generic info about custom model integration can
be found from <<devdocs>>.
[[statemachine-config-thingstoremember]]
=== Things to Remember
@@ -1672,3 +1704,39 @@ event is sent to particular, random or all machines.
All possible options for expected are documented in javadocs
{sm-statemachinetestplanbuilder-statemachinetestplanstepbuilder}[_StateMachineTestPlanStepBuilder_].
====
[[sm-papyrus]]
== Eclipse Modeling Support
Defining a state machine configuration with UI modeling is supported
via Eclipse Papyrus framework.
From eclipse wizard create a new _Papyrus Model_ with `UML` _Diagram
Language_. In this example it's named as `simple-machine`. Then you've
given an option to choose various diagram kind's and a `StateMachine
Diagram` mush be chooce.
We want to create a machine having two states, `S1` and `S2` where
`S1` is initial state. Then event `E1` is created to do a transition
from `S1` to `S2`. In papyrus a machine would then look like something
shown below.
image::images/simple-machine.png[width=500]
Behind a scenes a raw uml file would look like.
[source,xml,indent=0]
----
include::samples/simple-machine.uml[]
----
After uml file is in place in your project, it can be imported into
configuration using `StateMachineModelConfigurer` where
`StateMachineModelFactory` is associated with a model.
`UmlStateMachineModelFactory` is a special factory which knows howto
process eclipse's uml structure.
[source,java,indent=0]
----
include::samples/DocsUmlSampleTests1.java[tags=snippetA]
----

View File

@@ -17,5 +17,6 @@ interoperability with web applications.
* Configuration model classes are now a public API.
* New features in timer based events.
* Configuration model verifier.
* New samples, <<statemachine-examples-security>>, <<statemachine-examples-eventservice>>
* New samples, <<statemachine-examples-security>>, <<statemachine-examples-eventservice>>.
* UI modeling support using Eclipse Papyrus, <<sm-papyrus>>.

View File

@@ -0,0 +1,75 @@
/*
* Copyright 2016 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.ArrayList;
import java.util.Collection;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.statemachine.config.EnableStateMachine;
import org.springframework.statemachine.config.StateMachineConfigurerAdapter;
import org.springframework.statemachine.config.builders.StateMachineModelConfigurer;
import org.springframework.statemachine.config.model.ConfigurationData;
import org.springframework.statemachine.config.model.DefaultStateMachineModel;
import org.springframework.statemachine.config.model.StateData;
import org.springframework.statemachine.config.model.StateMachineModel;
import org.springframework.statemachine.config.model.StateMachineModelFactory;
import org.springframework.statemachine.config.model.StatesData;
import org.springframework.statemachine.config.model.TransitionData;
import org.springframework.statemachine.config.model.TransitionsData;
public class DocsConfigurationSampleTests8 {
// tag::snippetA[]
@Configuration
@EnableStateMachine
public static class Config1 extends StateMachineConfigurerAdapter<String, String> {
@Override
public void configure(StateMachineModelConfigurer<String, String> model) throws Exception {
model
.withModel()
.factory(modelFactory());
}
@Bean
public StateMachineModelFactory<String, String> modelFactory() {
return new CustomStateMachineModelFactory();
}
}
// end::snippetA[]
// tag::snippetB[]
public static class CustomStateMachineModelFactory implements StateMachineModelFactory<String, String> {
@Override
public StateMachineModel<String, String> build() {
ConfigurationData<String, String> configurationData = new ConfigurationData<>();
Collection<StateData<String, String>> stateData = new ArrayList<>();
stateData.add(new StateData<String, String>("S1", true));
stateData.add(new StateData<String, String>("S2"));
StatesData<String, String> statesData = new StatesData<>(stateData);
Collection<TransitionData<String, String>> transitionData = new ArrayList<>();
transitionData.add(new TransitionData<String, String>("S1", "S2", "E1"));
TransitionsData<String, String> transitionsData = new TransitionsData<>(transitionData);
StateMachineModel<String, String> stateMachineModel = new DefaultStateMachineModel<String, String>(configurationData,
statesData, transitionsData);
return stateMachineModel;
}
}
// end::snippetB[]
}

View File

@@ -0,0 +1,49 @@
/*
* Copyright 2016 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.uml.docs;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;
import org.springframework.core.io.Resource;
import org.springframework.statemachine.config.EnableStateMachine;
import org.springframework.statemachine.config.StateMachineConfigurerAdapter;
import org.springframework.statemachine.config.builders.StateMachineModelConfigurer;
import org.springframework.statemachine.config.model.StateMachineModelFactory;
import org.springframework.statemachine.uml.UmlStateMachineModelFactory;
public class DocsUmlSampleTests1 {
// tag::snippetA[]
@Configuration
@EnableStateMachine
public static class Config1 extends StateMachineConfigurerAdapter<String, String> {
@Override
public void configure(StateMachineModelConfigurer<String, String> model) throws Exception {
model
.withModel()
.factory(modelFactory());
}
@Bean
public StateMachineModelFactory<String, String> modelFactory() {
Resource model = new ClassPathResource("org/springframework/statemachine/uml/docs/simple-machine.uml");
return new UmlStateMachineModelFactory(model);
}
}
// end::snippetA[]
}

View File

@@ -0,0 +1,2 @@
<?xml version="1.0" encoding="UTF-8"?>
<xmi:XMI xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI"/>

View File

@@ -0,0 +1,97 @@
<?xml version="1.0" encoding="UTF-8"?>
<notation:Diagram xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:ecore="http://www.eclipse.org/emf/2002/Ecore" xmlns:notation="http://www.eclipse.org/gmf/runtime/1.0.2/notation" xmlns:style="http://www.eclipse.org/papyrus/infra/viewpoints/policy/style" xmlns:uml="http://www.eclipse.org/uml2/5.0.0/UML" xmi:id="_AMSTYP8fEeW45bORGB4c_A" type="PapyrusUMLStateMachineDiagram" name="StateMachine Diagram" measurementUnit="Pixel">
<children xmi:type="notation:Shape" xmi:id="_AMSTYf8fEeW45bORGB4c_A" type="2000">
<children xmi:type="notation:DecorationNode" xmi:id="_AMSTYv8fEeW45bORGB4c_A" type="2001">
<layoutConstraint xmi:type="notation:Bounds" xmi:id="_AMSTY_8fEeW45bORGB4c_A" width="651" height="23"/>
</children>
<children xmi:type="notation:DecorationNode" xmi:id="_AMSTZP8fEeW45bORGB4c_A" type="2002">
<children xmi:type="notation:Shape" xmi:id="_AMSTZf8fEeW45bORGB4c_A" type="3000">
<eAnnotations xmi:type="ecore:EAnnotation" xmi:id="_AMSTZv8fEeW45bORGB4c_A" source="RegionAnnotationKey">
<details xmi:type="ecore:EStringToStringMapEntry" xmi:id="_AMSTZ_8fEeW45bORGB4c_A" key="RegionZoneKey" value=""/>
</eAnnotations>
<children xmi:type="notation:DecorationNode" xmi:id="_AMSTaP8fEeW45bORGB4c_A" type="3002">
<children xmi:type="notation:Shape" xmi:id="_EZt9IP8fEeW45bORGB4c_A" type="6000">
<children xmi:type="notation:DecorationNode" xmi:id="_EZt9Iv8fEeW45bORGB4c_A" type="6001">
<layoutConstraint xmi:type="notation:Bounds" xmi:id="_I9ecMP8fEeW45bORGB4c_A" width="101"/>
</children>
<children xmi:type="notation:DecorationNode" xmi:id="_EZt9I_8fEeW45bORGB4c_A" type="19003">
<layoutConstraint xmi:type="notation:Location" xmi:id="_EZt9JP8fEeW45bORGB4c_A" x="40"/>
</children>
<children xmi:type="notation:DecorationNode" xmi:id="_EZt9Jf8fEeW45bORGB4c_A" type="6002">
<layoutConstraint xmi:type="notation:Bounds" xmi:id="_EZt9Jv8fEeW45bORGB4c_A" y="-1" width="101"/>
</children>
<element xmi:type="uml:State" href="simple-machine.uml#_EZrg4P8fEeW45bORGB4c_A"/>
<layoutConstraint xmi:type="notation:Bounds" xmi:id="_EZt9If8fEeW45bORGB4c_A" x="170" y="47" width="101" height="61"/>
</children>
<children xmi:type="notation:Shape" xmi:id="_FAx9IP8fEeW45bORGB4c_A" type="6000">
<children xmi:type="notation:DecorationNode" xmi:id="_FAykMP8fEeW45bORGB4c_A" type="6001">
<layoutConstraint xmi:type="notation:Bounds" xmi:id="_JrhN8P8fEeW45bORGB4c_A" width="101"/>
</children>
<children xmi:type="notation:DecorationNode" xmi:id="_FAykMf8fEeW45bORGB4c_A" type="19003">
<layoutConstraint xmi:type="notation:Location" xmi:id="_FAykMv8fEeW45bORGB4c_A" x="40"/>
</children>
<children xmi:type="notation:DecorationNode" xmi:id="_FAykM_8fEeW45bORGB4c_A" type="6002">
<layoutConstraint xmi:type="notation:Bounds" xmi:id="_FAykNP8fEeW45bORGB4c_A" y="-1" width="101"/>
</children>
<element xmi:type="uml:State" href="simple-machine.uml#_FAvg4P8fEeW45bORGB4c_A"/>
<layoutConstraint xmi:type="notation:Bounds" xmi:id="_FAx9If8fEeW45bORGB4c_A" x="450" y="47" width="101" height="61"/>
</children>
<children xmi:type="notation:Shape" xmi:id="_Fg3LYP8fEeW45bORGB4c_A" type="8000">
<children xmi:type="notation:DecorationNode" xmi:id="_Fg3LYv8fEeW45bORGB4c_A" type="8001">
<layoutConstraint xmi:type="notation:Location" xmi:id="_Fg3LY_8fEeW45bORGB4c_A" x="25" y="3"/>
</children>
<children xmi:type="notation:DecorationNode" xmi:id="_Fg3LZP8fEeW45bORGB4c_A" type="8002">
<layoutConstraint xmi:type="notation:Location" xmi:id="_Fg3ycP8fEeW45bORGB4c_A" x="25" y="-10"/>
</children>
<element xmi:type="uml:Pseudostate" href="simple-machine.uml#_Fg0IEP8fEeW45bORGB4c_A"/>
<layoutConstraint xmi:type="notation:Bounds" xmi:id="_Fg3LYf8fEeW45bORGB4c_A" x="63" y="61"/>
</children>
<layoutConstraint xmi:type="notation:Bounds" xmi:id="_AMSTaf8fEeW45bORGB4c_A"/>
</children>
<element xmi:type="uml:Region" href="simple-machine.uml#_AMRsUP8fEeW45bORGB4c_A"/>
<layoutConstraint xmi:type="notation:Bounds" xmi:id="_AMSTav8fEeW45bORGB4c_A" width="651" height="168"/>
</children>
<layoutConstraint xmi:type="notation:Bounds" xmi:id="_AMSTa_8fEeW45bORGB4c_A" y="23" width="651" height="168"/>
</children>
<element xmi:type="uml:StateMachine" href="simple-machine.uml#_AMRFQP8fEeW45bORGB4c_A"/>
<layoutConstraint xmi:type="notation:Bounds" xmi:id="_AMSTbP8fEeW45bORGB4c_A" x="30" y="30" width="651" height="191"/>
</children>
<styles xmi:type="notation:StringValueStyle" xmi:id="_AMSTbf8fEeW45bORGB4c_A" name="diagram_compatibility_version" stringValue="1.1.0"/>
<styles xmi:type="notation:DiagramStyle" xmi:id="_AMSTbv8fEeW45bORGB4c_A"/>
<styles xmi:type="style:PapyrusViewStyle" xmi:id="_AMSTb_8fEeW45bORGB4c_A">
<owner xmi:type="uml:Model" href="simple-machine.uml#_AMP3IP8fEeW45bORGB4c_A"/>
</styles>
<element xmi:type="uml:StateMachine" href="simple-machine.uml#_AMRFQP8fEeW45bORGB4c_A"/>
<edges xmi:type="notation:Connector" xmi:id="_chnKMP8fEeW45bORGB4c_A" type="7000" source="_EZt9IP8fEeW45bORGB4c_A" target="_FAx9IP8fEeW45bORGB4c_A">
<children xmi:type="notation:DecorationNode" xmi:id="_chnKM_8fEeW45bORGB4c_A" type="7001">
<layoutConstraint xmi:type="notation:Location" xmi:id="_chnKNP8fEeW45bORGB4c_A"/>
</children>
<children xmi:type="notation:DecorationNode" xmi:id="_chnKNf8fEeW45bORGB4c_A" type="7002">
<layoutConstraint xmi:type="notation:Location" xmi:id="_chnKNv8fEeW45bORGB4c_A" x="-2" y="-15"/>
</children>
<children xmi:type="notation:DecorationNode" xmi:id="_chnKN_8fEeW45bORGB4c_A" type="7003">
<layoutConstraint xmi:type="notation:Location" xmi:id="_chnKOP8fEeW45bORGB4c_A" y="60"/>
</children>
<styles xmi:type="notation:FontStyle" xmi:id="_chnKMf8fEeW45bORGB4c_A"/>
<element xmi:type="uml:Transition" href="simple-machine.uml#_chgcgP8fEeW45bORGB4c_A"/>
<bendpoints xmi:type="notation:RelativeBendpoints" xmi:id="_chnKMv8fEeW45bORGB4c_A" points="[15, -1, -200, 1]$[194, -7, -21, -5]"/>
<sourceAnchor xmi:type="notation:IdentityAnchor" xmi:id="_ch3o4P8fEeW45bORGB4c_A" id="(1.0,0.4098360655737705)"/>
<targetAnchor xmi:type="notation:IdentityAnchor" xmi:id="_ch3o4f8fEeW45bORGB4c_A" id="(0.0,0.39344262295081966)"/>
</edges>
<edges xmi:type="notation:Connector" xmi:id="_egRPQP8fEeW45bORGB4c_A" type="7000" source="_Fg3LYP8fEeW45bORGB4c_A" target="_EZt9IP8fEeW45bORGB4c_A">
<children xmi:type="notation:DecorationNode" xmi:id="_egR2UP8fEeW45bORGB4c_A" type="7001">
<layoutConstraint xmi:type="notation:Location" xmi:id="_egR2Uf8fEeW45bORGB4c_A"/>
</children>
<children xmi:type="notation:DecorationNode" xmi:id="_egR2Uv8fEeW45bORGB4c_A" type="7002">
<layoutConstraint xmi:type="notation:Location" xmi:id="_egR2U_8fEeW45bORGB4c_A"/>
</children>
<children xmi:type="notation:DecorationNode" xmi:id="_egR2VP8fEeW45bORGB4c_A" type="7003">
<layoutConstraint xmi:type="notation:Location" xmi:id="_egR2Vf8fEeW45bORGB4c_A" y="60"/>
</children>
<styles xmi:type="notation:FontStyle" xmi:id="_egRPQf8fEeW45bORGB4c_A"/>
<element xmi:type="uml:Transition" href="simple-machine.uml#_egLIoP8fEeW45bORGB4c_A"/>
<bendpoints xmi:type="notation:RelativeBendpoints" xmi:id="_egRPQv8fEeW45bORGB4c_A" points="[8, 1, -103, 0]$[97, -2, -14, -3]"/>
<sourceAnchor xmi:type="notation:IdentityAnchor" xmi:id="_eght8P8fEeW45bORGB4c_A" id="(1.0,0.4)"/>
<targetAnchor xmi:type="notation:IdentityAnchor" xmi:id="_eght8f8fEeW45bORGB4c_A" id="(0.0,0.39344262295081966)"/>
</edges>
</notation:Diagram>

View File

@@ -0,0 +1,16 @@
<?xml version="1.0" encoding="UTF-8"?>
<uml:Model xmi:version="20131001" xmlns:xmi="http://www.omg.org/spec/XMI/20131001" xmlns:uml="http://www.eclipse.org/uml2/5.0.0/UML" xmi:id="_AMP3IP8fEeW45bORGB4c_A" name="RootElement">
<packagedElement xmi:type="uml:StateMachine" xmi:id="_AMRFQP8fEeW45bORGB4c_A" name="StateMachine">
<region xmi:type="uml:Region" xmi:id="_AMRsUP8fEeW45bORGB4c_A" name="Region1">
<transition xmi:type="uml:Transition" xmi:id="_chgcgP8fEeW45bORGB4c_A" source="_EZrg4P8fEeW45bORGB4c_A" target="_FAvg4P8fEeW45bORGB4c_A">
<trigger xmi:type="uml:Trigger" xmi:id="_hs5jUP8fEeW45bORGB4c_A" event="_NeH84P8fEeW45bORGB4c_A"/>
</transition>
<transition xmi:type="uml:Transition" xmi:id="_egLIoP8fEeW45bORGB4c_A" source="_Fg0IEP8fEeW45bORGB4c_A" target="_EZrg4P8fEeW45bORGB4c_A"/>
<subvertex xmi:type="uml:State" xmi:id="_EZrg4P8fEeW45bORGB4c_A" name="S1"/>
<subvertex xmi:type="uml:State" xmi:id="_FAvg4P8fEeW45bORGB4c_A" name="S2"/>
<subvertex xmi:type="uml:Pseudostate" xmi:id="_Fg0IEP8fEeW45bORGB4c_A"/>
</region>
</packagedElement>
<packagedElement xmi:type="uml:Signal" xmi:id="_L01D0P8fEeW45bORGB4c_A" name="E1"/>
<packagedElement xmi:type="uml:SignalEvent" xmi:id="_NeH84P8fEeW45bORGB4c_A" name="SignalEventE1" signal="_L01D0P8fEeW45bORGB4c_A"/>
</uml:Model>