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`. +// 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. \ No newline at end of file