Skip to content

armgit / solr

Public Imported from GitHub
0

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.adoc
index 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 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`.
-== 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