Add docs for repository config

- Docs for base usage, jpa and jpa sample.
- Relates to #238

docs/src/reference/asciidoc/getting-started.adoc

@@ -16,7 +16,8 @@ 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.
+beyond framework itself. Also optional security and data access has
+dependencies to _Spring Security_ and _Spring Data Modules_.
 
 == Modules
 The following modules are available for Spring Statemachine.
@@ -37,6 +38,12 @@ framework.
 |spring-statemachine-redis
 |`Redis` related features for state machine.
 
+|spring-statemachine-data-common
+|Common support module for `Spring Data`.
+
+|spring-statemachine-data-jpa
+|Support module for `Spring Data JPA`.
+
 |spring-statemachine-zookeeper
 |`Zookeeper` integration for a distributed state machine.
 
@@ -47,7 +54,7 @@ framework.
 |Support module for Spring Cloud Cluster.
 
 |spring-statemachine-uml
-|Support module for UI uml modeling.
+|Support module for UI uml modeling with Eclipse Papyrus.
 |===
 
 == Using Gradle

docs/src/reference/asciidoc/samples/data.json

@@ -0,0 +1,29 @@
+[
+	{
+		"_class": "org.springframework.statemachine.data.jpa.JpaRepositoryState",
+		"initial": true,
+		"state": "S1"
+	},
+	{
+		"_class": "org.springframework.statemachine.data.jpa.JpaRepositoryState",
+		"initial": false,
+		"state": "S2"
+	},
+	{
+		"_class": "org.springframework.statemachine.data.jpa.JpaRepositoryState",
+		"initial": false,
+		"state": "S3"
+	},
+	{
+		"_class": "org.springframework.statemachine.data.jpa.JpaRepositoryTransition",
+		"source": "S1",
+		"target": "S2",
+		"event": "E1"
+	},
+	{
+		"_class": "org.springframework.statemachine.data.jpa.JpaRepositoryTransition",
+		"source": "S2",
+		"target": "S3",
+		"event": "E2"
+	}
+]

docs/src/reference/asciidoc/sm-examples.adoc

@@ -36,6 +36,8 @@ normal build cycle. Samples in this chapter are:
 
 <<statemachine-examples-ordershipping>> Order Shipping.
 
+<<statemachine-examples-datajpa>> JPA Config.
+
 
 [source,text]
 ----
@@ -1425,3 +1427,69 @@ Finally you can see what machine does by refressing a page.
 
 image::images/sm-ordershipping-4.png[width=1000]
 
+[[statemachine-examples-datajpa]]
+== JPA Config
+JPA Config is an example how state machine concepts can be used
+with a machine configuration kept in a database. This sample is using
+embedded _H2_ database with a _H2 Console_ to ease playing with a
+database.
+
+To enable automatic scan of needed _Entity_ classes and _JPA
+Repositories_, a boot application can be annotated with a custom
+locations as shown below.
+
+[source,java,indent=0]
+----
+include::samples/demo/datajpa/Application.java[tags=snippetA]
+----
+
+What comes for a machine config `RepositoryStateMachineModelFactory`
+can be used as shown below.
+
+[source,java,indent=0]
+----
+include::samples/demo/datajpa/StateMachineConfig.java[tags=snippetB]
+----
+
+Lets get into actual demo. Run the boot based sample application:
+
+[source,text,subs="attributes"]
+----
+# java -jar spring-statemachine-samples-datajpa-{revnumber}.jar
+----
+
+Accessing application via _http://localhost:8080_ brings up a new
+constructed machine with every request and you can choose to send
+events to a machine. Possible events and machine configuration are
+updated from a database with every request.
+
+image::images/sm-datajpa-1.png[width=1000]
+
+To access embedded console use _JDBC URL_ `jdbc:h2:mem:testdb` if it's
+not already set.
+
+image::images/sm-datajpa-2.png[width=1000]
+
+From console you can see how database tables look like and modify
+those as you wish.
+
+image::images/sm-datajpa-3.png[width=1000]
+
+Now that you got this far you probably wondered how those default
+states and transitions got populated into a database. Spring Data
+already have a nice trick to auto populate repositories and we simply
+use this feature via `Jackson2RepositoryPopulatorFactoryBean`.
+
+
+[source,java,indent=0]
+----
+include::samples/demo/datajpa/StateMachineConfig.java[tags=snippetA]
+----
+
+Actual source for populator data is shown below.
+
+[source,json,indent=0]
+----
+include::samples/data.json[]
+----
+

docs/src/reference/asciidoc/sm.adoc

@@ -36,6 +36,8 @@ that Spring Statemachine provides to any Spring based application.
 
 <<sm-papyrus>> the state machine uml modeling support.
 
+<<sm-repository>> the state machine repository config support.
+
 [[sm-config]]
 == Statemachine Configuration
 One of the common tasks when using a Statemachine is to design its
@@ -2015,3 +2017,57 @@ sub-state.
 
 image::images/papyrus-gs-15.png[width=400]
 
+[[sm-repository]]
+== Repository Config Support
+
+[IMPORTANT]
+====
+Repository abstraction support is still work in progress and scheduled
+to be complete in future milestones.
+====
+
+It is also possible to keep machine configuration in an external
+storage where it will be loaded on demand instead of creating a static
+configuration either using _JavaConfig_ or _UML_ based config. This
+integration works via _Spring Data Repository_ abstraction.
+
+We have created special `StateMachineModelFactory` implementation
+called `RepositoryStateMachineModelFactory` which is able to use base
+repository interfaces `StateRepository` and `TransitionRepository`
+accompanied with base entity interfaces `RepositoryState` and
+`RepositoryTransition` respectively.
+
+Due to way how _Entities_ and _Repositories_ work in a _Spring Data_,
+from a user perspective read access can be fully abstracted as it is
+done in `RepositoryStateMachineModelFactory` as there is no need to
+know what is a real mapped _Entity_ class _Repository_ is working
+with. Writing into a _Repository_ is always dependant of using a real
+_Repository_ specific _Entity_ class. From machine configuration point
+of view we don't need to know these, meaning we don't need to know
+actual implementation whether that is _JPA_, _Mongo_  or anything else
+what _Spring Data_ supports. Using a real _Repository_ related
+_Entity_ class comes into play when you manually try to write new
+states or transitions into a backed repository.
+
+Actual out of a box implementations are documented in below sections.
+
+[[sm-repository-jpa]]
+=== JPA
+Currently one repository implementation exists which uses _JPA_ to
+access configured database.
+
+Actual _Repository_ implementations for a _JPA_ are
+`JpaStateRepository` and `JpaTransitionRepository` which are backed by
+_Entity_ classes `JpaRepositoryState` and `JpaRepositoryTransition`
+respectively.
+
+Generic way to update states and transition manually is shown below.
+
+[source,java,indent=0]
+----
+include::samples/DocsJpaRepositorySampleTests1.java[tags=snippetA]
+----
+
+Complete example can be found from sample
+<<statemachine-examples-datajpa>>.
+