More docs for dist machine

build.gradle

@@ -248,6 +248,7 @@ configure(rootProject) {
 		from 'spring-statemachine-core/src/test/java/org/springframework/statemachine/docs'
 		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-samples/src/main/java/'
 		from 'spring-statemachine-samples/washer/src/main/java/'
 		from 'spring-statemachine-samples/tasks/src/main/java/'

docs/src/reference/asciidoc/sm.adoc

@@ -743,7 +743,7 @@ Distributed state is probably one of a most compicated concepts of a
 Spring State Machine. What exactly is a distributed state? A state
 within a single state machine is naturally really simple to understand
 but when there is a need to introduce a shared distributed state
-thoughout a state machines, things will get a little complicated.
+through a state machines, things will get a little complicated.
 
 [NOTE]
 ====
@@ -752,7 +752,7 @@ yet considered to be stable in this particular release. We expect this
 feature to mature towards the first official release.
 ====
 
-For configuration support see section
+For generic configuration support see section
 <<statemachine-config-commonsettings>> and actual usage example see
 sample <<statemachine-examples-zookeeper>>.
 
@@ -769,9 +769,35 @@ distributed state abstractions handled via interface
 While `Distributed State Machine` is implemented via an abstraction,
 only one implementation currently exists based on `Zookeeper`.
 
+Here is a generic example of how `Zookeeper` based `Distributed State
+Machine` would be configured.
+
+[source,java,indent=0]
+----
+include::samples/DocsZookeeperSampleTests.java[tags=snippetA]
+----
+
 Current technical documentation of a `Zookeeker` based distributed
 state machine can be found from an appendice <<appendices-zookeeper>>.
 
+=== ZookeeperStateMachineEnsemble
+`ZookeeperStateMachineEnsemble` itself needs two mandatory settings,
+an instance of `curatorClient` and `basePath`. Client is a
+`CuratorFramework` and path is root of a tree in a `Zookeeper`.
+
+Optionally it is possible to set `cleanState` which defaults to `TRUE`
+and will clear existing data if no members exists in an ensemble. Set
+this to `FALSE` if you want to preserve distributed state within
+application restarts.
+
+Optionally it is possible to set a size of a `logSize` which defaults
+to `32` and is used to keep history of state changes. Value of this
+setting needs to be a power of two. `32` is generally good default
+value but if a particular state machine is left behind more than a
+size of a log it is put into error state and disconnected from an
+ensemble indicating it has lost its history to reconstruct fully
+synchronized status.
+
 [[sm-test]]
 == Testing Support
 We have also added a set of utility classes to easy testing of a state

spring-statemachine-zookeeper/src/test/java/org/springframework/statemachine/zookeeper/docs/DocsZookeeperSampleTests.java

@@ -0,0 +1,84 @@
+/*
+ * 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.zookeeper.docs;
+
+import org.apache.curator.framework.CuratorFramework;
+import org.apache.curator.framework.CuratorFrameworkFactory;
+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.StateMachineConfigurationConfigurer;
+import org.springframework.statemachine.config.builders.StateMachineStateConfigurer;
+import org.springframework.statemachine.config.builders.StateMachineTransitionConfigurer;
+import org.springframework.statemachine.ensemble.StateMachineEnsemble;
+import org.springframework.statemachine.zookeeper.ZookeeperStateMachineEnsemble;
+
+public class DocsZookeeperSampleTests {
+
+	public void sample1() {
+	}
+
+// tag::snippetA[]
+	@Configuration
+	@EnableStateMachine
+	static class Config
+			extends StateMachineConfigurerAdapter<String, String> {
+
+		@Override
+		public void configure(StateMachineConfigurationConfigurer<String, String> config)
+				throws Exception {
+			config
+				.withDistributed()
+					.ensemble(stateMachineEnsemble())
+					.and()
+				.withConfiguration()
+					.autoStartup(true);
+		}
+
+		@Override
+		public void configure(StateMachineStateConfigurer<String, String> states)
+				throws Exception {
+			// config states
+		}
+
+		@Override
+		public void configure(StateMachineTransitionConfigurer<String, String> transitions)
+				throws Exception {
+			// config transitions
+		}
+
+		@Bean
+		public StateMachineEnsemble<String, String> stateMachineEnsemble()
+				throws Exception {
+			return new ZookeeperStateMachineEnsemble<String, String>(curatorClient(), "/zkpath");
+		}
+
+		@Bean
+		public CuratorFramework curatorClient()
+				throws Exception {
+			CuratorFramework client = CuratorFrameworkFactory
+					.builder()
+					.defaultData(new byte[0])
+					.connectString("localhost:2181").build();
+			client.start();
+			return client;
+		}
+
+	}
+// end::snippetA[]
+
+}