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

…tations (part 2)

Signed-off-by: Andriy Redko <[email protected]>

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;

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) {

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);

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) {

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> {
 
     /**

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

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);
 

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.

libs/core/src/main/java/org/opensearch/core/xcontent/XContentParser.java

@@ -33,6 +33,7 @@
 package org.opensearch.core.xcontent;
 
 import org.opensearch.common.CheckedFunction;
+import org.opensearch.common.annotation.PublicApi;
 
 import java.io.Closeable;
 import java.io.IOException;
@@ -53,8 +54,9 @@
  *          NamedXContentRegistry.EMPTY, ParserField."{\"key\" : \"value\"}");
  * </pre>
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public interface XContentParser extends Closeable {
 
     /**

libs/x-content/src/main/java/org/opensearch/common/xcontent/XContentType.java

@@ -35,6 +35,7 @@
 import com.fasterxml.jackson.dataformat.cbor.CBORConstants;
 import com.fasterxml.jackson.dataformat.smile.SmileConstants;
 
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.xcontent.cbor.CborXContent;
 import org.opensearch.common.xcontent.json.JsonXContent;
 import org.opensearch.common.xcontent.smile.SmileXContent;
@@ -48,8 +49,10 @@
 import java.io.OutputStream;
 
 /**
- * The content type of {@link XContent}.
+ * The content type of {@link XContent}. 
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public enum XContentType implements MediaType {
 
     /**

server/src/main/java/org/opensearch/OpenSearchGenerationException.java

@@ -32,15 +32,17 @@
 
 package org.opensearch;
 
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.common.io.stream.StreamInput;
 
 import java.io.IOException;
 
 /**
  * A generic exception indicating failure to generate.
  *
- * @opensearch.internal
+  * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class OpenSearchGenerationException extends OpenSearchException {
 
     public OpenSearchGenerationException(String msg) {

server/src/main/java/org/opensearch/action/ActionRequestValidationException.java

@@ -33,10 +33,12 @@
 package org.opensearch.action;
 
 import org.opensearch.common.ValidationException;
+import org.opensearch.common.annotation.PublicApi;
 
 /**
  * Base exception for an action request validation extendable by plugins
  *
  * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class ActionRequestValidationException extends ValidationException {}

server/src/main/java/org/opensearch/action/DocWriteRequest.java

@@ -38,6 +38,7 @@
 import org.opensearch.action.support.IndicesOptions;
 import org.opensearch.action.update.UpdateRequest;
 import org.opensearch.common.Nullable;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.lucene.uid.Versions;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.common.io.stream.StreamOutput;
@@ -55,8 +56,9 @@
  * Generic interface to group ActionRequest, which perform writes to a single document
  * Action requests implementing this can be part of {@link org.opensearch.action.bulk.BulkRequest}
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public interface DocWriteRequest<T> extends IndicesRequest, Accountable {
 
     // Flag set for disallowing index auto creation for an individual write request.
@@ -169,7 +171,10 @@ public interface DocWriteRequest<T> extends IndicesRequest, Accountable {
 
     /**
      * Requested operation type to perform on the document
+     * 
+     * @opensearch.api
      */
+    @PublicApi(since = "1.0.0")
     enum OpType {
         /**
          * Index the source. If there an existing document with the id, it will

server/src/main/java/org/opensearch/action/DocWriteResponse.java

@@ -38,6 +38,7 @@
 import org.opensearch.action.support.replication.ReplicationResponse;
 import org.opensearch.cluster.metadata.IndexMetadata;
 import org.opensearch.common.Nullable;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.xcontent.StatusToXContentObject;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.common.io.stream.StreamOutput;
@@ -64,8 +65,9 @@
 /**
  * A base class for the response of a write operation that involves a single doc
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public abstract class DocWriteResponse extends ReplicationResponse implements WriteResponse, StatusToXContentObject {
 
     private static final String _SHARDS = "_shards";
@@ -80,7 +82,10 @@ public abstract class DocWriteResponse extends ReplicationResponse implements Wr
     /**
      * An enum that represents the results of CRUD operations, primarily used to communicate the type of
      * operation that occurred.
+     * 
+     * @opensearch.api
      */
+    @PublicApi(since = "1.0.0")
     public enum Result implements Writeable {
         CREATED(0),
         UPDATED(1),

server/src/main/java/org/opensearch/action/IndicesRequest.java

@@ -33,15 +33,17 @@
 package org.opensearch.action;
 
 import org.opensearch.action.support.IndicesOptions;
+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. Allows to retrieve which indices the action relates to.
  * In case of internal requests originated during the distributed execution of an external request,
  * they will still return the indices that the original request related to.
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public interface IndicesRequest {
 
     /**

server/src/main/java/org/opensearch/action/admin/cluster/allocation/ClusterAllocationExplainRequest.java

@@ -35,6 +35,7 @@
 import org.opensearch.action.ActionRequestValidationException;
 import org.opensearch.action.support.clustermanager.ClusterManagerNodeRequest;
 import org.opensearch.common.Nullable;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.ParseField;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.common.io.stream.StreamOutput;
@@ -48,8 +49,9 @@
 /**
  * A request to explain the allocation of a shard in the cluster
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class ClusterAllocationExplainRequest extends ClusterManagerNodeRequest<ClusterAllocationExplainRequest> {
 
     private static final ObjectParser<ClusterAllocationExplainRequest, Void> PARSER = new ObjectParser<>("cluster/allocation/explain");

server/src/main/java/org/opensearch/action/admin/cluster/allocation/ClusterAllocationExplainRequestBuilder.java

@@ -34,12 +34,14 @@
 
 import org.opensearch.action.support.clustermanager.ClusterManagerNodeOperationRequestBuilder;
 import org.opensearch.client.OpenSearchClient;
+import org.opensearch.common.annotation.PublicApi;
 
 /**
  * Builder for requests to explain the allocation of a shard in the cluster
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class ClusterAllocationExplainRequestBuilder extends ClusterManagerNodeOperationRequestBuilder<
     ClusterAllocationExplainRequest,
     ClusterAllocationExplainResponse,

server/src/main/java/org/opensearch/action/admin/cluster/allocation/ClusterAllocationExplainResponse.java

@@ -32,6 +32,7 @@
 
 package org.opensearch.action.admin.cluster.allocation;
 
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.core.action.ActionResponse;
 import org.opensearch.core.common.io.stream.StreamInput;
 import org.opensearch.core.common.io.stream.StreamOutput;
@@ -41,8 +42,9 @@
 /**
  * Explanation response for a shard in the cluster
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class ClusterAllocationExplainResponse extends ActionResponse {
 
     private ClusterAllocationExplanation cae;

server/src/main/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;

server/src/main/java/org/opensearch/action/admin/cluster/crypto/CryptoSettings.java

@@ -9,6 +9,7 @@
 package org.opensearch.action.admin.cluster.crypto;
 
 import org.opensearch.action.ActionRequestValidationException;
+import org.opensearch.common.annotation.PublicApi;
 import org.opensearch.common.settings.Settings;
 import org.opensearch.common.xcontent.XContentType;
 import org.opensearch.core.common.io.stream.StreamInput;
@@ -28,8 +29,9 @@
 /**
  * Crypto settings supplied during a put repository request
  *
- * @opensearch.internal
+ * @opensearch.api
  */
+@PublicApi(since = "1.0.0")
 public class CryptoSettings implements Writeable, ToXContentObject {
     private String keyProviderName;
     private String keyProviderType;