SOLR-14749: Restructure the docs + add some examples.

solr/dev-docs/plugins/container-plugins.adoc

@@ -15,10 +15,20 @@ additional functionality at the Solr node level.
 
 === Plugin configurations
 Plugin configurations are maintained in ZooKeeper in the `/clusterprops.json` file, under
-the `plugin` entry. The configuration is a JSON map where keys are the plugin names, and
+the `plugin` entry. The configuration is a JSON map where keys are the unique plugin names, and
 values are serialized `org.apache.solr.client.solrj.request.beans.PluginMeta` beans.
 
-== Types of container plugins
+=== Types of container plugins
+Typically classes loaded from plugins support two types of functionality (not mutually exclusive):
+
+* plugins that expose REST API endpoints (the implementing class is annotated with
+`@EndPoint` and optionally `@Command` annotations). The APIs of these plugins are automatically
+registered as REST endpoints under the paths defined in the `@EndPoint` annotations.
+
+* plugins that implement a specific interface. Upon loading they are automatically
+discovered and registered with sub-systems that use this type of plugin. Examples here
+include the `ClusterSingleton`, ClusterEventProducer`, `ClusterEventListener`.
+// and `PlacementPluginConfig`
 
 === Plugin life-cycle
 Plugin instances are loaded and initialized when Solr's `CoreContainer` is first created.
@@ -36,6 +46,22 @@ Components that need to be aware of changes in plugin configurations or registra
 implement `org.apache.solr.api.ContainerPluginsRegistry.PluginRegistryListener` and register
 it with the instance of registry available from `coreContainer.getContainerPluginsRegistry()`.
 
+== Plugin types
+
+=== Predefined plugin names
+
+Plugins with these names are used in specific parts of Solr. Their names are reserved
+and cannot be used for other plugin types:
+
+// XXX uncomment when we move the config to plugins
+//`placement-plugin`::
+//plugin that implements `PlacementPlugin` interface. This type of plugin
+//determines the replica placement strategy in the cluster.
+
+`cluster-event-producer`::
+plugin that implements `ClusterEventProducer` interface. This type of plugin
+is used for generating cluster-level events.
+
 === ClusterSingleton plugins
 Plugins that implement `ClusterSingleton` interface are instantiated on each
 Solr node. However, their start/stop life-cycle, as defined in the interface,
@@ -48,8 +74,6 @@ is present in the cluster at any time.
 Any plugin type can implement this interface to indicate to Solr that
 it requires this cluster singleton behavior.
 
-// explain plugins that register Api-s
-// explain plugins that don't implement any Api
 === ClusterEventProducer plugin
 In order to support the generation of cluster-level events an implementation of
 `ClusterEventProducer` is created on each Solr node. This component is also a
@@ -57,25 +81,63 @@ In order to support the generation of cluster-level events an implementation of
 cluster at any time.
 
 If no plugin configuration is specified then the default implementation
-`org.apache.solr.cluster.events.impl.DefaultClusterEventProducer` is used. A no-op
-implementation is also available in `org.apache.solr.cluster.events.NoOpProducer`.
+`org.apache.solr.cluster.events.impl.NoOpProducer` is used, which doesn't generate
+any events - this means that by default event generation is turned off. An implementation
+that supports node and collection event generation is also available in
+`org.apache.solr.cluster.events.impl.DefaultClusterEventProducer`.
+
+Event producer configuration can be changed dynamically by changing the predefined
+plugin configuration, for example:
+
+[source,bash]
+----
+curl -X POST -H 'Content-type: application/json' -d '{
+    "add":{
+        "name": "cluster-event-producer",
+        "class": "org.apache.solr.cluster.events.impl.DefaultClusterEventProducer"
+    }}'
+  http://localhost:8983/api/cluster/plugin
+----
+
+It can be restored to the default no-op configuration by simply removing the plugin:
+
+[source,bash]
+----
+curl -X POST -H 'Content-type: application/json' -d '{
+    "remove": "cluster-event-producer"
+  }'
+  http://localhost:8983/api/cluster/plugin
+----
+
 
 === ClusterEventListener plugins
 Plugins that implement the `ClusterEventListener` interface will be automatically
 registered with the instance of `ClusterEventProducer`.
 
+// XXX edit this once SOLR-14977 is done
+Implementations will be notified of all events that are generated by the
+`ClusterEventProducer` and need to select only events that they are interested in.
+
+==== org.apache.solr.cluster.events.impl.CollectionsRepairEventListener
+An implementation of listener that reacts to NODE_LOST events and checks what replicas
+need to be re-added to other nodes to keep the replication counts the same as before.
+
+This implementation waits for a certain period (default is 30s) to make sure the node
+is really down, and for the replicas located on nodes that were down sufficiently long
+it generates appropriate ADDREPLICA commands to counter-balance the lost replicas on
+these nodes.
+
+Example plugin configuration:
+
+[source,bash]
+----
+curl -X POST -H 'Content-type: application/json' -d '{
+    "add":{
+        "name": "collections-repair-listener",
+        "class": "org.apache.solr.cluster.events.impl.CollectionsRepairEventListener"
+    }}'
+  http://localhost:8983/api/cluster/plugin
+----
+
 == Plugin management API
 
-== Predefined plugin names
-
-Plugins with these names are used in specific parts of Solr. Their names are reserved
-and cannot be used for other plugin types:
-
-// XXX uncomment when we move the config to plugins
-//`placement-plugin`::
-//plugin that implements `PlacementPlugin` interface. This type of plugin
-//determines the replica placement strategy in the cluster.
-
-`cluster-event-producer`::
-plugin that implements `ClusterEventProducer` interface. This type of plugin
-is used for generating cluster-level events.