svn commit: r973626 - in /websites/staging/sling/trunk/content: ./ documentation/bundles/discovery-api-and-impl.html

[bu...@apache.org]

Author: buildbot
Date: Thu Nov 26 12:31:18 2015
New Revision: 973626

Log:
Staging update by buildbot for sling

Modified:
    websites/staging/sling/trunk/content/   (props changed)
    websites/staging/sling/trunk/content/documentation/bundles/discovery-api-and-impl.html

Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Nov 26 12:31:18 2015
@@ -1 +1 @@
-1716485
+1716615

Modified: websites/staging/sling/trunk/content/documentation/bundles/discovery-api-and-impl.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles/discovery-api-and-impl.html (original)
+++ websites/staging/sling/trunk/content/documentation/bundles/discovery-api-and-impl.html Thu Nov 26 12:31:18 2015
@@ -133,7 +133,13 @@ instances) and contains a simple propert
 <li><a href="#properties">Properties</a></li>
 <li><a href="#deployment-and-configuration">Deployment and configuration</a></li>
 <li><a href="#discoveryimpl-resource-based-ootb-implementation">discovery.impl: Resource-based, OOTB Implementation</a><ul>
-<li><a href="#location-in-repository">Location in Repository</a></li>
+<li><a href="#location-in-repository">Location in Repository</a><ul>
+<li><a href="#vardiscoveryimplclusterinstances">/var/discovery/impl/clusterInstances/<slingId></a></li>
+<li><a href="#vardiscoveryimplestablishedview">/var/discovery/impl/establishedView</a></li>
+<li><a href="#vardiscoveryimplongoingvotings">/var/discovery/impl/ongoingVotings</a></li>
+<li><a href="#vardiscoveryimplpreviousview">/var/discovery/impl/previousView</a></li>
+</ul>
+</li>
 <li><a href="#heartbeats-voting-and-intra-cluster-discovery">Heartbeats, Voting and Intra-Cluster Discovery</a></li>
 <li><a href="#topology-connectors-for-cross-cluster-discovery">Topology Connectors for Cross-Cluster Discovery</a></li>
 <li><a href="#webconsole">WebConsole</a></li>
@@ -157,20 +163,22 @@ instances) and contains a simple propert
 <p>In the discovery API this cluster concept is represented via a <code>ClusterView</code> object. A 'view' because it is a momentary snapshot of the cluster and only contains instances that are currently alive. It's features are:</p>
 <ul>
 <li>each cluster has a stable leader. Stable meaning it won't change unless that leader crashes.</li>
-<li>it has a list of instances that are part of it, thus currently alive</li>
+<li>it has an ordered, stable list of instances that are part of it, thus currently alive. the relative order of instances in this list is stable, meaning that it only stays or moves up one position if an instance listed 'above' crashes - a newly started instance will always be added at the end of this list.</li>
 <li>plus it has a unique id that is persistent across restarts</li>
 </ul>
 <h3 id="topology-topologyview">Topology, TopologyView<a class="headerlink" href="#topology-topologyview" title="Permanent link">&para;</a></h3>
 <p>The topology - or more precisely the <code>TopologyView</code> - represents a snapshot (<code>view</code>) of a number of loosely coupled Sling instances (<code>InstanceDescription</code>)
 and clusters (<code>ClusterView</code>) of a particular deployment. A cluster can consist of one or more instances. Each instance
-is always part of a cluster (even if the cluster consists of only one instance). The features are:
-* only one: it has a list of clusters</p>
+is always part of a cluster (even if the cluster consists of only one instance). The features are:</p>
+<ul>
+<li>only one: it has a list of clusters</li>
+</ul>
 <p>There are no further assumption made on the structure of a topology.</p>
 <p>If different clusters in the topology should represent different 'types of clusters' (eg a publish or an author cluster), 
 then that is not explicitly handled by the discovery API. Instead, applications can define properties on each instance
 that model such cluster types or other aspects.</p>
 <h2 id="cluster-leader-and-instance-ordering">Cluster Leader and Instance Ordering<a class="headerlink" href="#cluster-leader-and-instance-ordering" title="Permanent link">&para;</a></h2>
-<p>The discovery API introduces support for a <code>cluster leader</code>: within each cluster, the API guarantees that one and only one
+<p>As mentioned the discovery API introduces support for a <code>cluster leader</code>: within each cluster, the API guarantees that one and only one
 instance is leader at any time. That leader is guaranteed to be <code>stable</code>, ie as long as it stays alive and is visible
 by other instances of the same cluster, it will stay leader. As soon as it leaves the cluster (or the corresponding
 implementation bundle is deactivated), another instance in that cluster is elected leader. The leader can be used to
@@ -253,6 +261,51 @@ that it sees the same number of instance
 </pre></div>
 
 
