|
@@ -1,8 +1,8 @@
|
|
[[creating-stable-plugins]]
|
|
[[creating-stable-plugins]]
|
|
=== Creating text analysis plugins with the stable plugin API
|
|
=== 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].
|
|
|
|
|
|
+Text analysis plugins provide {es} with custom {ref}/analysis.html[Lucene
|
|
|
|
+analyzers, token filters, character filters, and tokenizers].
|
|
|
|
|
|
[discrete]
|
|
[discrete]
|
|
==== The stable plugin API
|
|
==== The stable plugin API
|
|
@@ -10,7 +10,7 @@ analyzers, token filters, character filters, and tokenizers].
|
|
Text analysis plugins can be developed against the stable plugin API. This API
|
|
Text analysis plugins can be developed against the stable plugin API. This API
|
|
consists of the following dependencies:
|
|
consists of the following dependencies:
|
|
|
|
|
|
-* `plugin-api` - an API used by plugin developers to implement custom {es}
|
|
|
|
|
|
+* `plugin-api` - an API used by plugin developers to implement custom {es}
|
|
plugins.
|
|
plugins.
|
|
* `plugin-analysis-api` - an API used by plugin developers to implement analysis
|
|
* `plugin-analysis-api` - an API used by plugin developers to implement analysis
|
|
plugins and integrate them into {es}.
|
|
plugins and integrate them into {es}.
|
|
@@ -18,7 +18,7 @@ plugins and integrate them into {es}.
|
|
core Lucene analysis interfaces like `Tokenizer`, `Analyzer`, and `TokenStream`.
|
|
core Lucene analysis interfaces like `Tokenizer`, `Analyzer`, and `TokenStream`.
|
|
|
|
|
|
For new versions of {es} within the same major version, plugins built against
|
|
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
|
|
|
|
|
|
+this API does not need to be recompiled. Future versions of the API will be
|
|
backwards compatible and plugins are binary compatible with future versions of
|
|
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
|
|
{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.
|
|
you upgrade {es} to a new bugfix or minor version.
|
|
@@ -48,9 +48,9 @@ require code changes.
|
|
|
|
|
|
Stable plugins are ZIP files composed of JAR files and two metadata files:
|
|
Stable plugins are ZIP files composed of JAR files and two metadata files:
|
|
|
|
|
|
-* `stable-plugin-descriptor.properties` - a Java properties file that describes
|
|
|
|
|
|
+* `stable-plugin-descriptor.properties` - a Java properties file that describes
|
|
the plugin. Refer to <<plugin-descriptor-file-{plugin-type}>>.
|
|
the plugin. Refer to <<plugin-descriptor-file-{plugin-type}>>.
|
|
-* `named_components.json` - a JSON file mapping interfaces to key-value pairs
|
|
|
|
|
|
+* `named_components.json` - a JSON file mapping interfaces to key-value pairs
|
|
of component names and implementation classes.
|
|
of component names and implementation classes.
|
|
|
|
|
|
Note that only JAR files at the root of the plugin are added to the classpath
|
|
Note that only JAR files at the root of the plugin are added to the classpath
|
|
@@ -65,7 +65,7 @@ you use this plugin. However, you don't need Gradle to create plugins.
|
|
|
|
|
|
The {es} Github repository contains
|
|
The {es} Github repository contains
|
|
{es-repo}tree/main/plugins/examples/stable-analysis[an example analysis plugin].
|
|
{es-repo}tree/main/plugins/examples/stable-analysis[an example analysis plugin].
|
|
-The example `build.gradle` build script provides a good starting point for
|
|
|
|
|
|
+The example `build.gradle` build script provides a good starting point for
|
|
developing your own plugin.
|
|
developing your own plugin.
|
|
|
|
|
|
[discrete]
|
|
[discrete]
|
|
@@ -77,29 +77,29 @@ Plugins are written in Java, so you need to install a Java Development Kit
|
|
[discrete]
|
|
[discrete]
|
|
===== Step by step
|
|
===== Step by step
|
|
|
|
|
|
-. Create a directory for your project.
|
|
|
|
|
|
+. Create a directory for your project.
|
|
. Copy the example `build.gradle` build script to your project directory. Note
|
|
. Copy the example `build.gradle` build script to your project directory. Note
|
|
that this build script uses the `elasticsearch.stable-esplugin` gradle plugin to
|
|
that this build script uses the `elasticsearch.stable-esplugin` gradle plugin to
|
|
build your plugin.
|
|
build your plugin.
|
|
. Edit the `build.gradle` build script:
|
|
. 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
|
|
|
|
|
|
+** 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].
|
|
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
|
|
|
|
|
|
+** 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.
|
|
<<plugin-descriptor-file-{plugin-type}>> to create the file manually.
|
|
** Add module information.
|
|
** 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
|
|
|
|
|
|
+** Ensure you have declared the following compile-time dependencies. These
|
|
|
|
+dependencies are compile-time only because {es} will provide these libraries at
|
|
runtime.
|
|
runtime.
|
|
*** `org.elasticsearch.plugin:elasticsearch-plugin-api`
|
|
*** `org.elasticsearch.plugin:elasticsearch-plugin-api`
|
|
*** `org.elasticsearch.plugin:elasticsearch-plugin-analysis-api`
|
|
*** `org.elasticsearch.plugin:elasticsearch-plugin-analysis-api`
|
|
*** `org.apache.lucene:lucene-analysis-common`
|
|
*** `org.apache.lucene:lucene-analysis-common`
|
|
-** For unit testing, ensure these dependencies have also been added to the
|
|
|
|
|
|
+** For unit testing, ensure these dependencies have also been added to the
|
|
`build.gradle` script as `testImplementation` dependencies.
|
|
`build.gradle` script as `testImplementation` dependencies.
|
|
-. Implement an interface from the analysis plugin API, annotating it with
|
|
|
|
|
|
+. Implement an interface from the analysis plugin API, annotating it with
|
|
`NamedComponent`. Refer to <<example-text-analysis-plugin>> for an example.
|
|
`NamedComponent`. Refer to <<example-text-analysis-plugin>> for an example.
|
|
. You should now be able to assemble a plugin ZIP file by running:
|
|
. You should now be able to assemble a plugin ZIP file by running:
|
|
+
|
|
+
|
|
@@ -107,22 +107,22 @@ runtime.
|
|
----
|
|
----
|
|
gradle bundlePlugin
|
|
gradle bundlePlugin
|
|
----
|
|
----
|
|
-The resulting plugin ZIP file is written to the `build/distributions`
|
|
|
|
|
|
+The resulting plugin ZIP file is written to the `build/distributions`
|
|
directory.
|
|
directory.
|
|
|
|
|
|
[discrete]
|
|
[discrete]
|
|
===== YAML REST tests
|
|
===== 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].
|
|
|
|
|
|
+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
|
|
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
|
|
|
|
|
|
+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:
|
|
follows:
|
|
|
|
|
|
-* A test suite class, defined under `src/yamlRestTest/java`. This class should
|
|
|
|
|
|
+* A test suite class, defined under `src/yamlRestTest/java`. This class should
|
|
extend `ESClientYamlSuiteTestCase`.
|
|
extend `ESClientYamlSuiteTestCase`.
|
|
-* The YAML tests themselves should be defined under
|
|
|
|
|
|
+* The YAML tests themselves should be defined under
|
|
`src/yamlRestTest/resources/test/`.
|
|
`src/yamlRestTest/resources/test/`.
|
|
|
|
|
|
[[plugin-descriptor-file-stable]]
|
|
[[plugin-descriptor-file-stable]]
|