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 3) (#11182)

Signed-off-by: Andriy Redko <andriy.redko@aiven.io>
  • Loading branch information
reta authored Nov 16, 2023
1 parent 5b505ec commit 09bacee
Show file tree
Hide file tree
Showing 353 changed files with 1,404 additions and 505 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,8 @@

package org.opensearch.common;

import org.opensearch.common.annotation.PublicApi;

import java.util.Objects;

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

Expand All @@ -42,6 +43,7 @@
*
* @opensearch.api
*/
@PublicApi(since = "1.0.0")
public abstract class ActionResponse extends TransportResponse {

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

/**
Expand All @@ -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> {

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

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

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

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

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

Expand Down
Loading

0 comments on commit 09bacee

Please sign in to comment.