mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-29 01:44:36 -04:00
[DOCS] Documentation update for creating plugins (#93413)
* [DOCS] Documentation for the stable plugin API * Removed references to rivers * Add link to Cloud docs for managing plugins * Add caveat about needing to update plugins * Remove reference to site plugins * Wording and clarifications * Fix test * Add link to text analysis docs * Text analysis API dependencies * Remove reference to REST endpoints and fix list * Move plugin descriptor file to its own page * Typos * Review feedback * Delete unused properties file * Changed into * Changed 'elasticsearchVersion' into 'pluginApiVersion' * Swap 'The analysis plugin API' and 'Plugin file structure' sections * Update docs/plugins/authors.asciidoc Co-authored-by: Arianna Laudazzi <46651782+alaudazzi@users.noreply.github.com> * Update docs/plugins/development/creating-non-text-analysis-plugins.asciidoc Co-authored-by: Arianna Laudazzi <46651782+alaudazzi@users.noreply.github.com> * Update docs/plugins/development/creating-non-text-analysis-plugins.asciidoc Co-authored-by: Arianna Laudazzi <46651782+alaudazzi@users.noreply.github.com> * Update docs/plugins/development/creating-text-analysis-plugins.asciidoc Co-authored-by: Arianna Laudazzi <46651782+alaudazzi@users.noreply.github.com> * Update docs/plugins/development/creating-text-analysis-plugins.asciidoc Co-authored-by: Arianna Laudazzi <46651782+alaudazzi@users.noreply.github.com> * Update docs/plugins/development/creating-non-text-analysis-plugins.asciidoc Co-authored-by: Arianna Laudazzi <46651782+alaudazzi@users.noreply.github.com> * Update docs/plugins/development/creating-text-analysis-plugins.asciidoc Co-authored-by: Arianna Laudazzi <46651782+alaudazzi@users.noreply.github.com> * Update docs/plugins/development/creating-text-analysis-plugins.asciidoc Co-authored-by: Arianna Laudazzi <46651782+alaudazzi@users.noreply.github.com> * Update docs/plugins/development/example-text-analysis-plugin.asciidoc Co-authored-by: Arianna Laudazzi <46651782+alaudazzi@users.noreply.github.com> * Update docs/plugins/development/plugin-descriptor-file.asciidoc Co-authored-by: Arianna Laudazzi <46651782+alaudazzi@users.noreply.github.com> * Update docs/plugins/plugin-script.asciidoc Co-authored-by: Arianna Laudazzi <46651782+alaudazzi@users.noreply.github.com> * Update docs/plugins/development/creating-non-text-analysis-plugins.asciidoc Co-authored-by: Arianna Laudazzi <46651782+alaudazzi@users.noreply.github.com> * Update docs/plugins/development/creating-non-text-analysis-plugins.asciidoc Co-authored-by: Arianna Laudazzi <46651782+alaudazzi@users.noreply.github.com> * Rewording * Add modulename and extended.plugins descriptions for descriptor file * Add link to existing plugins in Github * Review feedback * Use 'stable' and 'classic' plugin naming * Fix capitalization * Review feedback --------- Co-authored-by: Arianna Laudazzi <46651782+alaudazzi@users.noreply.github.com> Co-authored-by: William Brafford <william.brafford@elastic.co>
This commit is contained in:
Abdon Pijpelink
GitHub
parent
c46d7e7b01
commit
f93a94009f
29 changed files with 585 additions and 169 deletions
131
docs/plugins/development/creating-stable-plugins.asciidoc
Normal file
131
docs/plugins/development/creating-stable-plugins.asciidoc
Normal file
|
|
@ -0,0 +1,131 @@
|
|||
[[creating-stable-plugins]]
|
||||
=== Creating text analysis plugins with the stable plugin API
|
||||
|
||||
Text analysis plugins provide {es} with custom {ref}/analysis.html[Lucene
|
||||
analyzers, token filters, character filters, and tokenizers].
|
||||
|
||||
[discrete]
|
||||
==== The stable plugin API
|
||||
|
||||
Text analysis plugins can be developed against the stable plugin API. This API
|
||||
consists of the following dependencies:
|
||||
|
||||
* `plugin-api` - an API used by plugin developers to implement custom {es}
|
||||
plugins.
|
||||
* `plugin-analysis-api` - an API used by plugin developers to implement analysis
|
||||
plugins and integrate them into {es}.
|
||||
* `lucene-analysis-common` - a dependency of `plugin-analysis-api` that contains
|
||||
core Lucene analysis interfaces like `Tokenizer`, `Analyzer`, and `TokenStream`.
|
||||
|
||||
For new versions of {es} within the same major version, plugins built against
|
||||
this API do not need to be recompiled. Future versions of the API will be
|
||||
backwards compatible and plugins are binary compatible with future versions of
|
||||
{es}. In other words, once you have a working artifact, you can re-use it when
|
||||
you upgrade {es} to a new bugfix or minor version.
|
||||
|
||||
A text analysis plugin can implement four factory classes that are provided by
|
||||
the analysis plugin API.
|
||||
|
||||
* `AnalyzerFactory` to create a Lucene analyzer
|
||||
* `CharFilterFactory` to create a character character filter
|
||||
* `TokenFilterFactory` to create a Lucene token filter
|
||||
* `TokenizerFactory` to create a Lucene tokenizer
|
||||
|
||||
The key to implementing a stable plugin is the `@NamedComponent` annotation.
|
||||
Many of {es}'s components have names that are used in configurations. For
|
||||
example, the keyword analyzer is referenced in configuration with the name
|
||||
`"keyword"`. Once your custom plugin is installed in your cluster, your named
|
||||
components may be referenced by name in these configurations as well.
|
||||
|
||||
You can also create text analysis plugins as a <<creating-classic-plugins,
|
||||
classic plugin>>. However, classic plugins are pinned to a specific version of
|
||||
{es}. You need to recompile them when upgrading {es}. Because classic plugins
|
||||
are built against internal APIs that can change, upgrading to a new version may
|
||||
require code changes.
|
||||
|
||||
[discrete]
|
||||
==== Stable plugin file structure
|
||||
|
||||
Stable plugins are ZIP files composed of JAR files and two metadata files:
|
||||
|
||||
* `stable-plugin-descriptor.properties` - a Java properties file that describes
|
||||
the plugin. Refer to <<plugin-descriptor-file-{plugin-type}>>.
|
||||
* `named_components.json` - a JSON file mapping interfaces to key-value pairs
|
||||
of component names and implementation classes.
|
||||
|
||||
Note that only JAR files at the root of the plugin are added to the classpath
|
||||
for the plugin. If you need other resources, package them into a resources JAR.
|
||||
|
||||
[discrete]
|
||||
==== Development process
|
||||
|
||||
Elastic provides a Grade plugin, `elasticsearch.stable-esplugin`, that makes it
|
||||
easier to develop and package stable plugins. The steps in this section assume
|
||||
you use this plugin. However, you don't need Gradle to create plugins.
|
||||
|
||||
The {es} Github repository contains
|
||||
{es-repo}tree/main/plugins/examples/stable-analysis[an example analysis plugin].
|
||||
The example `build.gradle` build script provides a good starting point for
|
||||
developing your own plugin.
|
||||
|
||||
[discrete]
|
||||
===== Prerequisites
|
||||
|
||||
Plugins are written in Java, so you need to install a Java Development Kit
|
||||
(JDK). Install Gradle if you want to use Gradle.
|
||||
|
||||
[discrete]
|
||||
===== Step by step
|
||||
|
||||
. Create a directory for your project.
|
||||
. Copy the example `build.gradle` build script to your project directory. Note
|
||||
that this build script uses the `elasticsearch.stable-esplugin` gradle plugin to
|
||||
build your plugin.
|
||||
. Edit the `build.gradle` build script:
|
||||
** Add a definition for the `pluginApiVersion` and matching `luceneVersion`
|
||||
variables to the top of the file. You can find these versions in the
|
||||
`build-tools-internal/version.properties` file in the {es-repo}[Elasticsearch
|
||||
Github repository].
|
||||
** Edit the `name` and `description` in the `esplugin` section of the build
|
||||
script. This will create the plugin descriptor file. If you're not using the
|
||||
`elasticsearch.stable-esplugin` gradle plugin, refer to
|
||||
<<plugin-descriptor-file-{plugin-type}>> to create the file manually.
|
||||
** Add module information.
|
||||
** Ensure you have declared the following compile-time dependencies. These
|
||||
dependencies are compile-time only because {es} will provide these libraries at
|
||||
runtime.
|
||||
*** `org.elasticsearch.plugin:elasticsearch-plugin-api`
|
||||
*** `org.elasticsearch.plugin:elasticsearch-plugin-analysis-api`
|
||||
*** `org.apache.lucene:lucene-analysis-common`
|
||||
** For unit testing, ensure these dependencies have also been added to the
|
||||
`build.gradle` script as `testImplementation` dependencies.
|
||||
. Implement an interface from the analysis plugin API, annotating it with
|
||||
`NamedComponent`. Refer to <<example-text-analysis-plugin>> for an example.
|
||||
. You should now be able to assemble a plugin ZIP file by running:
|
||||
+
|
||||
[source,sh]
|
||||
----
|
||||
gradle bundlePlugin
|
||||
----
|
||||
The resulting plugin ZIP file is written to the `build/distributions`
|
||||
directory.
|
||||
|
||||
[discrete]
|
||||
===== YAML REST tests
|
||||
|
||||
The Gradle `elasticsearch.yaml-rest-test` plugin enables testing of your
|
||||
plugin using the {es-repo}blob/main/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/README.asciidoc[{es} yamlRestTest framework].
|
||||
These tests use a YAML-formatted domain language to issue REST requests against
|
||||
an internal {es} cluster that has your plugin installed, and to check the
|
||||
results of those requests. The structure of a YAML REST test directory is as
|
||||
follows:
|
||||
|
||||
* A test suite class, defined under `src/yamlRestTest/java`. This class should
|
||||
extend `ESClientYamlSuiteTestCase`.
|
||||
* The YAML tests themselves should be defined under
|
||||
`src/yamlRestTest/resources/test/`.
|
||||
|
||||
[[plugin-descriptor-file-stable]]
|
||||
==== The plugin descriptor file for stable plugins
|
||||
|
||||
include::plugin-descriptor-file.asciidoc[]
|
||||
Loading…
Add table
Add a link
Reference in a new issue