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

[st...@apache.org]

Author: stefanegli
Date: Wed May 22 11:39:14 2013
New Revision: 1485160

URL: http://svn.apache.org/r1485160
Log:
SLING-2827 : added discovery.api and .impl[s] documentation

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

Modified: sling/site/trunk/content/documentation/bundles.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles.mdtext?rev=1485160&r1=1485159&r2=1485160&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles.mdtext Wed May 22 11:39:14 2013
@@ -30,3 +30,4 @@ Title: Bundles
 * [Sling Health Check Tool]({{ refs.sling-health-check-tool.path }})
 * [Scheduler Service (commons scheduler)]({{ refs.scheduler-service-commons-scheduler.path }})
 * [Web Console Extensions (org.apache.sling.extensions.webconsolebranding, org.apache.sling.extensions.webconsolesecurityprovider)]({{ refs.web-console-extensions.path }})
+* [Discovery API and Resource Based Implementation (discovery.api, discovery.impl)]({{ refs.discovery-api-and-impl.path }})

Added: 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=1485160&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext (added)
+++ sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext Wed May 22 11:39:14 2013
@@ -0,0 +1,152 @@
+Title: Discovery API and its Implementations
+
+In many situations a particular Sling-based deployment consists of more than one Sling-instances:
+typically a number of instances would form a `cluster` that share a common repository - 
+in other situations, or additionally, instances might be loosely-coupled, each with their own repository.
+
+The `discovery-api` bundle introduces an abstraction for such scenarios called `topology`. 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.
+
+## Topology
+
+The topology - or more precisely the `TopologyView` - represents a snapshot (`view`) of a number of loosely-coupled Sling instances (`InstanceDescription`)
+and clusters (`ClusterView`) 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.
+
+## Cluster Leader and Instance Ordering
+
+The discovery API introduces support for a `cluster leader`: within each cluster, the API guarantees that one and only one
+instance is leader at any time. That leader is guaranteed to be `stable`, 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.
+
+Additionally each cluster (`ClusterView`) 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. 
+
+## Topology Changes
+
+The `DiscoveryService` provides access to the currently valid `TopologyView`. Additionally applications can 
+register a `TopologyEventListener` 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 `TOPOLOGY_CHANGING` event, starts
+settling the change within the topology (ie making sure everybody else in the topology agrees on the change) and finally
+sends a `TOPOLOGY_CHANGED` event with the new topology.
+Additionally, when "only" properties have changed, a `PROPERTIES_CHANGED` event is sent.
+
+Note that the detection of topology (or properties) changes will incur a delay which is implementation dependent.
+
+The following is an example of a listener - note that the binding is done automatically by OSGi:
+
+	import org.apache.felix.scr.annotations.Component;
+	import org.apache.felix.scr.annotations.Service;
+	import org.apache.sling.discovery.TopologyEvent;
+	import org.apache.sling.discovery.TopologyEventListener;
+
+	@Component(immediate = true)
+	@Service(value = { TopologyEventListener.class })
+	public class MyTopologyEventListener implements TopologyEventListener {
+	
+	    public void handleTopologyEvent(final TopologyEvent event) {
+	    	// your code here
+	    }
+	
+	}
+
+
+## Properties
+
+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 `PropertyProvider`.
+Typical use cases for this are announcements of endpoint-URLs or ports such that applications can communicate to other
+instances in the topology.
+
+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.
+
+The following is an example of a PropertyProvider, providing `sample.value1` and `sample.value2` properties:
+
+	import org.apache.felix.scr.annotations.Component;
+	import org.apache.felix.scr.annotations.Service;
+	import org.apache.sling.discovery.PropertyProvider;
+
+	@Service(value = { PropertyProvider.class })
+	@Properties({ @Property(name = PropertyProvider.PROPERTY_PROPERTIES, value = {
+	        "sample.value1", "sample.value2" }) })
+	public class SamplePropertyProvider implements PropertyProvider {
+	
+		public String getProperty(final String name) {
+			if ("sample.value1".equals(name)) {
+				return "foo";
+			} else if ("sample.value2".equals(name)) {
+				return "bar";
+			} else {
+				return null;
+			}
+		}
+	}
+
+## Deployment, Configuration
+
+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.
+
+## discovery.impl: Resource-based, OOTB Implementation
+
+The `discovery.impl` 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.
+
+### Location in Repository
+
+Administrative note: All the information about the topology is stored at the following location in the repository:
+
+	/var/discovery/impl
+
+### Connectors
+
+The announcement "cross-cluster" is done via HTTP(s) heartbeats between (arbitrary) cluster instances. These HTTP-heartbeats
+(internally termed `connectors`) must be configured [here][1].
+
+### WebConsole
+
+There is a Felix-based WebConsole that provides a (read-only) overview of the topology.
+It can be found here: [http://localhost:4502/system/console/topology][2].
+
+### Configuration
+
+The following properties can be configured ([here][1]):
+
+ * heartbeatInterval: the time in seconds between two heartbeats (both cluster-internal and for HTTP-connectors). Default
+   value is 15 seconds.
+   
+ * heartbeatTimeout: the time in seconds after which an instance is considered dead if no heartbeat was sent since. Default
+   value is 20 seconds.
+   
+ * 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).
+   
+ * 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.
+   
+ * 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.
+   
+ * 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.
+
+  [1]: http://localhost:4502/system/console/configMgr/org.apache.sling.discovery.impl.Config
+  [2]: http://localhost:4502/system/console/topology
\ No newline at end of file