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

…tations (part 3) (#11182) Signed-off-by: Andriy Redko <andriy.redko@aiven.io>
opensearch-project · Nov 16, 2023 · 09bacee · 09bacee
1 parent 5b505ec
commit 09bacee
Show file tree

Hide file tree

Showing 353 changed files with 1,404 additions and 505 deletions.
diff --git a/libs/common/src/main/java/org/opensearch/common/Explicit.java b/libs/common/src/main/java/org/opensearch/common/Explicit.java
@@ -32,6 +32,8 @@
 
 package org.opensearch.common;
 
+import org.opensearch.common.annotation.PublicApi;
+
 import java.util.Objects;
 
 /**
@@ -43,8 +45,9 @@
  * field mapping settings it is preferable to preserve an explicit
  * choice rather than a choice made only made implicitly by defaults.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class Explicit<T> {
 
     private final T value;

diff --git a/libs/common/src/main/java/org/opensearch/common/lease/Releasable.java b/libs/common/src/main/java/org/opensearch/common/lease/Releasable.java
@@ -32,13 +32,16 @@
 
 package org.opensearch.common.lease;
 
+import org.opensearch.common.annotation.PublicApi;
+
 import java.io.Closeable;
 
 /**
  * Specialization of {@link AutoCloseable} for calls that might not throw a checked exception.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public interface Releasable extends Closeable {
 
     @Override

diff --git a/libs/core/src/main/java/org/opensearch/core/action/ActionResponse.java b/libs/core/src/main/java/org/opensearch/core/action/ActionResponse.java
@@ -32,6 +32,7 @@
 
 package org.opensearch.core.action;
 
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.transport.TransportResponse;
 
@@ -42,6 +43,7 @@
  *
  * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public abstract class ActionResponse extends TransportResponse {
 
     public ActionResponse() {}

diff --git a/libs/core/src/main/java/org/opensearch/core/common/io/stream/Writeable.java b/libs/core/src/main/java/org/opensearch/core/common/io/stream/Writeable.java
@@ -32,6 +32,8 @@
 
 package org.opensearch.core.common.io.stream;
 
+import org.opensearch.common.annotation.PublicApi;
+
 import java.io.IOException;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
@@ -41,8 +43,9 @@
  * across the wire" using OpenSearch's internal protocol. If the implementer also implements equals and hashCode then a copy made by
  * serializing and deserializing must be equal and have the same hashCode. It isn't required that such a copy be entirely unchanged.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "2.8.0")
 public interface Writeable {
     /**
      * A WriteableRegistry registers {@link Writer} methods for writing data types over a
@@ -135,8 +138,11 @@ public static Class<?> getCustomClassFromInstance(final Object value) {
      *     out.writeMapOfLists(someMap, StreamOutput::writeString, StreamOutput::writeString);
      * }
      * </code></pre>
+     *
+     * @opensearch.api
      */
     @FunctionalInterface
+    @PublicApi(since = "2.8.0")
     interface Writer<V> {
 
         /**
@@ -161,8 +167,11 @@ interface Writer<V> {
      *     this.someMap = in.readMapOfLists(StreamInput::readString, StreamInput::readString);
      * }
      * </code></pre>
+     *
+     * @opensearch.api
      */
     @FunctionalInterface
+    @PublicApi(since = "2.8.0")
     interface Reader<V> {
 
         /**

diff --git a/libs/core/src/main/java/org/opensearch/core/common/util/ByteArray.java b/libs/core/src/main/java/org/opensearch/core/common/util/ByteArray.java
@@ -33,14 +33,16 @@
 package org.opensearch.core.common.util;
 
 import org.apache.lucene.util.BytesRef;
+import org.opensearch.common.annotation.PublicApi;
 
 import java.nio.ByteBuffer;
 
 /**
  * Abstraction of an array of byte values.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public interface ByteArray extends BigArray {
 
     /**

diff --git a/libs/core/src/main/java/org/opensearch/core/indices/breaker/AllCircuitBreakerStats.java b/libs/core/src/main/java/org/opensearch/core/indices/breaker/AllCircuitBreakerStats.java
@@ -32,6 +32,7 @@
 
 package org.opensearch.core.indices.breaker;
 
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.common.io.stream.StreamOutput;
 import org.opensearch.core.common.io.stream.Writeable;
@@ -43,8 +44,9 @@
 /**
  * Stats class encapsulating all of the different circuit breaker stats
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class AllCircuitBreakerStats implements Writeable, ToXContentFragment {
 
     /** An array of all the circuit breaker stats */

diff --git a/libs/core/src/main/java/org/opensearch/core/indices/breaker/CircuitBreakerService.java b/libs/core/src/main/java/org/opensearch/core/indices/breaker/CircuitBreakerService.java
@@ -32,20 +32,18 @@
 
 package org.opensearch.core.indices.breaker;
 
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.Logger;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.lifecycle.AbstractLifecycleComponent;
 import org.opensearch.core.common.breaker.CircuitBreaker;
 
 /**
  * Interface for Circuit Breaker services, which provide breakers to classes
  * that load field data.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public abstract class CircuitBreakerService extends AbstractLifecycleComponent {
-    private static final Logger logger = LogManager.getLogger(CircuitBreakerService.class);
-
     protected CircuitBreakerService() {}
 
     /**

diff --git a/libs/core/src/main/java/org/opensearch/core/indices/breaker/CircuitBreakerStats.java b/libs/core/src/main/java/org/opensearch/core/indices/breaker/CircuitBreakerStats.java
@@ -32,6 +32,7 @@
 
 package org.opensearch.core.indices.breaker;
 
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.common.io.stream.StreamOutput;
 import org.opensearch.core.common.io.stream.Writeable;
@@ -45,8 +46,9 @@
 /**
  * Class encapsulating stats about the {@link org.opensearch.core.common.breaker.CircuitBreaker}
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class CircuitBreakerStats implements Writeable, ToXContentObject {
 
     /** The name of the circuit breaker */

diff --git a/libs/core/src/main/java/org/opensearch/core/xcontent/ObjectParser.java b/libs/core/src/main/java/org/opensearch/core/xcontent/ObjectParser.java
@@ -32,6 +32,7 @@
 package org.opensearch.core.xcontent;
 
 import org.opensearch.common.Nullable;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.ParseField;
 
 import java.io.IOException;
@@ -83,8 +84,9 @@
  * It's highly recommended to use the high level declare methods like {@link #declareString(BiConsumer, ParseField)} instead of
  * {@link #declareField} which can be used to implement exceptional parsing operations not covered by the high level methods.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public final class ObjectParser<Value, Context> extends AbstractObjectParser<Value, Context>
     implements
         BiFunction<XContentParser, Context, Value>,

diff --git a/...alClusterTest/java/org/opensearch/remotestore/RemoteStoreBackpressureAndResiliencyIT.java b/...alClusterTest/java/org/opensearch/remotestore/RemoteStoreBackpressureAndResiliencyIT.java
@@ -14,14 +14,14 @@
 import org.opensearch.action.admin.indices.flush.FlushResponse;
 import org.opensearch.common.settings.Settings;
 import org.opensearch.common.unit.TimeValue;
-import org.opensearch.common.util.concurrent.AbstractAsyncTask;
 import org.opensearch.common.util.concurrent.UncategorizedExecutionException;
 import org.opensearch.core.common.bytes.BytesArray;
 import org.opensearch.core.common.bytes.BytesReference;
 import org.opensearch.core.common.unit.ByteSizeUnit;
 import org.opensearch.core.concurrency.OpenSearchRejectedExecutionException;
 import org.opensearch.core.xcontent.MediaTypeRegistry;
 import org.opensearch.index.IndexService;
+import org.opensearch.index.IndexServiceTestUtils;
 import org.opensearch.index.remote.RemoteSegmentTransferTracker;
 import org.opensearch.index.shard.IndexShard;
 import org.opensearch.indices.IndicesService;
@@ -175,7 +175,7 @@ public void testAsyncTrimTaskSucceeds() {
 
         logger.info("Increasing the frequency of async trim task to ensure it runs in background while indexing");
         IndexService indexService = internalCluster().getInstance(IndicesService.class, dataNodeName).iterator().next();
-        ((AbstractAsyncTask) indexService.getTrimTranslogTask()).setInterval(TimeValue.timeValueMillis(100));
+        IndexServiceTestUtils.setTrimTranslogTaskInterval(indexService, TimeValue.timeValueMillis(100));
 
         logger.info("--> Indexing data");
         indexData(randomIntBetween(2, 5), true);

diff --git a/server/src/main/java/org/opensearch/action/AliasesRequest.java b/server/src/main/java/org/opensearch/action/AliasesRequest.java
@@ -32,14 +32,17 @@
 
 package org.opensearch.action;
 
+import org.opensearch.common.annotation.PublicApi;
+
 /**
  * Needs to be implemented by all {@link org.opensearch.action.ActionRequest} subclasses that relate to
  * one or more indices and one or more aliases. Meant to be used for aliases management requests (e.g. add/remove alias,
  * get aliases) that hold aliases and indices in separate fields.
  * Allows to retrieve which indices and aliases the action relates to.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public interface AliasesRequest extends IndicesRequest.Replaceable {
 
     /**

diff --git a/server/src/main/java/org/opensearch/action/OriginalIndices.java b/server/src/main/java/org/opensearch/action/OriginalIndices.java
@@ -33,6 +33,7 @@
 package org.opensearch.action;
 
 import org.opensearch.action.support.IndicesOptions;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.common.io.stream.StreamOutput;
 
@@ -42,8 +43,9 @@
 /**
  * Used to keep track of original indices within internal (e.g. shard level) requests
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public final class OriginalIndices implements IndicesRequest {
 
     // constant to use when original indices are not applicable and will not be serialized across the wire

diff --git a/...ain/java/org/opensearch/action/admin/cluster/allocation/ClusterAllocationExplanation.java b/...ain/java/org/opensearch/action/admin/cluster/allocation/ClusterAllocationExplanation.java
@@ -40,6 +40,7 @@
 import org.opensearch.cluster.routing.allocation.AllocationDecision;
 import org.opensearch.cluster.routing.allocation.ShardAllocationDecision;
 import org.opensearch.common.Nullable;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.common.io.stream.StreamOutput;
 import org.opensearch.core.common.io.stream.Writeable;
@@ -58,8 +59,9 @@
  * or if it is not unassigned, then which nodes it could possibly be relocated to.
  * It is an immutable class.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public final class ClusterAllocationExplanation implements ToXContentObject, Writeable {
 
     private final ShardRouting shardRouting;

diff --git a/...er/src/main/java/org/opensearch/action/admin/cluster/snapshots/status/SnapshotStatus.java b/...er/src/main/java/org/opensearch/action/admin/cluster/snapshots/status/SnapshotStatus.java
@@ -35,6 +35,7 @@
 import org.opensearch.cluster.SnapshotsInProgress;
 import org.opensearch.cluster.SnapshotsInProgress.State;
 import org.opensearch.common.Nullable;
+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;
@@ -68,8 +69,9 @@
 /**
  * Status of a snapshot
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class SnapshotStatus implements ToXContentObject, Writeable {
 
     private final Snapshot snapshot;

diff --git a/server/src/main/java/org/opensearch/action/admin/indices/rollover/RolloverInfo.java b/server/src/main/java/org/opensearch/action/admin/indices/rollover/RolloverInfo.java
@@ -34,6 +34,7 @@
 
 import org.opensearch.cluster.AbstractDiffable;
 import org.opensearch.cluster.Diff;
+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;
@@ -52,8 +53,9 @@
 /**
  * Class for holding Rollover related information within an index
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class RolloverInfo extends AbstractDiffable<RolloverInfo> implements Writeable, ToXContentFragment {
 
     public static final ParseField CONDITION_FIELD = new ParseField("met_conditions");

diff --git a/server/src/main/java/org/opensearch/action/search/ParsedScrollId.java b/server/src/main/java/org/opensearch/action/search/ParsedScrollId.java
@@ -32,13 +32,16 @@
 
 package org.opensearch.action.search;
 
+import org.opensearch.common.annotation.PublicApi;
+
 import java.util.Arrays;
 
 /**
  * Search scroll id that has been parsed
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class ParsedScrollId {
 
     public static final String QUERY_THEN_FETCH_TYPE = "queryThenFetch";

diff --git a/server/src/main/java/org/opensearch/action/search/SearchContextIdForNode.java b/server/src/main/java/org/opensearch/action/search/SearchContextIdForNode.java
@@ -33,6 +33,7 @@
 package org.opensearch.action.search;
 
 import org.opensearch.common.Nullable;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.common.io.stream.StreamOutput;
 import org.opensearch.core.common.io.stream.Writeable;
@@ -43,8 +44,9 @@
 /**
  * Id for a search context per node.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public final class SearchContextIdForNode implements Writeable {
     private final String node;
     private final ShardSearchContextId searchContextId;

diff --git a/server/src/main/java/org/opensearch/action/search/SearchPhase.java b/server/src/main/java/org/opensearch/action/search/SearchPhase.java
@@ -32,6 +32,7 @@
 package org.opensearch.action.search;
 
 import org.opensearch.common.CheckedRunnable;
+import org.opensearch.common.annotation.PublicApi;
 
 import java.io.IOException;
 import java.util.Locale;
@@ -40,8 +41,9 @@
 /**
  * Base class for all individual search phases like collecting distributed frequencies, fetching documents, querying shards.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public abstract class SearchPhase implements CheckedRunnable<IOException> {
     private final String name;
     private long startTimeInNanos;

diff --git a/server/src/main/java/org/opensearch/action/search/SearchPhaseContext.java b/server/src/main/java/org/opensearch/action/search/SearchPhaseContext.java
@@ -34,6 +34,7 @@
 import org.apache.logging.log4j.Logger;
 import org.opensearch.action.OriginalIndices;
 import org.opensearch.common.Nullable;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.lease.Releasable;
 import org.opensearch.common.util.concurrent.AtomicArray;
 import org.opensearch.search.SearchPhaseResult;
@@ -48,8 +49,9 @@
 /**
  * This class provide contextual state and access to resources across multiple search phases.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public interface SearchPhaseContext extends Executor {
     // TODO maybe we can make this concrete later - for now we just implement this in the base class for all initial phases