Apache Solr open-source search software
SOLR-14749: Restructure the docs + add some examples.
Andrzej Bialecki0bfa2a690857
diff --git a/solr/dev-docs/plugins/container-plugins.adoc b/solr/dev-docs/plugins/container-plugins.adocindex b10ba4b42bd..a2604329a20 100644--- a/solr/dev-docs/plugins/container-plugins.adoc+++ b/solr/dev-docs/plugins/container-plugins.adoc@@ -15,10 +15,20 @@ additional functionality at the Solr node level.=== Plugin configurationsPlugin 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, andvalues 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-cyclePlugin 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 registraimplement `org.apache.solr.api.ContainerPluginsRegistry.PluginRegistryListener` and registerit 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 pluginsPlugins that implement `ClusterSingleton` interface are instantiated on eachSolr 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 thatit requires this cluster singleton behavior.-// explain plugins that register Api-s-// explain plugins that don't implement any Api=== ClusterEventProducer pluginIn 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 ofcluster 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 pluginsPlugins that implement the `ClusterEventListener` interface will be automaticallyregistered with the instance of `ClusterEventProducer`.-== Plugin management API+// 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.-== Predefined plugin names+==== 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.-Plugins with these names are used in specific parts of Solr. Their names are reserved-and cannot be used for other plugin types:+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.-// 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.+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-`cluster-event-producer`::-plugin that implements `ClusterEventProducer` interface. This type of plugin-is used for generating cluster-level events.\ No newline at end of file