=clu #13584 mark as experimental and some doc clarificiations

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

@@ -32,6 +32,9 @@ and add the following configuration stanza to your ``application.conf``
  
 Make sure to disable legacy metrics in akka-cluster: ``akka.cluster.metrics.enabled=off``,
 since it is still enabled in akka-cluster by default (for compatibility with past releases).
+
+Cluster members with status :ref:`WeaklyUp <weakly_up_java>`, if that feature is enabled,
+will participate in Cluster Metrics collection and dissemination.
  
 Metrics Collector
 -----------------

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

@@ -22,6 +22,9 @@ the sender to know the location of the destination actor. This is achieved by se
 the messages via a ``ShardRegion`` actor provided by this extension, which knows how
 to route the message with the entity id to the final destination.
 
+Cluster sharding will not be active on members with status :ref:`WeaklyUp <weakly_up_java>` 
+if that feature is enabled.
+
 An Example
 ----------
 

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

@@ -53,6 +53,9 @@ It's worth noting that messages can always be lost because of the distributed na
 As always, additional logic should be implemented in the singleton (acknowledgement) and in the
 client (retry) actors to ensure at-least-once message delivery.
 
+The singleton instance will not run on members with status :ref:`WeaklyUp <weakly_up_java>` if that feature
+is enabled.
+
 Potential problems to be aware of
 ---------------------------------
 

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

@@ -169,6 +169,8 @@ leaving member will be shutdown after the leader has changed status of the membe
 automatically, but in case of network failures during this process it might still be necessary
 to set the node’s status to ``Down`` in order to complete the removal.
 
+.. _weakly_up_java:
+
 WeaklyUp Members
 ^^^^^^^^^^^^^^^^
 
@@ -176,7 +178,13 @@ If a node is ``unreachable`` then gossip convergence is not possible and therefo
 ``leader`` actions are also not possible. However, we still might want new nodes to join
 the cluster in this scenario.
 
-With a configuration option you can allow this behavior::
+.. warning::
+
+  The WeaklyUp feature is marked as **“experimental”** as of its introduction in Akka 2.4.0. We will continue to
+  improve this feature based on our users’ feedback, which implies that while we try to keep incompatible
+  changes to a minimum the binary compatibility guarantee for maintenance releases does not apply this feature.
+
+This feature is disabled by default. With a configuration option you can allow this behavior::
 
     akka.cluster.allow-weakly-up-members = on
 
@@ -185,11 +193,17 @@ When ``allow-weakly-up-members`` is enabled and there is no gossip convergence,
 cluster. Once gossip convergence is reached, the leader will move ``WeaklyUp``
 members to ``Up``.
 
+You can subscribe to the ``WeaklyUp`` membership event to make use of the members that are
+in this state, but you should be aware of that members on the other side of a network partition
+have no knowledge about the existence of the new members. You should for example not count 
+``WeaklyUp`` members in quorum decisions.
+
 .. warning::
 
   This feature is only available from Akka 2.4.0 and cannot be used if some of your
   cluster members are running an older version of Akka.
 
+
 .. _cluster_subscriber_java:
 
 Subscribe to Cluster Events
@@ -458,6 +472,9 @@ automatically unregistered from the router. When new nodes join the cluster addi
 routees are added to the router, according to the configuration. Routees are also added 
 when a node becomes reachable again, after having been unreachable.
 
+Cluster aware routers make use of members with status :ref:`WeaklyUp <weakly_up_java>` if that feature
+is enabled.
+
 There are two distinct types of routers. 
 
 * **Group - router that sends messages to the specified path using actor selection** 

akka-docs/rst/java/distributed-data.rst

@@ -30,7 +30,7 @@ out-of-date value.
   improve this API based on our users’ feedback, which implies that while we try to keep incompatible
   changes to a minimum the binary compatibility guarantee for maintenance releases does not apply to the
   contents of the ``akka.persistence`` package.
-
+  
 Using the Replicator
 ====================
 
@@ -40,6 +40,10 @@ with a specific role. It communicates with other ``Replicator`` instances with t
 (without address) that are running on other nodes . For convenience it can be used with the
 ``akka.cluster.ddata.DistributedData`` extension.
 
+Cluster members with status :ref:`WeaklyUp <weakly_up_java>`, if that feature is enabled,
+will currently not participate in Distributed Data, but that is something that should be possible to
+add in a future release.
+
 Below is an example of an actor that schedules tick messages to itself and for each tick 
 adds or removes elements from a ``ORSet`` (observed-remove set). It also subscribes to
 changes of this. 

akka-docs/rst/java/distributed-pub-sub.rst

@@ -79,6 +79,11 @@ Successful ``Subscribe`` and ``Unsubscribe`` is acknowledged with
 ``DistributedPubSubMediator.SubscribeAck`` and ``DistributedPubSubMediator.UnsubscribeAck``
 replies.
 
+Cluster members with status :ref:`WeaklyUp <weakly_up_java>`, if that feature is enabled,
+will participate in Distributed Publish Subscribe, i.e. subscribers on nodes with 
+``WeaklyUp`` status will receive published messages if the publisher and subscriber are on
+same side of a network partition.
+
 A Small Example
 ---------------