+clu #3636 Revert join to uninitialized

* Revert the change introduced in
  https://github.com/akka/akka/pull/1738/files
* The cleanup/improvements aside of the actual
  feature is not reverted by this patch
* Clarify the documentation

akka-cluster/src/main/scala/akka/cluster/ClusterDaemon.scala

@@ -292,7 +292,6 @@ private[cluster] class ClusterCoreDaemon(publisher: ActorRef) extends Actor with
     case InitJoin                          ⇒ sender ! InitJoinNack(selfAddress)
     case ClusterUserAction.JoinTo(address) ⇒ join(address)
     case JoinSeedNodes(seedNodes)          ⇒ joinSeedNodes(seedNodes)
-    case Join(node, roles)                 ⇒ joiningUninitialized(node, roles)
     case msg: SubscriptionMessage          ⇒ publisher forward msg
   }
 
@@ -305,7 +304,6 @@ private[cluster] class ClusterCoreDaemon(publisher: ActorRef) extends Actor with
     case JoinSeedNodes(seedNodes) ⇒
       becomeUninitialized()
       joinSeedNodes(seedNodes)
-    case Join(node, roles)        ⇒ joiningUninitialized(node, roles)
     case msg: SubscriptionMessage ⇒ publisher forward msg
     case _: Tick ⇒
       if (deadline.exists(_.isOverdue)) {
@@ -473,16 +471,6 @@ private[cluster] class ClusterCoreDaemon(publisher: ActorRef) extends Actor with
     }
   }
 
-  /**
-   * Another node is joining when this node is uninitialized.
-   */
-  def joiningUninitialized(node: UniqueAddress, roles: Set[String]): Unit = {
-    require(latestGossip.members.isEmpty, "Joining an uninitialized node can only be done from empty state")
-    joining(node, roles)
-    if (latestGossip.hasMember(selfUniqueAddress))
-      becomeInitialized()
-  }
-
   /**
    * Reply from Join request.
    */

akka-cluster/src/multi-jvm/scala/akka/cluster/NodeUpSpec.scala

@@ -32,19 +32,21 @@ abstract class NodeUpSpec
   import ClusterEvent._
 
   "A cluster node that is joining another cluster" must {
-    "be moved to UP by the leader after a convergence" taggedAs LongRunningTest in {
+    "not be able to join a node that is not a cluster member" taggedAs LongRunningTest in {
 
-      // it should be possible to join an uninitialized node
-      // test race on purpose
       runOn(first) {
         cluster.join(second)
       }
-      runOn(second) {
-        cluster.join(first)
-      }
+      enterBarrier("first-join-attempt")
 
-      awaitMembersUp(2)
+      Thread.sleep(2000)
+      clusterView.members must be(Set.empty)
 
+      enterBarrier("after-0")
+    }
+
+    "be moved to UP by the leader after a convergence" taggedAs LongRunningTest in {
+      awaitClusterUp(first, second)
       enterBarrier("after-1")
     }
 

akka-docs/rst/java/cluster-usage.rst

@@ -110,6 +110,8 @@ The seed nodes can be started in any order and it is not necessary to have all
 seed nodes running, but the node configured as the first element in the ``seed-nodes``
 configuration list must be started when initially starting a cluster, otherwise the 
 other seed-nodes will not become initialized and no other node can join the cluster. 
+The reason for the special first seed node is to avoid forming separated islands when
+starting from an empty cluster.
 It is quickest to start all configured seed nodes at the same time (order doesn't matter), 
 otherwise it can take up to the configured ``seed-node-timeout`` until the nodes
 can join.
@@ -122,7 +124,15 @@ If you don't configure the seed nodes you need to join manually, using :ref:`clu
 or :ref:`cluster_command_line_java`. You can join to any node in the cluster. It doesn't 
 have to be configured as a seed node.
 
-Joining can also be performed programatically with ``Cluster.get(system).join(address)``.
+Joining can also be performed programatically with ``Cluster.get(system).join``. Note that
+you can only join to an existing cluster member, which means that for bootstrapping some
+node must join itself.
+
+You may also use ``Cluster.get(system).joinSeedNodes``, which is attractive when dynamically 
+discovering other nodes at startup by using some external tool or API. When using 
+``joinSeedNodes`` you should not include the node itself except for the node that is 
+supposed to be the first seed node, and that should be placed first in parameter to 
+``joinSeedNodes``.
 
 Unsuccessful join attempts are automatically retried after the time period defined in 
 configuration property ``retry-unsuccessful-join-after``. When using ``seed-nodes`` this

akka-docs/rst/scala/cluster-usage.rst

@@ -102,7 +102,9 @@ This can also be defined as Java system properties when starting the JVM using t
 The seed nodes can be started in any order and it is not necessary to have all
 seed nodes running, but the node configured as the first element in the ``seed-nodes``
 configuration list must be started when initially starting a cluster, otherwise the 
-other seed-nodes will not become initialized and no other node can join the cluster. 
+other seed-nodes will not become initialized and no other node can join the cluster.
+The reason for the special first seed node is to avoid forming separated islands when
+starting from an empty cluster.
 It is quickest to start all configured seed nodes at the same time (order doesn't matter), 
 otherwise it can take up to the configured ``seed-node-timeout`` until the nodes
 can join.
@@ -115,7 +117,15 @@ If you don't configure the seed nodes you need to join manually, using :ref:`clu
 or :ref:`cluster_command_line_scala`. You can join to any node in the cluster. It doesn't 
 have to be configured as a seed node.
 
-Joining can also be performed programatically with ``Cluster(system).join(address)``.
+Joining can also be performed programatically with ``Cluster(system).join``. Note that
+you can only join to an existing cluster member, which means that for bootstrapping some
+node must join itself.
+
+You may also use ``Cluster(system).joinSeedNodes``, which is attractive when dynamically 
+discovering other nodes at startup by using some external tool or API. When using 
+``joinSeedNodes`` you should not include the node itself except for the node that is 
+supposed to be the first seed node, and that should be placed first in parameter to 
+``joinSeedNodes``.
 
 Unsuccessful join attempts are automatically retried after the time period defined in 
 configuration property ``retry-unsuccessful-join-after``. When using ``seed-nodes`` this