+<h4 id="vardiscoveryimplclusterinstances">/var/discovery/impl/clusterInstances/<slingId><a class="headerlink" href="#vardiscoveryimplclusterinstances" title="Permanent link">&para;</a></h4>
+<p>Each instance has its own node under <code>clusterInstances/</code> where it stores:</p>
+<ul>
+<li><code>lastHeartbeat</code>: property, which marks the instance alive for another <code>heartbeatTimeout</code></li>
+<li><code>leaderElectionId</code>: an id which is used to determine the leader: the instance with the lowest such leaderElectionId is the leader.
+Therefore this id is crucial to implement stable leader and ordering. The id contains a prefix (to account for a crx2 edge case
+where jobs might want to be executed on slave rather than on master), followed by the bundle activate time (to honour stability)
+and ultimately by the slingId (to have a discriminator should there be multiple instances started at the same time)</li>
+<li><code>runtimeId</code>: a plain, random UUID that is created fresh upon bundle activation. It is used to detect situations where
+multiple instances have the same slingId and thus write into the same <code>/var/discovery/impl/clsuterInstances/&lt;slingId&gt;</code> node.</li>
+<li><code>slingHomePath</code> and <code>endpoints</code>: these are used for logging purpose only</li>
+</ul>
+<p>Additionally, there are two sub-nodes:</p>
+<ul>
+<li><code>announcements</code>: this contains announcements of topology connector peers (also see below). An announcement is a json-encoded
+representation of the sub-tree that the connector peer is aware of and is thereby announcing to this instance. Announcements
+are sent in both directions of a topology connector. Discovery.impl takes care of filtering out duplicate instances should
+the structure of topology connectors, and thus these announcements overlap (which is legal)</li>
+<li><code>properties</code>: contains all properties as specified by registered <code>PropertyProvider</code></li>
+</ul>
+<h4 id="vardiscoveryimplestablishedview">/var/discovery/impl/establishedView<a class="headerlink" href="#vardiscoveryimplestablishedview" title="Permanent link">&para;</a></h4>
+<p>This contains the currently valid, agreed/voted upon cluster view that lists all alive instances:</p>
+<ul>
+<li>the name of the node directly under <code>establishedView</code> is a unique id of the current incarnation of the cluster view -
+thus changes whenever an instance joins or leaves or there is a new voting for another reason.
+<strong> <code>clusterId</code> : name of the persistent identifier of this cluster. As this is propagated from cluster view to cluster view
+it stays unchanged forever.
+</strong> <code>leaderElectionId</code>: the leaderElectionId that was winning, ie that was lowest
+** <code>leaderId</code>: the slingId of the instance that is leader of this cluster view</li>
+<li><code>members</code>: just an intermediate node containing all alive instances as child nodes</li>
+<li>child node of <code>members</code>: each child represents a particular alive node (with the name being the slingId) and contains
+the following properties:
+<strong> <code>leaderElectionId</code>: the id that will be used to determine the leader - this value is copied from the corresponding
+<code>/var/discovery/impl/clusterInstances/&lt;slingId&gt;</code>
+</strong> <code>initiator</code>: this marks the instance that originally created this voting
+** <code>vote</code>: represents this instance's vote, which is true for a voting that got promoted to established view</li>
+</ul>
+<h4 id="vardiscoveryimplongoingvotings">/var/discovery/impl/ongoingVotings<a class="headerlink" href="#vardiscoveryimplongoingvotings" title="Permanent link">&para;</a></h4>
+<p>This area is used for voting. Each instance can initiate a voting when it realizes that the live instances - denominated
+by those instances that have a not-yet-timed-out heartbeat property - does not match with the <code>establishedView</code>.</p>
+<p>Once a voting gets a yes vote by all instances it is promoted (moved) under <code>establishedView</code> by the initiating instance. 
+Each establishedView was once a voting, thus the structure is the same as described above.</p>
+<h4 id="vardiscoveryimplpreviousview">/var/discovery/impl/previousView<a class="headerlink" href="#vardiscoveryimplpreviousview" title="Permanent link">&para;</a></h4>
+<p>The instance that promotes its winning voting to <code>establishedView</code> first moves what was there before under <code>previousView</code>.
+This is purely for debugging and not used anywhere, it just represents a persistet history of previous views of length 1.</p>
 <h3 id="heartbeats-voting-and-intra-cluster-discovery">Heartbeats, Voting and Intra-Cluster Discovery<a class="headerlink" href="#heartbeats-voting-and-intra-cluster-discovery" title="Permanent link">&para;</a></h3>
 <p><code>discovery.impl</code> uses the fact that all instance of a cluster are connected to the same repository as the
 basis for discovering those instances. It does so by using a heartbeat and voting mechanism:</p>
@@ -346,7 +399,7 @@ They use the same interval and timeout a
 </li>
 </ul>
       <div class="timestamp" style="margin-top: 30px; font-size: 80%; text-align: right;">
-        Rev. 1716485 by stefanegli on Wed, 25 Nov 2015 16:59:06 +0000
+        Rev. 1716615 by stefanegli on Thu, 26 Nov 2015 12:31:04 +0000
       </div>
       <div class="trademarkFooter"> 
         Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project