Author: buildbot
Date: Wed May 22 11:39:24 2013
New Revision: 862731
Log:
Staging update by buildbot for sling
Added:
websites/staging/sling/trunk/content/documentation/bundles/discovery-api-and-impl.html
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/bundles.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed May 22 11:39:24 2013
@@ -1 +1 @@
-1484690
+1485160
Modified: websites/staging/sling/trunk/content/documentation/bundles.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/bundles.html (original)
+++ websites/staging/sling/trunk/content/documentation/bundles.html Wed May 22
11:39:24 2013
@@ -118,9 +118,10 @@
<li><a href="/documentation/bundles/sling-health-check-tool.html">Sling Health
Check Tool</a></li>
<li><a
href="/documentation/bundles/scheduler-service-commons-scheduler.html">Scheduler
Service (commons scheduler)</a></li>
<li><a href="/documentation/bundles/web-console-extensions.html">Web Console
Extensions (org.apache.sling.extensions.webconsolebranding,
org.apache.sling.extensions.webconsolesecurityprovider)</a></li>
+<li><a href="/documentation/bundles/discovery-api-and-impl.html">Discovery API
and Resource Based Implementation (discovery.api, discovery.impl)</a></li>
</ul>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1484690 by bdelacretaz on Tue, 21 May 2013 08:18:10 +0000
+ Rev. 1485160 by stefanegli on Wed, 22 May 2013 11:39:14 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
Added:
websites/staging/sling/trunk/content/documentation/bundles/discovery-api-and-impl.html
==============================================================================
---
websites/staging/sling/trunk/content/documentation/bundles/discovery-api-and-impl.html
(added)
+++
websites/staging/sling/trunk/content/documentation/bundles/discovery-api-and-impl.html
Wed May 22 11:39:24 2013
@@ -0,0 +1,233 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
+<html>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+ <head>
+ <title>Apache Sling - Discovery API and its Implementations</title>
+ <link rel="icon" href="/res/favicon.ico">
+ <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+ <link rel="stylesheet" href="/res/codehilite.css" type="text/css"
media="all">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://sling.apache.org/";>
+ <img border="0" alt="Apache Sling" src="/res/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/";>
+ <img border="0" alt="Apache" src="/res/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><strong><a href="/documentation.html">Documentation</a></strong> <br
/>
+<a href="/documentation/getting-started.html">Getting Started</a> <br />
+<a href="/documentation/the-sling-engine.html">The Sling Engine</a> <br />
+<a href="/documentation/development.html">Development</a> <br />
+<a href="/documentation/bundles.html">Bundles</a> <br />
+<a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a>
<br />
+<a href="/documentation/configuration.html">Configuration</a> <br />
+<a href="http://s.apache.org/sling.wiki";>Wiki</a> <br />
+<a href="http://s.apache.org/sling.faq";>FAQ</a> <br />
+<a href="/sitemap.html">Site Map</a></p>
+<p><strong>API Docs</strong> <br />
+<a href="/apidocs/sling6/index.html">Sling 6</a> <br />
+<a href="/apidocs/sling5/index.html">Sling 5</a> <br />
+</p>
+<p><strong>Project info</strong> <br />
+<a href="/downloads.cgi">Downloads</a> <br />
+<a href="http://www.apache.org/licenses/";>License</a> <br />
+<a href="/contributing.html">Contributing</a> <br />
+<a href="/news.html">News</a> <br />
+<a href="/links.html">Links</a> <br />
+<a href="/project-information.html">Project Information</a> <br />
+<a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a> <br />
+<a href="http://svn.apache.org/viewvc/sling/trunk";>Browse Source
Repository</a> <br />
+<a href="/project-information/security.html">Security</a> <br />
+</p>
+<p><strong>Sponsorship</strong> <br />
+<a href="http://www.apache.org/foundation/thanks.html";>Thanks</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html";>Become a
Sponsor</a> <br />
+<a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a> <br />
+</p>
+<iframe
+ src="http://www.apache.org/ads/button.html";
+ style="border-width:0; float: left" frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a
href="/documentation.html">Documentation</a> » <a
href="/documentation/bundles.html">Bundles</a>
+ </div>
+
+
+
+ <h1>Discovery API and its Implementations</h1>
+ <p>In many situations a particular Sling-based deployment consists of
more than one Sling-instances:
+typically a number of instances would form a <code>cluster</code> that share a
common repository -
+in other situations, or additionally, instances might be loosely-coupled, each
with their own repository.</p>
+<p>The <code>discovery-api</code> bundle introduces an abstraction for such
scenarios called <code>topology</code>. It provides
+access to the current topology, allows to be informed of any changes in the
topology (such as joining or leaving
+instances) and contains a simple property exchange mechanism, e.g. to allow
building communication services on top of it.</p>
+<h2 id="topology">Topology</h2>
+<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 automatically part to a cluster (even if the cluster only consists
of one instance).
+Each instance and cluster has an identifier.
+Other than this cluster-instance relation there is no further
+assumption made on the structure of a topology. Therefore if the actual
structure is of a different shape (such as a tree)
+this would have to be managed separately.</p>
+<h2 id="cluster-leader-and-instance-ordering">Cluster Leader and Instance
Ordering</h2>
+<p>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
+deal with work that must be guaranteed to only execute on one (but any)
instance in the cluster.</p>
+<p>Additionally each cluster (<code>ClusterView</code>) orders its instances
in a stable list: each newly joined instances is added
+at the end of the list and retains its order in the list as long as it doesn't
leave the cluster. This can be used
+to distribute "singleton" work amongst the cluster to more than just the
leader. </p>
+<h2 id="topology-changes">Topology Changes</h2>
+<p>The <code>DiscoveryService</code> provides access to the currently valid
<code>TopologyView</code>. Additionally applications can
+register a <code>TopologyEventListener</code> and thus be informed about any
changes in the topology. Whenever the discovery
+service detects that an instance is no longer reponding or has newly joined,
or a new leader has been elected,
+it sends a <code>TOPOLOGY_CHANGING</code> event, starts
+settling the change within the topology (ie making sure everybody else in the
topology agrees on the change) and finally
+sends a <code>TOPOLOGY_CHANGED</code> event with the new topology.
+Additionally, when "only" properties have changed, a
<code>PROPERTIES_CHANGED</code> event is sent.</p>
+<p>Note that the detection of topology (or properties) changes will incur a
delay which is implementation dependent.</p>
+<p>The following is an example of a listener - note that the binding is done
automatically by OSGi:</p>
+<div class="codehilite"><pre><span class="nb">import</span> <span
class="n">org</span><span class="o">.</span><span class="n">apache</span><span
class="o">.</span><span class="n">felix</span><span class="o">.</span><span
class="n">scr</span><span class="o">.</span><span
class="n">annotations</span><span class="o">.</span><span
class="n">Component</span><span class="p">;</span>
+<span class="nb">import</span> <span class="n">org</span><span
class="o">.</span><span class="n">apache</span><span class="o">.</span><span
class="n">felix</span><span class="o">.</span><span class="n">scr</span><span
class="o">.</span><span class="n">annotations</span><span
class="o">.</span><span class="n">Service</span><span class="p">;</span>
+<span class="nb">import</span> <span class="n">org</span><span
class="o">.</span><span class="n">apache</span><span class="o">.</span><span
class="n">sling</span><span class="o">.</span><span
class="n">discovery</span><span class="o">.</span><span
class="n">TopologyEvent</span><span class="p">;</span>
+<span class="nb">import</span> <span class="n">org</span><span
class="o">.</span><span class="n">apache</span><span class="o">.</span><span
class="n">sling</span><span class="o">.</span><span
class="n">discovery</span><span class="o">.</span><span
class="n">TopologyEventListener</span><span class="p">;</span>
+
+<span class="nv">@Component</span><span class="p">(</span><span
class="n">immediate</span> <span class="o">=</span> <span
class="n">true</span><span class="p">)</span>
+<span class="nv">@Service</span><span class="p">(</span><span
class="n">value</span> <span class="o">=</span> <span class="p">{</span> <span
class="n">TopologyEventListener</span><span class="o">.</span><span
class="n">class</span> <span class="p">})</span>
+<span class="n">public</span> <span class="n">class</span> <span
class="n">MyTopologyEventListener</span> <span class="n">implements</span>
<span class="n">TopologyEventListener</span> <span class="p">{</span>
+
+ <span class="n">public</span> <span class="n">void</span> <span
class="n">handleTopologyEvent</span><span class="p">(</span><span
class="n">final</span> <span class="n">TopologyEvent</span> <span
class="n">event</span><span class="p">)</span> <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">your</span> <span
class="n">code</span> <span class="n">here</span>
+ <span class="p">}</span>
+
+<span class="p">}</span>
+</pre></div>
+
+
+<h2 id="properties">Properties</h2>
+<p>The discovery API not only lists all clusters and instances that are part
of a topology but also provides a simple
+mechanism for announcing properties of each instance to the topology. This can
be achieved via the <code>PropertyProvider</code>.
+Typical use cases for this are announcements of endpoint-URLs or ports such
that applications can communicate to other
+instances in the topology.</p>
+<p>Note that the properties mechanism is by no means to be used as a messaging
tool: both from an API point of view and
+the implementation of it are not optimized for frequent changes and its use
for messaging is discouraged. Instead
+it should be used to announce configuration information for accessing proper
messaging services.</p>
+<p>The following is an example of a PropertyProvider, providing
<code>sample.value1</code> and <code>sample.value2</code> properties:</p>
+<div class="codehilite"><pre><span class="nb">import</span> <span
class="n">org</span><span class="o">.</span><span class="n">apache</span><span
class="o">.</span><span class="n">felix</span><span class="o">.</span><span
class="n">scr</span><span class="o">.</span><span
class="n">annotations</span><span class="o">.</span><span
class="n">Component</span><span class="p">;</span>
+<span class="nb">import</span> <span class="n">org</span><span
class="o">.</span><span class="n">apache</span><span class="o">.</span><span
class="n">felix</span><span class="o">.</span><span class="n">scr</span><span
class="o">.</span><span class="n">annotations</span><span
class="o">.</span><span class="n">Service</span><span class="p">;</span>
+<span class="nb">import</span> <span class="n">org</span><span
class="o">.</span><span class="n">apache</span><span class="o">.</span><span
class="n">sling</span><span class="o">.</span><span
class="n">discovery</span><span class="o">.</span><span
class="n">PropertyProvider</span><span class="p">;</span>
+
+<span class="nv">@Service</span><span class="p">(</span><span
class="n">value</span> <span class="o">=</span> <span class="p">{</span> <span
class="n">PropertyProvider</span><span class="o">.</span><span
class="n">class</span> <span class="p">})</span>
+<span class="nv">@Properties</span><span class="p">({</span> <span
class="nv">@Property</span><span class="p">(</span><span class="n">name</span>
<span class="o">=</span> <span class="n">PropertyProvider</span><span
class="o">.</span><span class="n">PROPERTY_PROPERTIES</span><span
class="p">,</span> <span class="n">value</span> <span class="o">=</span> <span
class="p">{</span>
+ <span class="s">"sample.value1"</span><span
class="p">,</span> <span class="s">"sample.value2"</span> <span
class="p">})</span> <span class="p">})</span>
+<span class="n">public</span> <span class="n">class</span> <span
class="n">SamplePropertyProvider</span> <span class="n">implements</span> <span
class="n">PropertyProvider</span> <span class="p">{</span>
+
+ <span class="n">public</span> <span class="n">String</span> <span
class="n">getProperty</span><span class="p">(</span><span
class="n">final</span> <span class="n">String</span> <span
class="n">name</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span
class="s">"sample.value1"</span><span class="o">.</span><span
class="n">equals</span><span class="p">(</span><span class="n">name</span><span
class="p">))</span> <span class="p">{</span>
+ <span class="k">return</span> <span
class="s">"foo"</span><span class="p">;</span>
+ <span class="p">}</span> <span class="k">else</span> <span
class="k">if</span> <span class="p">(</span><span
class="s">"sample.value2"</span><span class="o">.</span><span
class="n">equals</span><span class="p">(</span><span class="n">name</span><span
class="p">))</span> <span class="p">{</span>
+ <span class="k">return</span> <span
class="s">"bar"</span><span class="p">;</span>
+ <span class="p">}</span> <span class="k">else</span> <span
class="p">{</span>
+ <span class="k">return</span> <span class="n">null</span><span
class="p">;</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h2 id="deployment-configuration">Deployment, Configuration</h2>
+<p>The discovery API makes no assumptions as to how the instances and clusters
discovery each other. This is entirely
+up to the implementations. Some might choose to automatic discovery within a
local LAN using IP multicast, some
+might choose to explicit configuration with a central service etc.</p>
+<h2 id="discoveryimpl-resource-based-ootb-implementation">discovery.impl:
Resource-based, OOTB Implementation</h2>
+<p>The <code>discovery.impl</code> is a resource-based, out of the box
implementation using standard Sling. The discovery within
+a cluster is done by writing heartbeat information into the (common)
repository. The establishment of a clusterview
+is done by analyzing these heartbeats, initiating a voting within the cluster
(such that each instance can agree
+that it sees the same number of instances) and by concluding the voting by
promoting it as the new "established" view.</p>
+<h3 id="location-in-repository">Location in Repository</h3>
+<p>Administrative note: All the information about the topology is stored at
the following location in the repository:</p>
+<div class="codehilite"><pre><span class="sr">/var/</span><span
class="n">discovery</span><span class="o">/</span><span class="n">impl</span>
+</pre></div>
+
+
+<h3 id="connectors">Connectors</h3>
+<p>The announcement "cross-cluster" is done via HTTP(s) heartbeats between
(arbitrary) cluster instances. These HTTP-heartbeats
+(internally termed <code>connectors</code>) must be configured <a
href="http://localhost:4502/system/console/configMgr/org.apache.sling.discovery.impl.Config";>here</a>.</p>
+<h3 id="webconsole">WebConsole</h3>
+<p>There is a Felix-based WebConsole that provides a (read-only) overview of
the topology.
+It can be found here: <a
href="http://localhost:4502/system/console/topology";>http://localhost:4502/system/console/topology</a>.</p>
+<h3 id="configuration">Configuration</h3>
+<p>The following properties can be configured (<a
href="http://localhost:4502/system/console/configMgr/org.apache.sling.discovery.impl.Config";>here</a>):</p>
+<ul>
+<li>
+<p>heartbeatInterval: the time in seconds between two heartbeats (both
cluster-internal and for HTTP-connectors). Default
+ value is 15 seconds.</p>
+</li>
+<li>
+<p>heartbeatTimeout: the time in seconds after which an instance is considered
dead if no heartbeat was sent since. Default
+ value is 20 seconds.</p>
+</li>
+<li>
+<p>topologyConnectorUrls: a list of connector URLs to which this instance
should connect to. The list can contain multiple
+ instances of the same cluster (for fallback configurations). If the list is
empty, no connector will be created.
+ The default relative URL is /libs/sling/topology/connector. Note that this
URL is accessible without authentication -
+ to avoid having to configure administrative username/passwords in all
instances. Instead, a whitelist approach is used
+ (see next item).</p>
+</li>
+<li>
+<p>topologyConnectorWhitelist: As mentioned above, the path
/libs/sling/topology/connector does not require authentication.
+ To assure that only trusted instances can connect to the topology, its
hostname or IP address must be in a whitelist.
+ By default this whitelist only contains localhost and 127.0.0.1.</p>
+</li>
+<li>
+<p>minEventDelay: To reduce the number of events sent during changes, there is
a delay (in seconds) before the event is sent.
+ If additional changes happen during this delay, the change will be combined
in one event.</p>
+</li>
+<li>
+<p>leaderElectionRepositoryDescriptor: this is an advanced parameter. It
denotes a repository descriptor that is evaluated
+ and taken into account for leader Election: the corresponding value of the
descriptor is sorted by first.</p>
+</li>
+</ul>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
+ Rev. 1485160 by stefanegli on Wed, 22 May 2013 11:39:14 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
+ logo are trademarks of The Apache Software Foundation. All other marks
mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
