Skip to content

Commit

Permalink
[BWC and API enforcement] Decorate the existing APIs with proper anno…
Browse files Browse the repository at this point in the history
…tations (part 2)

Signed-off-by: Andriy Redko <[email protected]>
  • Loading branch information
reta committed Oct 26, 2023
1 parent 5ae9333 commit 68c1aa0
Show file tree
Hide file tree
Showing 469 changed files with 1,606 additions and 525 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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> {

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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);

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -53,8 +54,9 @@
* NamedXContentRegistry.EMPTY, ParserField."{\"key\" : \"value\"}");
* </pre>
*
* @opensearch.internal
* @opensearch.api
*/
@PublicApi(since = "1.0.0")
public interface XContentParser extends Closeable {

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -49,7 +50,9 @@

/**
* The content type of {@link XContent}.
* @opensearch.api
*/
@PublicApi(since = "1.0.0")
public enum XContentType implements MediaType {

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {}
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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";
Expand All @@ -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),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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");
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand Down
Loading

0 comments on commit 68c1aa0

Please sign in to comment.