Stable Plugin API modules and analysis interfaces (#88775)

This commit adds stable analysis plugin API with analysis components interfaces and annotations.
It does not contain any usage of it yet. Separate changes to introduce example plugins or refactoring to existing ones will follow later.

It contains two gradle modules. One plugin-api with two annotations Nameable and NamedComponent, which can be reused for plugins other than analysis.
And second analysis-plugin-api which contains analysis components (TokenFilterFactory, CharFilterFactory etc)

NamedComponent - used by plugin developer - indicates that a Nameable component will be registered under a given name.
Nameable - for analysis plugins it is only used by the stable analysis api designers (ES) - indicates that component have a name and should be declared with NamedComponent

additional tasks that will follow: #88980

libs/plugin-analysis-api/src/main/java/module-info.java

@@ -0,0 +1,14 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+module org.elasticsearch.analysis.plugin.api {
+    requires org.apache.lucene.core;
+    requires org.elasticsearch.plugin.api;
+
+    exports org.elasticsearch.plugin.analysis.api;
+}

libs/plugin-analysis-api/src/main/java/org/elasticsearch/plugin/analysis/api/AnalysisMode.java

@@ -0,0 +1,77 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+package org.elasticsearch.plugin.analysis.api;
+
+/**
+ * Enum representing the mode in which token filters and analyzers are allowed to operate.
+ * While most token filters are allowed both in index and search time analyzers, some are
+ * restricted to be used only at index time, others at search time.
+ */
+public enum AnalysisMode {
+
+    /**
+     * AnalysisMode representing analysis components that can be used only at index time.
+     */
+    INDEX_TIME("index time") {
+        @Override
+        public AnalysisMode merge(AnalysisMode other) {
+            if (other == AnalysisMode.SEARCH_TIME) {
+                throw new IllegalStateException("Cannot merge SEARCH_TIME and INDEX_TIME analysis mode.");
+            }
+            return AnalysisMode.INDEX_TIME;
+        }
+    },
+    /**
+     * AnalysisMode representing analysis components that can be used only at search time.
+     */
+    SEARCH_TIME("search time") {
+        @Override
+        public AnalysisMode merge(AnalysisMode other) {
+            if (other == AnalysisMode.INDEX_TIME) {
+                throw new IllegalStateException("Cannot merge SEARCH_TIME and INDEX_TIME analysis mode.");
+            }
+            return AnalysisMode.SEARCH_TIME;
+        }
+    },
+    /**
+     * AnalysisMode representing analysis components that can be used both at index and search time.
+     */
+    ALL("all") {
+        @Override
+        public AnalysisMode merge(AnalysisMode other) {
+            return other;
+        }
+    };
+
+    private final String readableName;
+
+    AnalysisMode(String name) {
+        this.readableName = name;
+    }
+
+    /**
+     * Returns a readable name of the analysis mode.
+     * @return a name of the analysis mode.
+     */
+    public String getReadableName() {
+        return this.readableName;
+    }
+
+    /**
+     * Returns a mode that is compatible with both this mode and the other mode, that is:
+     * <ul>
+     * <li>ALL.merge(INDEX_TIME) == INDEX_TIME</li>
+     * <li>ALL.merge(SEARCH_TIME) == SEARCH_TIME</li>
+     * <li>INDEX_TIME.merge(SEARCH_TIME) throws an {@link IllegalStateException}</li>
+     * </ul>
+     * @return merged AnalysisMode
+     * @throws IllegalStateException when  {@link #INDEX_TIME} is merged with {@link #SEARCH_TIME} (and vice versa)
+     */
+    public abstract AnalysisMode merge(AnalysisMode other);
+}

libs/plugin-analysis-api/src/main/java/org/elasticsearch/plugin/analysis/api/AnalyzerFactory.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+package org.elasticsearch.plugin.analysis.api;
+
+import org.apache.lucene.analysis.Analyzer;
+import org.elasticsearch.plugin.api.Nameable;
+
+/**
+ * An analysis component used to create Analyzers.
+ */
+public interface AnalyzerFactory extends Nameable {
+    /**
+     * Returns a lucene org.apache.lucene.analysis.Analyzer instance.
+     * @return an analyzer
+     */
+    Analyzer create();
+
+}

libs/plugin-analysis-api/src/main/java/org/elasticsearch/plugin/analysis/api/CharFilterFactory.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+package org.elasticsearch.plugin.analysis.api;
+
+import org.elasticsearch.plugin.api.Nameable;
+
+import java.io.Reader;
+
+/**
+ * An analysis component used to create char filters.
+ *
+ */
+public interface CharFilterFactory extends Nameable {
+    /**
+     * Wraps the given Reader with a CharFilter.
+     * @param reader reader to be wrapped
+     * @return a reader wrapped with CharFilter
+     */
+    Reader create(Reader reader);
+
+    /**
+     * Normalize a tokenStream for use in multi-term queries.
+     * The default implementation returns the given reader.
+     */
+    default Reader normalize(Reader reader) {
+        return reader;
+    }
+}

libs/plugin-analysis-api/src/main/java/org/elasticsearch/plugin/analysis/api/TokenFilterFactory.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+package org.elasticsearch.plugin.analysis.api;
+
+import org.apache.lucene.analysis.TokenStream;
+import org.elasticsearch.plugin.api.Nameable;
+
+/**
+ * An analysis component used to create token filters.
+ */
+public interface TokenFilterFactory extends Nameable {
+
+    /**
+     * Transform the specified input TokenStream.
+     * @param tokenStream a token stream to be transformed
+     * @return transformed token stream
+     */
+    TokenStream create(TokenStream tokenStream);
+
+    /**
+     * Normalize a tokenStream for use in multi-term queries.
+     * The default implementation returns a given token stream.
+     */
+    default TokenStream normalize(TokenStream tokenStream) {
+        return tokenStream;
+    }
+
+    /**
+     * Get the {@link AnalysisMode} this filter is allowed to be used in. The default is
+     * {@link AnalysisMode#ALL}. Instances need to override this method to define their
+     * own restrictions.
+     * @return analysis mode
+     */
+    default AnalysisMode getAnalysisMode() {
+        return AnalysisMode.ALL;
+    }
+
+}

libs/plugin-analysis-api/src/main/java/org/elasticsearch/plugin/analysis/api/TokenizerFactory.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+package org.elasticsearch.plugin.analysis.api;
+
+import org.apache.lucene.analysis.Tokenizer;
+import org.elasticsearch.plugin.api.Nameable;
+
+/**
+ * An analysis component used to create tokenizers.
+ */
+public interface TokenizerFactory extends Nameable {
+
+    /**
+     * Creates a Tokenizer instance.
+     * @return a tokenizer
+     */
+    Tokenizer create();
+}