[BWC and API enforcement] Decorate the existing APIs with proper anno…

…tations (part 2) Signed-off-by: Andriy Redko <[email protected]>
opensearch-project · Nov 1, 2023 · 9b669ac · 9b669ac
1 parent 8673fa9
commit 9b669ac
Show file tree

Hide file tree

Showing 502 changed files with 1,762 additions and 576 deletions.
diff --git a/libs/common/src/main/java/org/opensearch/common/CheckedBiConsumer.java b/libs/common/src/main/java/org/opensearch/common/CheckedBiConsumer.java
@@ -32,13 +32,16 @@
 
 package org.opensearch.common;
 
+import org.opensearch.common.annotation.PublicApi;
+
 import java.util.function.BiConsumer;
 
 /**
  * A {@link BiConsumer}-like interface which allows throwing checked exceptions.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 @FunctionalInterface
 public interface CheckedBiConsumer<T, U, E extends Exception> {
     void accept(T t, U u) throws E;

diff --git a/libs/common/src/main/java/org/opensearch/common/CheckedFunction.java b/libs/common/src/main/java/org/opensearch/common/CheckedFunction.java
@@ -32,13 +32,16 @@
 
 package org.opensearch.common;
 
+import org.opensearch.common.annotation.PublicApi;
+
 import java.util.function.Function;
 
 /**
  * A {@link Function}-like interface which allows throwing checked exceptions.
  *
  * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 @FunctionalInterface
 public interface CheckedFunction<T, R, E extends Exception> {
     R apply(T t) throws E;

diff --git a/libs/common/src/main/java/org/opensearch/common/collect/Tuple.java b/libs/common/src/main/java/org/opensearch/common/collect/Tuple.java
@@ -32,12 +32,15 @@
 
 package org.opensearch.common.collect;
 
+import org.opensearch.common.annotation.PublicApi;
+
 /**
  * Java 9 Tuple
  * todo: deprecate and remove w/ min jdk upgrade to 11?
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class Tuple<V1, V2> {
 
     public static <V1, V2> Tuple<V1, V2> tuple(V1 v1, V2 v2) {

diff --git a/libs/common/src/main/java/org/opensearch/common/crypto/MasterKeyProvider.java b/libs/common/src/main/java/org/opensearch/common/crypto/MasterKeyProvider.java
@@ -7,12 +7,17 @@
  */
 package org.opensearch.common.crypto;
 
+import org.opensearch.common.annotation.ExperimentalApi;
+
 import java.io.Closeable;
 import java.util.Map;
 
 /**
  * Master key provider responsible for management of master keys.
+ *
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public interface MasterKeyProvider extends Closeable {
 
     /**

diff --git a/libs/common/src/main/java/org/opensearch/common/io/InputStreamContainer.java b/libs/common/src/main/java/org/opensearch/common/io/InputStreamContainer.java
@@ -8,13 +8,16 @@
 
 package org.opensearch.common.io;
 
+import org.opensearch.common.annotation.ExperimentalApi;
+
 import java.io.InputStream;
 
 /**
  * Model composed of an input stream and the total content length of the stream
  *
- * @opensearch.internal
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public class InputStreamContainer {
 
     private final InputStream inputStream;

diff --git a/libs/core/src/main/java/org/opensearch/OpenSearchException.java b/libs/core/src/main/java/org/opensearch/OpenSearchException.java
@@ -33,6 +33,7 @@
 
 import org.opensearch.common.CheckedFunction;
 import org.opensearch.common.Nullable;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.collect.Tuple;
 import org.opensearch.core.ParseField;
 import org.opensearch.core.common.Strings;
@@ -69,8 +70,9 @@
 /**
  * A core library base class for all opensearch exceptions.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class OpenSearchException extends RuntimeException implements Writeable, ToXContentFragment {
 
     protected static final Version UNKNOWN_VERSION_ADDED = Version.fromId(0);

diff --git a/libs/core/src/main/java/org/opensearch/OpenSearchParseException.java b/libs/core/src/main/java/org/opensearch/OpenSearchParseException.java
@@ -32,6 +32,7 @@
 
 package org.opensearch;
 
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.rest.RestStatus;
 
@@ -40,8 +41,9 @@
 /**
  * Unchecked exception that is translated into a {@code 400 BAD REQUEST} error when it bubbles out over HTTP.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class OpenSearchParseException extends OpenSearchException {
 
     public OpenSearchParseException(String msg, Object... args) {

diff --git a/libs/core/src/main/java/org/opensearch/core/common/transport/TransportAddress.java b/libs/core/src/main/java/org/opensearch/core/common/transport/TransportAddress.java
@@ -32,6 +32,7 @@
 
 package org.opensearch.core.common.transport;
 
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.network.NetworkAddress;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.common.io.stream.StreamOutput;
@@ -47,8 +48,9 @@
 /**
  * A transport address used for IP socket address (wraps {@link java.net.InetSocketAddress}).
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public final class TransportAddress implements Writeable, ToXContentFragment {
 
     /**

diff --git a/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/ResourceStats.java b/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/ResourceStats.java
@@ -8,11 +8,14 @@
 
 package org.opensearch.core.tasks.resourcetracker;
 
+import org.opensearch.common.annotation.PublicApi;
+
 /**
  *  Different resource stats are defined.
  *
- *  @opensearch.internal
+ *  @opensearch.api
  */
