incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r862731 - in /websites/staging/sling/trunk/content: ./ documentation/bundles.html documentation/bundles/discovery-api-and-impl.html
Date Wed, 22 May 2013 11:39:24 GMT
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 &amp; 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>&nbsp;&raquo&nbsp;<a href="/documentation.html">Documentation</a>&nbsp;&raquo&nbsp;<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">&quot;sample.value1&quot;</span><span class="p">,</span>
<span class="s">&quot;sample.value2&quot;</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">&quot;sample.value1&quot;</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">&quot;foo&quot;</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">&quot;sample.value2&quot;</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">&quot;bar&quot;</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>



Mime
View raw message