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">¶</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">¶</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">¶</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/<slingId></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">¶</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/<slingId></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">¶</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">¶</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">¶</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
