From 5879332f9f0fa40cc1399e1c566295b8b6627690 Mon Sep 17 00:00:00 2001 From: Janne Valkealahti Date: Sun, 23 Aug 2015 09:47:26 +0100 Subject: [PATCH] More docs for dist machine --- build.gradle | 1 + docs/src/reference/asciidoc/sm.adoc | 30 ++++++- .../docs/DocsZookeeperSampleTests.java | 84 +++++++++++++++++++ 3 files changed, 113 insertions(+), 2 deletions(-) create mode 100644 spring-statemachine-zookeeper/src/test/java/org/springframework/statemachine/zookeeper/docs/DocsZookeeperSampleTests.java diff --git a/build.gradle b/build.gradle index db484782..42c18f78 100644 --- a/build.gradle +++ b/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/' diff --git a/docs/src/reference/asciidoc/sm.adoc b/docs/src/reference/asciidoc/sm.adoc index e22b83c9..f28421ad 100644 --- a/docs/src/reference/asciidoc/sm.adoc +++ b/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 <> and actual usage example see sample <>. @@ -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 <>. +=== 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 diff --git a/spring-statemachine-zookeeper/src/test/java/org/springframework/statemachine/zookeeper/docs/DocsZookeeperSampleTests.java b/spring-statemachine-zookeeper/src/test/java/org/springframework/statemachine/zookeeper/docs/DocsZookeeperSampleTests.java new file mode 100644 index 00000000..fc394c60 --- /dev/null +++ b/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 { + + @Override + public void configure(StateMachineConfigurationConfigurer config) + throws Exception { + config + .withDistributed() + .ensemble(stateMachineEnsemble()) + .and() + .withConfiguration() + .autoStartup(true); + } + + @Override + public void configure(StateMachineStateConfigurer states) + throws Exception { + // config states + } + + @Override + public void configure(StateMachineTransitionConfigurer transitions) + throws Exception { + // config transitions + } + + @Bean + public StateMachineEnsemble stateMachineEnsemble() + throws Exception { + return new ZookeeperStateMachineEnsemble(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[] + +}