Added missed API visibility annotations for public / experimental APIs (

#12864) (#12867) Signed-off-by: Andriy Redko <andriy.redko@aiven.io> (cherry picked from commit ac0bb83)
opensearch-project · Mar 23, 2024 · a350cef · a350cef
1 parent 24e25b7
commit a350cef
Show file tree

Hide file tree

Showing 33 changed files with 121 additions and 29 deletions.
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/core/common/breaker/CircuitBreaker.java b/libs/core/src/main/java/org/opensearch/core/common/breaker/CircuitBreaker.java
@@ -32,14 +32,17 @@
 
 package org.opensearch.core.common.breaker;
 
+import org.opensearch.common.annotation.PublicApi;
+
 import java.util.Locale;
 
 /**
  * Interface for an object that can be incremented, breaking after some
  * configured limit has been reached.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public interface CircuitBreaker {
 
     /**
@@ -72,8 +75,10 @@ public interface CircuitBreaker {
     /**
      * The type of breaker
      * can be {@link #MEMORY}, {@link #PARENT}, or {@link #NOOP}
-     * @opensearch.internal
+     *
+     * @opensearch.api
      */
+    @PublicApi(since = "1.0.0")
     enum Type {
         /** A regular or ChildMemoryCircuitBreaker */
         MEMORY,

diff --git a/libs/core/src/main/java/org/opensearch/core/common/transport/BoundTransportAddress.java b/libs/core/src/main/java/org/opensearch/core/common/transport/BoundTransportAddress.java
@@ -32,6 +32,7 @@
 
 package org.opensearch.core.common.transport;
 
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.network.InetAddresses;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.common.io.stream.StreamOutput;
@@ -44,8 +45,9 @@
  * the addresses the transport is bound to, and the other is the published one that represents the address clients
  * should communicate on.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class BoundTransportAddress implements Writeable {
 
     private TransportAddress[] boundAddresses;

diff --git a/libs/core/src/main/java/org/opensearch/core/transport/TransportResponse.java b/libs/core/src/main/java/org/opensearch/core/transport/TransportResponse.java
@@ -32,6 +32,7 @@
 
 package org.opensearch.core.transport;
 
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.common.io.stream.StreamOutput;
 
@@ -40,8 +41,9 @@
 /**
  * Response over the transport interface
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public abstract class TransportResponse extends TransportMessage {
 
     /**

diff --git a/libs/core/src/main/java/org/opensearch/semver/SemverRange.java b/libs/core/src/main/java/org/opensearch/semver/SemverRange.java
@@ -10,6 +10,7 @@
 
 import org.opensearch.Version;
 import org.opensearch.common.Nullable;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.xcontent.ToXContentFragment;
 import org.opensearch.core.xcontent.XContentBuilder;
 import org.opensearch.semver.expr.Caret;
@@ -31,7 +32,10 @@
  *     <li>'~' Allows for patch version variability starting from the range version. For example, ~1.2.3 range would match versions greater than or equal to 1.2.3 but less than 1.3.0</li>
  *     <li>'^' Allows for patch and minor version variability starting from the range version. For example, ^1.2.3 range would match versions greater than or equal to 1.2.3 but less than 2.0.0</li>
  * </ul>
+ *
+ * @opensearch.api
  */
+@PublicApi(since = "2.13.0")
 public class SemverRange implements ToXContentFragment {
 
     private final Version rangeVersion;

diff --git a/...src/main/java/org/opensearch/action/support/clustermanager/ClusterManagerNodeRequest.java b/...src/main/java/org/opensearch/action/support/clustermanager/ClusterManagerNodeRequest.java
@@ -33,6 +33,7 @@
 package org.opensearch.action.support.clustermanager;
 
 import org.opensearch.action.ActionRequest;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.unit.TimeValue;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.common.io.stream.StreamOutput;
@@ -42,8 +43,9 @@
 /**
  * A based request for cluster-manager based operation.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public abstract class ClusterManagerNodeRequest<Request extends ClusterManagerNodeRequest<Request>> extends ActionRequest {
 
     public static final TimeValue DEFAULT_CLUSTER_MANAGER_NODE_TIMEOUT = TimeValue.timeValueSeconds(30);

diff --git a/server/src/main/java/org/opensearch/common/cache/RemovalListener.java b/server/src/main/java/org/opensearch/common/cache/RemovalListener.java
@@ -32,11 +32,14 @@
 
 package org.opensearch.common.cache;
 
+import org.opensearch.common.annotation.ExperimentalApi;
+
 /**
  * Listener for removing an element from the cache
  *
- * @opensearch.internal
+ * @opensearch.experimental
  */
+@ExperimentalApi
 @FunctionalInterface
 public interface RemovalListener<K, V> {
     void onRemoval(RemovalNotification<K, V> notification);

diff --git a/server/src/main/java/org/opensearch/common/cache/policy/CachedQueryResult.java b/server/src/main/java/org/opensearch/common/cache/policy/CachedQueryResult.java
@@ -8,6 +8,7 @@
 
 package org.opensearch.common.cache.policy;
 
+import org.opensearch.common.annotation.ExperimentalApi;
 import org.opensearch.core.common.bytes.BytesReference;
 import org.opensearch.core.common.io.stream.NamedWriteableAwareStreamInput;
 import org.opensearch.core.common.io.stream.NamedWriteableRegistry;
@@ -62,7 +63,10 @@ public void writeToNoId(StreamOutput out) throws IOException {
     /**
      * A class containing information needed for all cache policies
      *  to decide whether to admit a given value.
+     *
+     *  @opensearch.experimental
      */
+    @ExperimentalApi
     public static class PolicyValues implements Writeable {
         final long tookTimeNanos;
         // More values can be added here as they're needed for future policies

diff --git a/server/src/main/java/org/opensearch/common/cache/serializer/Serializer.java b/server/src/main/java/org/opensearch/common/cache/serializer/Serializer.java
@@ -8,10 +8,15 @@
 
 package org.opensearch.common.cache.serializer;
 
+import org.opensearch.common.annotation.ExperimentalApi;
+
 /**
  * Defines an interface for serializers, to be used by pluggable caches.
  * T is the class of the original object, and U is the serialized class.
+ *
+ * @opensearch.experimental
  */
+@ExperimentalApi
 public interface Serializer<T, U> {
     /**
      * Serializes an object.

diff --git a/server/src/main/java/org/opensearch/common/lucene/index/OpenSearchDirectoryReader.java b/server/src/main/java/org/opensearch/common/lucene/index/OpenSearchDirectoryReader.java
@@ -84,8 +84,10 @@ public DelegatingCacheHelper getDelegatingCacheHelper() {
 
     /**
      * Wraps existing IndexReader cache helper which internally provides a way to wrap CacheKey.
-     * @opensearch.internal
+     *
+     * @opensearch.api
      */
+    @PublicApi(since = "2.13.0")
     public class DelegatingCacheHelper implements CacheHelper {
         private final CacheHelper cacheHelper;
         private final DelegatingCacheKey serializableCacheKey;
@@ -113,7 +115,10 @@ public void addClosedListener(ClosedListener listener) {
     /**
      *  Wraps internal IndexReader.CacheKey and attaches a uniqueId to it which can be eventually be used instead of
      *  object itself for serialization purposes.
+     *
+     *  @opensearch.api
      */
+    @PublicApi(since = "2.13.0")
     public class DelegatingCacheKey {
         private final CacheKey cacheKey;
         private final String uniqueId;

diff --git a/server/src/main/java/org/opensearch/common/metrics/MeanMetric.java b/server/src/main/java/org/opensearch/common/metrics/MeanMetric.java
@@ -32,13 +32,16 @@
 
 package org.opensearch.common.metrics;
 
+import org.opensearch.common.annotation.PublicApi;
+
 import java.util.concurrent.atomic.LongAdder;
 
 /**
  * An average metric for tracking.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class MeanMetric implements Metric {
 
     private final LongAdder counter = new LongAdder();

diff --git a/server/src/main/java/org/opensearch/http/HttpInfo.java b/server/src/main/java/org/opensearch/http/HttpInfo.java
@@ -32,6 +32,7 @@
 
 package org.opensearch.http;
 
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.logging.DeprecationLogger;
 import org.opensearch.common.network.InetAddresses;
 import org.opensearch.core.common.io.stream.StreamInput;
@@ -47,8 +48,9 @@
 /**
  * Information about an http connection
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class HttpInfo implements ReportingService.Info {
 
     private static final DeprecationLogger deprecationLogger = DeprecationLogger.getLogger(HttpInfo.class);

diff --git a/server/src/main/java/org/opensearch/http/HttpServerTransport.java b/server/src/main/java/org/opensearch/http/HttpServerTransport.java
@@ -32,6 +32,7 @@
 
 package org.opensearch.http;
 
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.lifecycle.LifecycleComponent;
 import org.opensearch.common.util.concurrent.ThreadContext;
 import org.opensearch.core.common.transport.BoundTransportAddress;
@@ -42,8 +43,9 @@
 /**
  * HTTP Transport server
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public interface HttpServerTransport extends LifecycleComponent, ReportingService<HttpInfo> {
 
     String HTTP_SERVER_WORKER_THREAD_NAME_PREFIX = "http_server_worker";

diff --git a/server/src/main/java/org/opensearch/http/HttpStats.java b/server/src/main/java/org/opensearch/http/HttpStats.java
@@ -32,6 +32,7 @@
 
 package org.opensearch.http;
 
+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 for HTTP connections
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class HttpStats implements Writeable, ToXContentFragment {
 
     private final long serverOpen;

diff --git a/server/src/main/java/org/opensearch/index/codec/fuzzy/LongArrayBackedBitSet.java b/server/src/main/java/org/opensearch/index/codec/fuzzy/LongArrayBackedBitSet.java
@@ -39,7 +39,7 @@ class LongArrayBackedBitSet implements Accountable, Closeable {
     /**
      * Constructor which uses Lucene's IndexInput to read the bitset into a read-only buffer.
      * @param in IndexInput containing the serialized bitset.
-     * @throws IOException
+     * @throws IOException I/O exception
      */
     LongArrayBackedBitSet(IndexInput in) throws IOException {
         underlyingArrayLength = in.readLong();

diff --git a/server/src/main/java/org/opensearch/index/store/RemoteSegmentStoreDirectoryFactory.java b/server/src/main/java/org/opensearch/index/store/RemoteSegmentStoreDirectoryFactory.java
@@ -9,6 +9,7 @@
 package org.opensearch.index.store;
 
 import org.apache.lucene.store.Directory;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.blobstore.BlobPath;
 import org.opensearch.core.index.shard.ShardId;
 import org.opensearch.index.IndexSettings;
@@ -28,8 +29,9 @@
 /**
  * Factory for a remote store directory
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "2.3.0")
 public class RemoteSegmentStoreDirectoryFactory implements IndexStorePlugin.DirectoryFactory {
     private static final String SEGMENTS = "segments";
 

diff --git a/server/src/main/java/org/opensearch/rest/BaseRestHandler.java b/server/src/main/java/org/opensearch/rest/BaseRestHandler.java
@@ -40,6 +40,7 @@
 import org.opensearch.action.support.clustermanager.ClusterManagerNodeRequest;
 import org.opensearch.client.node.NodeClient;
 import org.opensearch.common.CheckedConsumer;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.collect.Tuple;
 import org.opensearch.common.settings.Setting;
 import org.opensearch.common.settings.Setting.Property;
@@ -72,6 +73,7 @@
  *
  * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public abstract class BaseRestHandler implements RestHandler {
 
     public static final Setting<Boolean> MULTI_ALLOW_EXPLICIT_INDEX = Setting.boolSetting(
@@ -194,8 +196,11 @@ protected final String unrecognized(
     /**
      * REST requests are handled by preparing a channel consumer that represents the execution of
      * the request against a channel.
+     *
+     * @opensearch.api
      */
     @FunctionalInterface
+    @PublicApi(since = "1.0.0")
     protected interface RestChannelConsumer extends CheckedConsumer<RestChannel, Exception> {}
 
     /**

diff --git a/server/src/main/java/org/opensearch/rest/RestChannel.java b/server/src/main/java/org/opensearch/rest/RestChannel.java
@@ -33,6 +33,7 @@
 package org.opensearch.rest;
 
 import org.opensearch.common.Nullable;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.io.stream.BytesStreamOutput;
 import org.opensearch.core.xcontent.MediaType;
 import org.opensearch.core.xcontent.XContentBuilder;
@@ -44,6 +45,7 @@
  *
  * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public interface RestChannel {
 
     XContentBuilder newBuilder() throws IOException;

diff --git a/server/src/main/java/org/opensearch/rest/RestHandler.java b/server/src/main/java/org/opensearch/rest/RestHandler.java
@@ -33,6 +33,7 @@
 package org.opensearch.rest;
 
 import org.opensearch.client.node.NodeClient;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.xcontent.XContent;
 import org.opensearch.rest.RestRequest.Method;
 
@@ -180,8 +181,9 @@ public boolean allowSystemIndexAccessByDefault() {
     /**
      * Route for the request.
      *
-     * @opensearch.internal
+     * @opensearch.api
      */
+    @PublicApi(since = "1.0.0")
     class Route {
 
         protected final String path;

diff --git a/server/src/main/java/org/opensearch/rest/RestResponse.java b/server/src/main/java/org/opensearch/rest/RestResponse.java
@@ -33,6 +33,7 @@
 package org.opensearch.rest;
 
 import org.opensearch.OpenSearchException;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.lease.Releasable;
 import org.opensearch.core.common.bytes.BytesReference;
 import org.opensearch.core.rest.RestStatus;
@@ -49,6 +50,7 @@
  *
  * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public abstract class RestResponse {
 
     private Map<String, List<String>> customHeaders;