+@PublicApi(since = "2.1.0")
 public enum ResourceStats {
     CPU("cpu_time_in_nanos"),
     MEMORY("memory_in_bytes");

diff --git a/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/ResourceStatsType.java b/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/ResourceStatsType.java
@@ -8,11 +8,14 @@
 
 package org.opensearch.core.tasks.resourcetracker;
 
+import org.opensearch.common.annotation.PublicApi;
+
 /**
  * Defines the different types of resource stats.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "2.1.0")
 public enum ResourceStatsType {
     // resource stats of the worker thread reported directly from runnable.
     WORKER_STATS("worker_stats", false);

diff --git a/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/ResourceUsageInfo.java b/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/ResourceUsageInfo.java
@@ -10,6 +10,7 @@
 
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
+import org.opensearch.common.annotation.PublicApi;
 
 import java.util.Collections;
 import java.util.EnumMap;
@@ -22,8 +23,9 @@
  * It captures the resource usage information like memory, CPU about a particular execution of thread
  * for a specific stats type.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "2.1.0")
 public class ResourceUsageInfo {
     private static final Logger logger = LogManager.getLogger(ResourceUsageInfo.class);
     private final EnumMap<ResourceStats, ResourceStatsInfo> statsInfo = new EnumMap<>(ResourceStats.class);

diff --git a/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/ResourceUsageMetric.java b/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/ResourceUsageMetric.java
@@ -8,11 +8,14 @@
 
 package org.opensearch.core.tasks.resourcetracker;
 
+import org.opensearch.common.annotation.PublicApi;
+
 /**
  * Information about resource usage
  *
- * @opensearch.internal
+ *  @opensearch.api
  */
+@PublicApi(since = "2.1.0")
 public class ResourceUsageMetric {
     private final ResourceStats stats;
     private final long value;

diff --git a/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/TaskResourceStats.java b/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/TaskResourceStats.java
@@ -9,6 +9,7 @@
 package org.opensearch.core.tasks.resourcetracker;
 
 import org.opensearch.Version;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.common.Strings;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.common.io.stream.StreamOutput;
@@ -29,8 +30,9 @@
  * Writeable TaskResourceStats objects are used to represent resource
  * snapshot information about currently running task.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "2.1.0")
 public class TaskResourceStats implements Writeable, ToXContentFragment {
     private final Map<String, TaskResourceUsage> resourceUsage;
     private final TaskThreadUsage threadUsage;

diff --git a/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/TaskResourceUsage.java b/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/TaskResourceUsage.java
@@ -8,6 +8,7 @@
 
 package org.opensearch.core.tasks.resourcetracker;
 
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.ParseField;
 import org.opensearch.core.common.Strings;
 import org.opensearch.core.common.io.stream.StreamInput;
@@ -30,8 +31,9 @@
  * Writeable TaskResourceUsage objects are used to represent resource usage
  * information of running tasks.
  *
- * @opensearch.internal
+ *  @opensearch.api
  */
+@PublicApi(since = "2.1.0")
 public class TaskResourceUsage implements Writeable, ToXContentFragment {
     private static final ParseField CPU_TIME_IN_NANOS = new ParseField("cpu_time_in_nanos");
     private static final ParseField MEMORY_IN_BYTES = new ParseField("memory_in_bytes");

diff --git a/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/TaskThreadUsage.java b/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/TaskThreadUsage.java
@@ -8,6 +8,7 @@
 
 package org.opensearch.core.tasks.resourcetracker;
 
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.ParseField;
 import org.opensearch.core.common.Strings;
 import org.opensearch.core.common.io.stream.StreamInput;
@@ -29,8 +30,9 @@
  * Writeable TaskThreadExecutions objects are used to represent thread related resource usage of running tasks.
  * asd
  *
- * @opensearch.internal
+ *  @opensearch.api
  */
+@PublicApi(since = "2.1.0")
 public class TaskThreadUsage implements Writeable, ToXContentFragment {
 
     private static final String THREAD_EXECUTIONS = "thread_executions";

diff --git a/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/ThreadResourceInfo.java b/libs/core/src/main/java/org/opensearch/core/tasks/resourcetracker/ThreadResourceInfo.java
@@ -8,14 +8,17 @@
 
 package org.opensearch.core.tasks.resourcetracker;
 
+import org.opensearch.common.annotation.PublicApi;
+
 /**
  * Resource consumption information about a particular execution of thread.
  * <p>
  * It captures the resource usage information about a particular execution of thread
  * for a specific stats type like worker_stats or response_stats etc.,
  *
- * @opensearch.internal
+ *  @opensearch.api
  */
+@PublicApi(since = "2.1.0")
 public class ThreadResourceInfo {
     private final long threadId;
     private volatile boolean isActive = true;

diff --git a/libs/core/src/main/java/org/opensearch/core/xcontent/AbstractObjectParser.java b/libs/core/src/main/java/org/opensearch/core/xcontent/AbstractObjectParser.java
@@ -33,6 +33,7 @@
 package org.opensearch.core.xcontent;
 
 import org.opensearch.common.CheckedFunction;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.ParseField;
 import org.opensearch.core.xcontent.ObjectParser.NamedObjectParser;
 import org.opensearch.core.xcontent.ObjectParser.ValueType;
@@ -47,8 +48,9 @@
 /**
  * Superclass for {@link ObjectParser} and {@link ConstructingObjectParser}. Defines most of the "declare" methods so they can be shared.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public abstract class AbstractObjectParser<Value, Context> {
 
     /**

diff --git a/libs/core/src/main/java/org/opensearch/core/xcontent/ContextParser.java b/libs/core/src/main/java/org/opensearch/core/xcontent/ContextParser.java
@@ -32,11 +32,16 @@
 
 package org.opensearch.core.xcontent;
 
+import org.opensearch.common.annotation.PublicApi;
+
 import java.io.IOException;
 
 /**
  * Reads an object from a parser using some context.
+ *
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 @FunctionalInterface
 public interface ContextParser<Context, T> {
     T parse(XContentParser p, Context c) throws IOException;

diff --git a/libs/core/src/main/java/org/opensearch/core/xcontent/DeprecationHandler.java b/libs/core/src/main/java/org/opensearch/core/xcontent/DeprecationHandler.java
@@ -32,12 +32,17 @@
 
 package org.opensearch.core.xcontent;
 
+import org.opensearch.common.annotation.PublicApi;
+
 import java.util.function.Supplier;
 
 /**
  * Callback for notifying the creator of the {@link XContentParser} that
  * parsing hit a deprecated field.
+ *
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public interface DeprecationHandler {
     /**
      * Throws an {@link UnsupportedOperationException} when parsing hits a

diff --git a/libs/core/src/main/java/org/opensearch/core/xcontent/ToXContent.java b/libs/core/src/main/java/org/opensearch/core/xcontent/ToXContent.java
@@ -33,6 +33,7 @@
 package org.opensearch.core.xcontent;
 
 import org.opensearch.common.Booleans;
+import org.opensearch.common.annotation.PublicApi;
 
 import java.io.IOException;
 import java.util.Map;
@@ -42,15 +43,17 @@
  * The output may or may not be a value object. Objects implementing {@link ToXContentObject} output a valid value
  * but those that don't may or may not require emitting a startObject and an endObject.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public interface ToXContent {
 
     /**
      * Base parameters class
      *
-     * @opensearch.internal
+     * @opensearch.api
      */
+    @PublicApi(since = "1.0.0")
     interface Params {
         String param(String key);
 

diff --git a/libs/core/src/main/java/org/opensearch/core/xcontent/XContent.java b/libs/core/src/main/java/org/opensearch/core/xcontent/XContent.java
@@ -32,6 +32,8 @@
 
 package org.opensearch.core.xcontent;
 
+import org.opensearch.common.annotation.PublicApi;
+
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
@@ -41,7 +43,10 @@
 
 /**
  * A generic abstraction on top of handling content, inspired by JSON and pull parsing.
+ *
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public interface XContent {
     /**
      * The type this content handles and produces.