svn commit: r1712247 - /sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext

[st...@apache.org]

Author: stefanegli
Date: Tue Nov  3 10:42:40 2015
New Revision: 1712247

URL: http://svn.apache.org/viewvc?rev=1712247&view=rev
Log:
SLING-4831 : Clarify topology connectors are cross-cluster, not intra-cluster

Modified:
    sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext

Modified: sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext?rev=1712247&r1=1712246&r2=1712247&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext Tue Nov  3 10:42:40 2015
@@ -118,10 +118,28 @@ Administrative note: All the information
 
 	/var/discovery/impl
 
-### Connectors
+### Topology Connectors for Cross-Cluster Discovery
 
-The "cross-cluster" announcement is done via HTTP(s) heartbeats between (arbitrary) cluster instances. These HTTP heartbeats
-(internally termed `connectors`) are configured at [/system/console/configMgr/org.apache.sling.discovery.impl.Config][1].
+From a discovery API's point of view a cluster consists of all instances that are connected to the same repository.
+The above described built-in mechanism of storing a lastHeartbeat property into the (shared) repository, of voting on changes
+and creating an explicit establishedView results in automatic discovery within a cluster. There is therefore 
+no further configuration needed for discovering instances in the same cluster.
+
+However, for discovering multiple clusters such an automatic discovery is not possible and the clusters need
+to be explicitly configured using (cross-cluster) topology connectors:
+
+A topology connector is a periodically issued HTTP PUT that announces the part of the topology known to the
+sending instance to the receiving instance and vica-verca the receiving instance announces its part of the
+topology to the sender in the response of the very same HTTP PUT. This way whatever other clusters are connected 
+to sender or receiver will be made known to each other. Such a 'topology announcement' will be valid either until
+the same sender sends the announcement again (which it does periodically) - or until it times out (configurable).
+A topology connector is by definition always between clusters, never within the same cluster. Topology connectors 
+can be structured in an arbitrary way (chain, star, tree, etc) with the only important point to note here that 
+since changes in the topology propagate through these topology connectors they have a certain delay (namely
+the configured heartbeatInterval per hop).
+
+Topology connectors are configured at [/system/console/configMgr/org.apache.sling.discovery.impl.Config][1].
+They use the same interval and timeout as the repository heartbeats (heartbeatInterval and heartbeatTimeout).
 
 ### WebConsole
 
@@ -171,4 +189,4 @@ The following properties can be configur
 
 
   [1]: http://localhost:8888/system/console/configMgr/org.apache.sling.discovery.impl.Config
-  [2]: http://localhost:8888/system/console/topology
\ No newline at end of file
+  [2]: http://localhost:8888/system/console/topology