Author: bdelacretaz
Date: Wed May 22 12:26:37 2013
New Revision: 1485185
URL: http://svn.apache.org/r1485185
Log:
Fix a few typos and minor rewordings
Modified:
sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext
Modified:
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=1485185&r1=1485184&r2=1485185&view=diff
==============================================================================
---
sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext
(original)
+++
sling/site/trunk/content/documentation/bundles/discovery-api-and-impl.mdtext
Wed May 22 12:26:37 2013
@@ -1,8 +1,8 @@
-Title: Discovery API and its Implementations
+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.
+In many situations a particular Sling-based deployment consists of several
Sling instances:
+typically a number of instances would form a `cluster` that share a common
content 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
@@ -12,9 +12,9 @@ instances) and contains a simple propert
## Topology
-The topology - or more precisely the `TopologyView` - represents a snapshot
(`view`) of a number of loosely-coupled Sling instances (`InstanceDescription`)
+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).
+is always part of a cluster (even if the cluster consists of only 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)
@@ -34,17 +34,19 @@ to distribute "singleton" work amongst t
## Topology Changes
-The `DiscoveryService` provides access to the currently valid `TopologyView`.
Additionally applications can
+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,
+service detects that an instance is no longer responding 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
+settling the change within the topology (i.e. making sure everybody else in
the topology agrees with 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:
+The following is an example of a listener. Note that the binding is done
automatically by OSGi, as soon as a
+`TopologyEventListener` is registered.
import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Service;
@@ -65,15 +67,16 @@ The following is an example of a listene
## 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
+mechanism for announcing properties of each instance to the topology, via the
`PropertyProvider` service interface.
+
+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.
+Note that the properties mechanism is not meant 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. It is only
+meant to 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:
+The following is an example of a `PropertyProvider` that provides
`sample.value1` and `sample.value2` properties:
import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Service;
@@ -95,15 +98,15 @@ The following is an example of a Propert
}
}
-## Deployment, Configuration
+## Deployment and 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.
+up to the implementations. Some might choose automatic discovery within a LAN
using IP multicast, others
+might choose explicit configuration via 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
+The `discovery.impl` bundle 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.
@@ -116,17 +119,16 @@ Administrative note: All the information
### 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].
+The "cross-cluster" announcement is done via HTTP(s) heartbeats between
(arbitrary) cluster instances. These HTTP heartbeats
+(internally termed `connectors`) are configured at
[/system/console/configMgr/org.apache.sling.discovery.impl.Config][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].
+A Felix WebConsole plugin at [/system/console/topology][2] provides a
(read-only) overview of the topology.
### Configuration
-The following properties can be configured ([here][1]):
+The following properties can be configured (at
[/system/console/configMgr/org.apache.sling.discovery.impl.Config][1]):
* heartbeatInterval: the time in seconds between two heartbeats (both
cluster-internal and for HTTP-connectors). Default
value is 15 seconds.
@@ -150,5 +152,5 @@ The following properties can be configur
* 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
+ [1]:
http://localhost:8888/system/console/configMgr/org.apache.sling.discovery.impl.Config
+ [2]: http://localhost:8888/system/console/topology
\ No newline at end of file
