Update docs for join state

- Relates to #238

docs/src/reference/asciidoc/sm.adoc

@@ -318,7 +318,7 @@ properly. Mark particular state as choice state by using `join()`
 method. This state doesn't need to match either source states or
 target state in a transition configuration.
 
-Select one target state where transition goes when all source states
+Select a target state where transition goes when all source states
 has been joined. If you use state hosting regions as source, end
 states of a regions are used as joins. Otherwise you can pick any
 states from a regions.
@@ -328,6 +328,17 @@ states from a regions.
 include::samples/DocsConfigurationSampleTests.java[tags=snippetU]
 ----
 
+It is also possible to have multiple transitions originating from a
+join state. It this case it is adviced to use guards and define those
+so that only one guard evaluates _TRUE_ at any given time as otherwise
+transition behaviour is not predicted. This is shown above where guard
+simply checks if extended state has variables.
+
+[source,java,indent=0]
+----
+include::samples/DocsConfigurationSampleTests.java[tags=snippetUUU]
+----
+
 [[statemachine-config-states-exitentry]]
 ==== Exit/Entry Point States
 Exit and Entry Points can be used to do more controlled exit and entry

spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsConfigurationSampleTests.java

@@ -724,6 +724,7 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
 					.initial(States2.S1)
 					.state(States2.S3)
 					.join(States2.S4)
+					.state(States2.S5)
 					.and()
 					.withStates()
 						.parent(States2.S3)
@@ -747,12 +748,69 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
 				.withJoin()
 					.source(States2.S2F)
 					.source(States2.S3F)
+					.target(States2.S4)
+					.and()
+				.withExternal()
+					.source(States2.S4)
 					.target(States2.S5);
 		}
-
 	}
 // end::snippetU[]
 
+// tag::snippetUUU[]
+	@Configuration
+	@EnableStateMachine
+	public class Config22
+			extends EnumStateMachineConfigurerAdapter<States2, Events> {
+
+		@Override
+		public void configure(StateMachineStateConfigurer<States2, Events> states)
+				throws Exception {
+			states
+				.withStates()
+					.initial(States2.S1)
+					.state(States2.S3)
+					.join(States2.S4)
+					.state(States2.S5)
+					.end(States2.SF)
+					.and()
+					.withStates()
+						.parent(States2.S3)
+						.initial(States2.S2I)
+						.state(States2.S21)
+						.state(States2.S22)
+						.end(States2.S2F)
+						.and()
+					.withStates()
+						.parent(States2.S3)
+						.initial(States2.S3I)
+						.state(States2.S31)
+						.state(States2.S32)
+						.end(States2.S3F);
+		}
+
+		@Override
+		public void configure(StateMachineTransitionConfigurer<States2, Events> transitions)
+				throws Exception {
+			transitions
+				.withJoin()
+					.source(States2.S2F)
+					.source(States2.S3F)
+					.target(States2.S4)
+					.and()
+				.withExternal()
+					.source(States2.S4)
+					.target(States2.S5)
+					.guardExpression("!extendedState.variables.isEmpty()")
+					.and()
+				.withExternal()
+					.source(States2.S4)
+					.target(States2.SF)
+					.guardExpression("extendedState.variables.isEmpty()");
+		}
+	}
+// end::snippetUUU[]
+
 // tag::snippetUU[]
 	@Configuration
 	@EnableStateMachine

spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/States2.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2015 the original author or authors.
+ * Copyright 2015-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.
@@ -17,8 +17,8 @@ package org.springframework.statemachine.docs;
 
 //tag::snippetA[]
 public enum States2 {
-    S1,S2,S3,S4,S5,
-    S2I,S21,S22,S2F,
-    S3I,S31,S32,S3F
+	S1,S2,S3,S4,S5,SF,
+	S2I,S21,S22,S2F,
+	S3I,S31,S32,S3F
 }
 //end::snippetA[]