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
