[Javadocs] add to o.o.common (#3289)

Add javadocs to top level and internal classes in the org.opensearch.common
package.

Signed-off-by: Nicholas Walter Knize <nknize@apache.org>

server/src/main/java/org/opensearch/common/AsyncBiFunction.java

@@ -35,6 +35,8 @@ import org.opensearch.action.ActionListener;
 
 /**
  * A {@link java.util.function.BiFunction}-like interface designed to be used with asynchronous executions.
+ *
+ * @opensearch.internal
  */
 public interface AsyncBiFunction<T, U, C> {
 

server/src/main/java/org/opensearch/common/CheckedBiConsumer.java

@@ -36,6 +36,8 @@ import java.util.function.BiConsumer;
 
 /**
  * A {@link BiConsumer}-like interface which allows throwing checked exceptions.
+ *
+ * @opensearch.internal
  */
 @FunctionalInterface
 public interface CheckedBiConsumer<T, U, E extends Exception> {

server/src/main/java/org/opensearch/common/CheckedBiFunction.java

@@ -34,6 +34,8 @@ package org.opensearch.common;
 
 /**
  * A {@link java.util.function.BiFunction}-like interface which allows throwing checked exceptions.
+ *
+ * @opensearch.internal
  */
 @FunctionalInterface
 public interface CheckedBiFunction<T, U, R, E extends Exception> {

server/src/main/java/org/opensearch/common/CheckedSupplier.java

@@ -36,6 +36,8 @@ import java.util.function.Supplier;
 
 /**
  * A {@link Supplier}-like interface which allows throwing checked exceptions.
+ *
+ * @opensearch.internal
  */
 @FunctionalInterface
 public interface CheckedSupplier<R, E extends Exception> {

server/src/main/java/org/opensearch/common/Classes.java

@@ -34,6 +34,11 @@ package org.opensearch.common;
 
 import java.lang.reflect.Modifier;
 
+/**
+ * Base class utilities
+ *
+ * @opensearch.internal
+ */
 public class Classes {
 
     /**

server/src/main/java/org/opensearch/common/Explicit.java

@@ -43,6 +43,7 @@ import java.util.Objects;
  * field mapping settings it is preferable to preserve an explicit
  * choice rather than a choice made only made implicitly by defaults.
  *
+ * @opensearch.internal
  */
 public class Explicit<T> {
 

server/src/main/java/org/opensearch/common/ExponentiallyWeightedMovingAverage.java

@@ -37,6 +37,8 @@ import java.util.concurrent.atomic.AtomicLong;
 /**
  * Implements exponentially weighted moving averages (commonly abbreviated EWMA) for a single value.
  * This class is safe to share between threads.
+ *
+ * @opensearch.internal
  */
 public class ExponentiallyWeightedMovingAverage {
 

server/src/main/java/org/opensearch/common/FieldMemoryStats.java

@@ -46,6 +46,8 @@ import java.util.Objects;
 
 /**
  * A reusable class to encode {@code field -> memory size} mappings
+ *
+ * @opensearch.internal
  */
 public final class FieldMemoryStats implements Writeable, Iterable<ObjectLongCursor<String>> {
 

server/src/main/java/org/opensearch/common/LegacyTimeBasedUUIDGenerator.java

@@ -39,6 +39,8 @@ import java.util.concurrent.atomic.AtomicInteger;
  * These are essentially flake ids, but we use 6 (not 8) bytes for timestamp, and use 3 (not 2) bytes for sequence number.
  * For more information about flake ids, check out
  * https://archive.fo/2015.07.08-082503/http://www.boundary.com/blog/2012/01/flake-a-decentralized-k-ordered-unique-id-generator-in-erlang/
+ *
+ * @opensearch.internal
  */
 
 class LegacyTimeBasedUUIDGenerator implements UUIDGenerator {

server/src/main/java/org/opensearch/common/LocalTimeOffset.java

@@ -61,6 +61,8 @@ import java.util.Locale;
  * <p>
  * So there are two methods to convert from local time back to utc,
  * {@link #localToUtc(long, Strategy)} and {@link #localToUtcInThisOffset(long)}.
+ *
+ * @opensearch.internal
  */
 public abstract class LocalTimeOffset {
     /**
@@ -206,6 +208,8 @@ public abstract class LocalTimeOffset {
 
     /**
      * How to get instances of {@link LocalTimeOffset}.
+     *
+     * @opensearch.internal
      */
     public abstract static class Lookup {
         /**
@@ -234,6 +238,11 @@ public abstract class LocalTimeOffset {
         abstract int size();
     }
 
+    /**
+     * No previous local time offset
+     *
+     * @opensearch.internal
+     */
     private static class NoPrevious extends LocalTimeOffset {
         NoPrevious(long millis) {
             super(millis);
@@ -269,6 +278,11 @@ public abstract class LocalTimeOffset {
         }
     }
 
+    /**
+     * Transition for a local time offset
+     *
+     * @opensearch.internal
+     */
     public abstract static class Transition extends LocalTimeOffset {
         private final LocalTimeOffset previous;
         private final long startUtcMillis;
@@ -307,6 +321,11 @@ public abstract class LocalTimeOffset {
         }
     }
 
+    /**
+     * Gap for a local time offset
+     *
+     * @opensearch.internal
+     */
     public static class Gap extends Transition {
         private final long firstMissingLocalTime;
         private final long firstLocalTimeAfterGap;
@@ -347,6 +366,11 @@ public abstract class LocalTimeOffset {
         }
     }
 
+    /**
+     * Overlap for a local time offset
+     *
+     * @opensearch.internal
+     */
     public static class Overlap extends Transition {
         private final long firstOverlappingLocalTime;
         private final long firstNonOverlappingLocalTime;
@@ -403,6 +427,11 @@ public abstract class LocalTimeOffset {
         }
     }
 
+    /**
+     * Fixed lookup the local time offset
+     *
+     * @opensearch.internal
+     */
     private static class FixedLookup extends Lookup {
         private final ZoneId zone;
         private final LocalTimeOffset fixed;
@@ -441,6 +470,8 @@ public abstract class LocalTimeOffset {
     /**
      * Looks up transitions by checking whether the date is after the start
      * of each transition. Simple so fast for small numbers of transitions.
+     *
+     * @opensearch.internal
      */
     private static class LinkedListLookup extends AbstractManyTransitionsLookup {
         private final LocalTimeOffset lastOffset;
@@ -477,6 +508,8 @@ public abstract class LocalTimeOffset {
     /**
      * Builds an array that can be {@link Arrays#binarySearch(long[], long)}ed
      * for the daylight savings time transitions.
+     *
+     * @openearch.internal
      */
     private static class TransitionArrayLookup extends AbstractManyTransitionsLookup {
         private final LocalTimeOffset[] offsets;
@@ -536,6 +569,11 @@ public abstract class LocalTimeOffset {
         }
     }
 
+    /**
+     * Base class for many transitions lookup
+     *
+     * @opensearch.internal
+     */
     private abstract static class AbstractManyTransitionsLookup extends Lookup {
         protected final ZoneId zone;
         protected final long minUtcMillis;

server/src/main/java/org/opensearch/common/MacAddressProvider.java

@@ -36,6 +36,11 @@ import java.net.NetworkInterface;
 import java.net.SocketException;
 import java.util.Enumeration;
 
+/**
+ * Provider of MAC addressing
+ *
+ * @opensearch.internal
+ */
 public class MacAddressProvider {
 
     private static byte[] getMacAddress() throws SocketException {

server/src/main/java/org/opensearch/common/NamedRegistry.java

@@ -41,6 +41,8 @@ import static java.util.Objects.requireNonNull;
 
 /**
  * A registry from String to some class implementation. Used to ensure implementations are registered only once.
+ *
+ * @opensearch.internal
  */
 public class NamedRegistry<T> {
     private final Map<String, T> registry = new HashMap<>();

server/src/main/java/org/opensearch/common/Numbers.java

@@ -39,6 +39,8 @@ import java.math.BigInteger;
 
 /**
  * A set of utilities for numbers.
+ *
+ * @opensearch.internal
  */
 public final class Numbers {
 

server/src/main/java/org/opensearch/common/ParsingException.java

@@ -46,6 +46,8 @@ import java.io.IOException;
  * Exception that can be used when parsing queries with a given {@link
  * XContentParser}.
  * Can contain information about location of the error.
+ *
+ * @opensearch.internal
  */
 public class ParsingException extends OpenSearchException {
 

server/src/main/java/org/opensearch/common/PidFile.java

@@ -44,6 +44,8 @@ import java.nio.file.StandardOpenOption;
 /**
  * Process ID file abstraction that writes the current pid into a file and optionally
  * removes it on system exit.
+ *
+ * @opensearch.internal
  */
 public final class PidFile {
 

server/src/main/java/org/opensearch/common/Priority.java

@@ -37,6 +37,11 @@ import org.opensearch.common.io.stream.StreamOutput;
 
 import java.io.IOException;
 
+/**
+ * Priority levels.
+ *
+ * @opensearch.internal
+ */
 public enum Priority {
 
     IMMEDIATE((byte) 0),

server/src/main/java/org/opensearch/common/RandomBasedUUIDGenerator.java

@@ -38,6 +38,11 @@ import java.util.Arrays;
 import java.util.Base64;
 import java.util.Random;
 
+/**
+ * Random UUID generator.
+ *
+ * @opensearch.internal
+ */
 class RandomBasedUUIDGenerator implements UUIDGenerator {
 
     /**

server/src/main/java/org/opensearch/common/Randomness.java

@@ -56,6 +56,8 @@ import java.util.concurrent.ThreadLocalRandom;
  * process, non-reproducible sources of randomness are provided (unless
  * a setting is provided for a module that exposes a seed setting (e.g.,
  * NodeEnvironment#NODE_ID_SEED_SETTING)).
+ *
+ * @opensearch.internal
  */
 public final class Randomness {
     private static final Method currentMethod;

server/src/main/java/org/opensearch/common/Rounding.java

@@ -75,6 +75,8 @@ import java.util.concurrent.TimeUnit;
  * See <a href="https://davecturner.github.io/2019/04/14/timezone-rounding.html">this</a>
  * blog for some background reading. Its super interesting and the links are
  * a comedy gold mine. If you like time zones. Or hate them.
+ *
+ * @opensearch.internal
  */
 public abstract class Rounding implements Writeable {
     private static final Logger logger = LogManager.getLogger(Rounding.class);
@@ -347,6 +349,11 @@ public abstract class Rounding implements Writeable {
         return new Builder(interval);
     }
 
+    /**
+     * Builder for rounding
+     *
+     * @opensearch.internal
+     */
     public static class Builder {
 
         private final DateTimeUnit unit;
@@ -426,6 +433,11 @@ public abstract class Rounding implements Writeable {
         }
     }
 
+    /**
+     * Rounding time units
+     *
+     * @opensearch.internal
+     */
     static class TimeUnitRounding extends Rounding {
         static final byte ID = 1;
 
@@ -887,6 +899,11 @@ public abstract class Rounding implements Writeable {
         }
     }
 
+    /**
+     * Rounding time intervals
+     *
+     * @opensearch.internal
+     */
     static class TimeIntervalRounding extends Rounding {
         static final byte ID = 2;
 
@@ -1204,6 +1221,11 @@ public abstract class Rounding implements Writeable {
         }
     }
 
+    /**
+     * Rounding offsets
+     *
+     * @opensearch.internal
+     */
     static class OffsetRounding extends Rounding {
         static final byte ID = 3;
 
@@ -1315,6 +1337,8 @@ public abstract class Rounding implements Writeable {
 
     /**
      * Implementation of {@link Prepared} using pre-calculated "round down" points.
+     *
+     * @opensearch.internal
      */
     private static class ArrayRounding implements Prepared {
         private final long[] values;

server/src/main/java/org/opensearch/common/SecureRandomHolder.java

@@ -34,6 +34,11 @@ package org.opensearch.common;
 
 import java.security.SecureRandom;
 
+/**
+ * Random holder that is secure.
+ *
+ * @opensearch.internal
+ */
 class SecureRandomHolder {
     // class loading is atomic - this is a lazy & safe singleton to be used by this package
     public static final SecureRandom INSTANCE = new SecureRandom();

server/src/main/java/org/opensearch/common/StopWatch.java

@@ -54,7 +54,7 @@ import java.util.concurrent.TimeUnit;
  * This class is normally used to verify performance during proof-of-concepts
  * and in development, rather than as part of production applications.
  *
- *
+ * @opensearch.internal
  */
 public class StopWatch {
 
@@ -239,6 +239,8 @@ public class StopWatch {
 
     /**
      * Inner class to hold data about one task executed within the stop watch.
+     *
+     * @opensearch.internal
      */
     public static class TaskInfo {
 

server/src/main/java/org/opensearch/common/Strings.java

@@ -59,6 +59,11 @@ import java.util.function.Supplier;
 import static java.util.Collections.unmodifiableSet;
 import static org.opensearch.common.util.set.Sets.newHashSet;
 
+/**
+ * String utility class.
+ *
+ * @opensearch.internal
+ */
 public class Strings {
 
     public static final String[] EMPTY_ARRAY = new String[0];

server/src/main/java/org/opensearch/common/SuppressLoggerChecks.java

@@ -39,6 +39,8 @@ import java.lang.annotation.Target;
 
 /**
  * Annotation to suppress logging usage checks errors inside a whole class or a method.
+ *
+ * @opensearch.internal
  */
 @Retention(RetentionPolicy.CLASS)
 @Target({ ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.TYPE })

server/src/main/java/org/opensearch/common/Table.java

@@ -44,6 +44,11 @@ import java.util.concurrent.TimeUnit;
 
 import static java.util.Collections.emptyMap;
 
+/**
+ * A table.
+ *
+ * @opensearch.internal
+ */
 public class Table {
 
     private List<Cell> headers = new ArrayList<>();
@@ -224,6 +229,11 @@ public class Table {
         return headerAliasMap;
     }
 
+    /**
+     * Cell in a table
+     *
+     * @opensearch.internal
+     */
     public static class Cell {
         public final Object value;
         public final Map<String, String> attr;

server/src/main/java/org/opensearch/common/TimeBasedUUIDGenerator.java

@@ -42,6 +42,8 @@ import java.util.concurrent.atomic.AtomicLong;
  * structured.
  * For more information about flake ids, check out
  * https://archive.fo/2015.07.08-082503/http://www.boundary.com/blog/2012/01/flake-a-decentralized-k-ordered-unique-id-generator-in-erlang/
+ *
+ * @opensearch.internal
  */
 
 class TimeBasedUUIDGenerator implements UUIDGenerator {

server/src/main/java/org/opensearch/common/TriConsumer.java

@@ -38,6 +38,8 @@ package org.opensearch.common;
  * @param <S> the type of the first argument
  * @param <T> the type of the second argument
  * @param <U> the type of the third argument
+ *
+ * @opensearch.internal
  */
 @FunctionalInterface
 public interface TriConsumer<S, T, U> {

server/src/main/java/org/opensearch/common/TriFunction.java

@@ -39,6 +39,8 @@ package org.opensearch.common;
  * @param <T> the type of the second argument
  * @param <U> the type of the third argument
  * @param <R> the return type
+ *
+ * @opensearch.internal
  */
 @FunctionalInterface
 public interface TriFunction<S, T, U, R> {

server/src/main/java/org/opensearch/common/UUIDGenerator.java

@@ -34,6 +34,8 @@ package org.opensearch.common;
 
 /**
  * Generates opaque unique strings.
+ *
+ * @opensearch.internal
  */
 interface UUIDGenerator {
     String getBase64UUID();

server/src/main/java/org/opensearch/common/UUIDs.java

@@ -36,6 +36,11 @@ import org.opensearch.common.settings.SecureString;
 
 import java.util.Random;
 
+/**
+ * UUID utility class.
+ *
+ * @opensearch.internal
+ */
 public class UUIDs {
 
     private static final RandomBasedUUIDGenerator RANDOM_UUID_GENERATOR = new RandomBasedUUIDGenerator();

server/src/main/java/org/opensearch/common/ValidationException.java

@@ -37,6 +37,8 @@ import java.util.List;
 
 /**
  * Encapsulates an accumulation of validation errors
+ *
+ * @opensearch.internal
  */
 public class ValidationException extends IllegalArgumentException {
     private final List<String> validationErrors = new ArrayList<>();

server/src/main/java/org/opensearch/common/blobstore/BlobContainer.java

@@ -41,6 +41,8 @@ import java.util.Map;
 
 /**
  * An interface for managing a repository of blob entries, where each blob entry is just a named group of bytes.
+ *
+ * @opensearch.internal
  */
 public interface BlobContainer {
 

server/src/main/java/org/opensearch/common/blobstore/BlobMetadata.java

@@ -34,6 +34,8 @@ package org.opensearch.common.blobstore;
 
 /**
  * An interface for providing basic metadata about a blob.
+ *
+ * @opensearch.internal
  */
 public interface BlobMetadata {
 

server/src/main/java/org/opensearch/common/blobstore/BlobPath.java

@@ -41,6 +41,8 @@ import java.util.List;
 
 /**
  * The list of paths where a blob can reside.  The contents of the paths are dependent upon the implementation of {@link BlobContainer}.
+ *
+ * @opensearch.internal
  */
 public class BlobPath implements Iterable<String> {
 

server/src/main/java/org/opensearch/common/blobstore/BlobStore.java

@@ -37,6 +37,8 @@ import java.util.Map;
 
 /**
  * An interface for storing blobs.
+ *
+ * @opensearch.internal
  */
 public interface BlobStore extends Closeable {
 

server/src/main/java/org/opensearch/common/blobstore/BlobStoreException.java

@@ -37,6 +37,11 @@ import org.opensearch.common.io.stream.StreamInput;
 
 import java.io.IOException;
 
+/**
+ * Thrown on blob store errors
+ *
+ * @opensearch.internal
+ */
 public class BlobStoreException extends OpenSearchException {
 
     public BlobStoreException(String msg) {

server/src/main/java/org/opensearch/common/blobstore/DeleteResult.java

@@ -34,6 +34,8 @@ package org.opensearch.common.blobstore;
 
 /**
  * The result of deleting multiple blobs from a {@link BlobStore}.
+ *
+ * @opensearch.internal
  */
 public final class DeleteResult {
 

server/src/main/java/org/opensearch/common/blobstore/fs/FsBlobContainer.java

@@ -73,6 +73,8 @@ import static java.util.Collections.unmodifiableMap;
  * Note that the methods in this implementation of {@link org.opensearch.common.blobstore.BlobContainer} may
  * additionally throw a {@link java.lang.SecurityException} if the configured {@link java.lang.SecurityManager}
  * does not permit read and/or write access to the underlying files.
+ *
+ * @opensearch.internal
  */
 public class FsBlobContainer extends AbstractBlobContainer {
 

server/src/main/java/org/opensearch/common/blobstore/fs/FsBlobStore.java

@@ -41,6 +41,11 @@ import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
 
+/**
+ * FileSystem blob store
+ *
+ * @opensearch.internal
+ */
 public class FsBlobStore implements BlobStore {
 
     private final Path path;

server/src/main/java/org/opensearch/common/blobstore/support/AbstractBlobContainer.java

@@ -37,6 +37,8 @@ import org.opensearch.common.blobstore.BlobPath;
 
 /**
  * A base abstract blob container that implements higher level container methods.
+ *
+ * @opensearch.internal
  */
 public abstract class AbstractBlobContainer implements BlobContainer {
 

server/src/main/java/org/opensearch/common/blobstore/support/FilterBlobContainer.java

@@ -44,6 +44,11 @@ import java.util.Map;
 import java.util.Objects;
 import java.util.stream.Collectors;
 
+/**
+ * Filter blob container.
+ *
+ * @opensearch.internal
+ */
 public abstract class FilterBlobContainer implements BlobContainer {
 
     private final BlobContainer delegate;

server/src/main/java/org/opensearch/common/blobstore/support/PlainBlobMetadata.java

@@ -34,6 +34,11 @@ package org.opensearch.common.blobstore.support;
 
 import org.opensearch.common.blobstore.BlobMetadata;
 
+/**
+ * Plain blob metadata
+ *
+ * @opensearch.internal
+ */
 public class PlainBlobMetadata implements BlobMetadata {
 
     private final String name;

server/src/main/java/org/opensearch/common/breaker/ChildMemoryCircuitBreaker.java

@@ -42,6 +42,8 @@ import java.util.concurrent.atomic.AtomicLong;
 
 /**
  * Breaker that will check a parent's when incrementing
+ *
+ * @opensearch.internal
  */
 public class ChildMemoryCircuitBreaker implements CircuitBreaker {
 
@@ -268,6 +270,11 @@ public class ChildMemoryCircuitBreaker implements CircuitBreaker {
         this.limitAndOverhead = new LimitAndOverhead(limit, overhead);
     }
 
+    /**
+     * Breaker limit and overhead info
+     *
+     * @opensearch.internal
+     */
     private static class LimitAndOverhead {
 
         private final long limit;

server/src/main/java/org/opensearch/common/breaker/CircuitBreaker.java

@@ -37,6 +37,8 @@ import java.util.Locale;
 /**
  * Interface for an object that can be incremented, breaking after some
  * configured limit has been reached.
+ *
+ * @opensearch.internal
  */
 public interface CircuitBreaker {
 

server/src/main/java/org/opensearch/common/breaker/CircuitBreakingException.java

@@ -42,6 +42,8 @@ import java.io.IOException;
 
 /**
  * Exception thrown when the circuit breaker trips
+ *
+ * @opensearch.internal
  */
 public class CircuitBreakingException extends OpenSearchException {
 

server/src/main/java/org/opensearch/common/breaker/NoopCircuitBreaker.java

@@ -35,6 +35,8 @@ package org.opensearch.common.breaker;
 /**
  * A CircuitBreaker that doesn't increment or adjust, and all operations are
  * basically noops
+ *
+ * @opensearch.internal
  */
 public class NoopCircuitBreaker implements CircuitBreaker {
     public static final int LIMIT = -1;

server/src/main/java/org/opensearch/common/bytes/AbstractBytesReference.java

@@ -41,6 +41,11 @@ import java.io.IOException;
 import java.io.OutputStream;
 import java.util.function.ToIntBiFunction;
 
+/**
+ * Base bytesref class
+ *
+ * @opensearch.internal
+ */
 public abstract class AbstractBytesReference implements BytesReference {
 
     private Integer hash = null; // we cache the hash of this reference since it can be quite costly to re-calculated it

server/src/main/java/org/opensearch/common/bytes/BytesArray.java

@@ -39,6 +39,11 @@ import java.io.IOException;
 import java.io.OutputStream;
 import java.util.Arrays;
 
+/**
+ * A bytes array.
+ *
+ * @opensearch.internal
+ */
 public final class BytesArray extends AbstractBytesReference {
 
     public static final BytesArray EMPTY = new BytesArray(BytesRef.EMPTY_BYTES, 0, 0);

server/src/main/java/org/opensearch/common/bytes/BytesReference.java

@@ -49,6 +49,8 @@ import java.util.ArrayList;
 
 /**
  * A reference to bytes.
+ *
+ * @opensearch.internal
  */
 public interface BytesReference extends Comparable<BytesReference>, ToXContentFragment {
 

server/src/main/java/org/opensearch/common/bytes/CompositeBytesReference.java

@@ -47,6 +47,8 @@ import java.util.Objects;
  * into one without copying.
  *
  * Note, {@link #toBytesRef()} will materialize all pages in this BytesReference.
+ *
+ * @opensearch.internal
  */
 public final class CompositeBytesReference extends AbstractBytesReference {
 

server/src/main/java/org/opensearch/common/bytes/PagedBytesReference.java

@@ -42,6 +42,8 @@ import java.io.IOException;
 /**
  * A page based bytes reference, internally holding the bytes in a paged
  * data structure.
+ *
+ * @opensearch.internal
  */
 public class PagedBytesReference extends AbstractBytesReference {
 

server/src/main/java/org/opensearch/common/bytes/RecyclingBytesStreamOutput.java

@@ -49,6 +49,8 @@ import java.util.Objects;
  * {@link BigArrays} if needed. The idea is that you can use this for passing data to an API that requires a single {@code byte[]} (or a
  * {@link org.apache.lucene.util.BytesRef}) which you'd prefer to re-use if possible, avoiding excessive allocations, but which may not
  * always be large enough.
+ *
+ * @opensearch.internal
  */
 public class RecyclingBytesStreamOutput extends BytesStream {
 

server/src/main/java/org/opensearch/common/bytes/ReleasableBytesReference.java

@@ -45,6 +45,8 @@ import java.io.OutputStream;
 /**
  * An extension to {@link BytesReference} that requires releasing its content. This
  * class exists to make it explicit when a bytes reference needs to be released, and when not.
+ *
+ * @opensearch.internal
  */
 public final class ReleasableBytesReference implements Releasable, BytesReference {
 

server/src/main/java/org/opensearch/common/cache/Cache.java

@@ -79,6 +79,8 @@ import java.util.function.ToLongBiFunction;
  *
  * @param <K> The type of the keys
  * @param <V> The type of the values
+ *
+ * @opensearch.internal
  */
 public class Cache<K, V> {
 
@@ -173,6 +175,11 @@ public class Cache<K, V> {
         DELETED
     }
 
+    /**
+     * Entry in a cache
+     *
+     * @opensearch.internal
+     */
     static class Entry<K, V> {
         final K key;
         final V value;
@@ -196,6 +203,8 @@ public class Cache<K, V> {
      *
      * @param <K> the type of the keys
      * @param <V> the type of the values
+     *
+     * @opensearch.internal
      */
     private static class CacheSegment<K, V> {
         // read/write lock protecting mutations to the segment
@@ -329,6 +338,11 @@ public class Cache<K, V> {
             }
         }
 
+        /**
+         * Segment statistics
+         *
+         * @opensearch.internal
+         */
         private static class SegmentStats {
             private final LongAdder hits = new LongAdder();
             private final LongAdder misses = new LongAdder();
@@ -717,6 +731,11 @@ public class Cache<K, V> {
         return new CacheStats(hits, misses, evictions);
     }
 
+    /**
+     * Cache statistics
+     *
+     * @opensearch.internal
+     */
     public static class CacheStats {
         private long hits;
         private long misses;

server/src/main/java/org/opensearch/common/cache/CacheBuilder.java

@@ -37,6 +37,11 @@ import org.opensearch.common.unit.TimeValue;
 import java.util.Objects;
 import java.util.function.ToLongBiFunction;
 
+/**
+ * The cache builder.
+ *
+ * @opensearch.internal
+ */
 public class CacheBuilder<K, V> {
     private long maximumWeight = -1;
     private long expireAfterAccessNanos = -1;

server/src/main/java/org/opensearch/common/cache/CacheLoader.java

@@ -32,6 +32,11 @@
 
 package org.opensearch.common.cache;
 
+/**
+ * An interface for a cache loader.
+ *
+ * @opensearch.internal
+ */
 @FunctionalInterface
 public interface CacheLoader<K, V> {
     V load(K key) throws Exception;

server/src/main/java/org/opensearch/common/cache/RemovalListener.java

@@ -32,6 +32,11 @@
 
 package org.opensearch.common.cache;
 
+/**
+ * Listener for removing an element from the cache
+ *
+ * @opensearch.internal
+ */
 @FunctionalInterface
 public interface RemovalListener<K, V> {
     void onRemoval(RemovalNotification<K, V> notification);

server/src/main/java/org/opensearch/common/cache/RemovalNotification.java

@@ -32,6 +32,11 @@
 
 package org.opensearch.common.cache;
 
+/**
+ * Notification when an element is removed from the cache
+ *
+ * @opensearch.internal
+ */
 public class RemovalNotification<K, V> {
     public enum RemovalReason {
         REPLACED,

server/src/main/java/org/opensearch/common/collect/CopyOnWriteHashMap.java

@@ -62,6 +62,8 @@ import java.util.stream.Stream;
  * it is better suited for work-loads that are not too write-intensive.
  *
  * @see <a href="http://en.wikipedia.org/wiki/Hash_array_mapped_trie">the wikipedia page</a>
+ *
+ * @opensearch.internal
  */
 public final class CopyOnWriteHashMap<K, V> extends AbstractMap<K, V> {
 
@@ -87,6 +89,8 @@ public final class CopyOnWriteHashMap<K, V> extends AbstractMap<K, V> {
 
     /**
      * Abstraction of a node, implemented by both inner and leaf nodes.
+     *
+     * @opensearch.internal
      */
     private abstract static class Node<K, V> {
 
@@ -124,6 +128,8 @@ public final class CopyOnWriteHashMap<K, V> extends AbstractMap<K, V> {
 
     /**
      * A leaf of the tree where all hashes are equal. Values are added and retrieved in linear time.
+     *
+     * @opensearch.internal
      */
     private static class Leaf<K, V> extends Node<K, V> {
 
@@ -247,6 +253,8 @@ public final class CopyOnWriteHashMap<K, V> extends AbstractMap<K, V> {
      *
      * As a consequence, the number of slots in an inner node is equal to the
      * number of one bits in the bitmap.
+     *
+     * @opensearch.internal
      */
     private static class InnerNode<K, V> extends Node<K, V> {
 
@@ -440,6 +448,11 @@ public final class CopyOnWriteHashMap<K, V> extends AbstractMap<K, V> {
 
     }
 
+    /**
+     * Iterates over an entry
+     *
+     * @opensearch.internal
+     */
     private static class EntryIterator<K, V> implements Iterator<Map.Entry<K, V>> {
 
         private final Deque<Map.Entry<K, V>> entries;

server/src/main/java/org/opensearch/common/collect/EvictingQueue.java

@@ -60,6 +60,8 @@ import java.util.Queue;
  * full queue, elements are evicted from the head of the queue to accommodate the new elements.
  *
  * @param <T> The type of elements in the queue.
+ *
+ * @opensearch.internal
  */
 public class EvictingQueue<T> implements Queue<T> {
     private final int maximumSize;

server/src/main/java/org/opensearch/common/collect/HppcMaps.java

@@ -39,6 +39,11 @@ import com.carrotsearch.hppc.cursors.ObjectCursor;
 
 import java.util.Iterator;
 
+/**
+ * High performance maps
+ *
+ * @opensearch.internal
+ */
 public final class HppcMaps {
 
     private HppcMaps() {}

server/src/main/java/org/opensearch/common/collect/ImmutableOpenIntMap.java

@@ -54,6 +54,8 @@ import java.util.Map;
  * <p>
  * Can be constructed using a {@link #builder()}, or using {@link #builder(org.opensearch.common.collect.ImmutableOpenIntMap)}
  * (which is an optimized option to copy over existing content and modify it).
+ *
+ * @opensearch.internal
  */
 public final class ImmutableOpenIntMap<VType> implements Iterable<IntObjectCursor<VType>> {
 
@@ -223,6 +225,11 @@ public final class ImmutableOpenIntMap<VType> implements Iterable<IntObjectCurso
         return new Builder<>(map);
     }
 
+    /**
+     * Base builder for an immutable int
+     *
+     * @opensearch.internal
+     */
     public static class Builder<VType> implements IntObjectMap<VType> {
 
         private IntObjectHashMap<VType> map;

server/src/main/java/org/opensearch/common/collect/ImmutableOpenMap.java

@@ -52,6 +52,8 @@ import java.util.Map;
  * <p>
  * Can be constructed using a {@link #builder()}, or using {@link #builder(ImmutableOpenMap)} (which is an optimized
  * option to copy over existing content and modify it).
+ *
+ * @opensearch.internal
  */
 public final class ImmutableOpenMap<KType, VType> implements Iterable<ObjectObjectCursor<KType, VType>> {
 
@@ -238,6 +240,11 @@ public final class ImmutableOpenMap<KType, VType> implements Iterable<ObjectObje
         return new Builder<>(map);
     }
 
+    /**
+     * Builder for an immuatable map
+     *
+     * @opensearch.internal
+     */
     public static class Builder<KType, VType> implements ObjectObjectMap<KType, VType> {
         private ObjectObjectHashMap<KType, VType> map;
 

server/src/main/java/org/opensearch/common/collect/Iterators.java

@@ -45,6 +45,11 @@ public class Iterators {
         return new ConcatenatedIterator<T>(iterators);
     }
 
+    /**
+     * Concat iterators
+     *
+     * @opensearch.internal
+     */
     static class ConcatenatedIterator<T> implements Iterator<T> {
         private final Iterator<? extends T>[] iterators;
         private int index = 0;

server/src/main/java/org/opensearch/common/collect/MapBuilder.java

@@ -37,6 +37,11 @@ import java.util.Map;
 
 import static java.util.Collections.unmodifiableMap;
 
+/**
+ * Builder for a map.
+ *
+ * @opensearch.internal
+ */
 public class MapBuilder<K, V> {
 
     public static <K, V> MapBuilder<K, V> newMapBuilder() {

server/src/main/java/org/opensearch/common/component/AbstractLifecycleComponent.java

@@ -37,6 +37,11 @@ import java.io.UncheckedIOException;
 import java.util.List;
 import java.util.concurrent.CopyOnWriteArrayList;
 
+/**
+ * Base class for a lifecycle component.
+ *
+ * @opensearch.internal
+ */
 public abstract class AbstractLifecycleComponent implements LifecycleComponent {
 
     protected final Lifecycle lifecycle = new Lifecycle();

server/src/main/java/org/opensearch/common/component/Lifecycle.java

@@ -72,6 +72,8 @@ package org.opensearch.common.component;
  *  // perform close logic here
  * }
  * </pre>
+ *
+ * @opensearch.internal
  */
 public class Lifecycle {
 

server/src/main/java/org/opensearch/common/component/LifecycleComponent.java

@@ -34,6 +34,11 @@ package org.opensearch.common.component;
 
 import org.opensearch.common.lease.Releasable;
 
+/**
+ * Base interface for a lifecycle component.
+ *
+ * @opensearch.internal
+ */
 public interface LifecycleComponent extends Releasable {
 
     Lifecycle.State lifecycleState();

server/src/main/java/org/opensearch/common/component/LifecycleListener.java

@@ -32,6 +32,11 @@
 
 package org.opensearch.common.component;
 
+/**
+ * Base lifecycle listener.
+ *
+ * @opensearch.internal
+ */
 public abstract class LifecycleListener {
 
     public void beforeStart() {

server/src/main/java/org/opensearch/common/compress/CompressedXContent.java

@@ -54,6 +54,8 @@ import java.util.zip.CheckedOutputStream;
  * data using a compressed representation in order to require less permanent
  * memory. Note that the compressed string might still sometimes need to be
  * decompressed in order to perform equality checks or to compute hash codes.
+ *
+ * @opensearch.internal
  */
 public final class CompressedXContent {
 

server/src/main/java/org/opensearch/common/compress/Compressor.java

@@ -38,6 +38,11 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
 
+/**
+ * Compressor interface
+ *
+ * @opensearch.internal
+ */
 public interface Compressor {
 
     boolean isCompressed(BytesReference bytes);

server/src/main/java/org/opensearch/common/compress/CompressorFactory.java

@@ -40,6 +40,11 @@ import org.opensearch.common.xcontent.XContentType;
 import java.io.IOException;
 import java.util.Objects;
 
+/**
+ * Factory to create a compressor instance.
+ *
+ * @opensearch.internal
+ */
 public class CompressorFactory {
 
     public static final Compressor COMPRESSOR = new DeflateCompressor();

server/src/main/java/org/opensearch/common/compress/DeflateCompressor.java

@@ -51,6 +51,8 @@ import java.util.zip.InflaterOutputStream;
 
 /**
  * {@link Compressor} implementation based on the DEFLATE compression algorithm.
+ *
+ * @opensearch.internal
  */
 public class DeflateCompressor implements Compressor {
 

server/src/main/java/org/opensearch/common/compress/NotCompressedException.java

@@ -32,9 +32,13 @@
 
 package org.opensearch.common.compress;
 
-/** Exception indicating that we were expecting something compressed, which
+/**
- *  was not compressed or corrupted so that the compression format could not
+ * Exception indicating that we were expecting something compressed, which
- *  be detected. */
+ * was not compressed or corrupted so that the compression format could not
+ * be detected.
+ *
+ *  @opensearch.internal
+ */
 public class NotCompressedException extends RuntimeException {
 
     public NotCompressedException() {

server/src/main/java/org/opensearch/common/compress/NotXContentException.java

@@ -34,8 +34,12 @@ package org.opensearch.common.compress;
 
 import org.opensearch.common.xcontent.XContent;
 
-/** Exception indicating that we were expecting some {@link XContent} but could
+/**
- *  not detect its type. */
+ * Exception indicating that we were expecting some {@link XContent} but could
+ * not detect its type.
+ *
+ * @opensearch.internal
+ */
 public class NotXContentException extends RuntimeException {
 
     public NotXContentException(String message) {

server/src/main/java/org/opensearch/common/concurrent/AutoCloseableRefCounted.java

@@ -18,6 +18,8 @@ import org.opensearch.common.util.concurrent.RefCounted;
 /**
  * Adapter class that enables a {@link RefCounted} implementation to function like an {@link AutoCloseable}.
  * The {@link #close()} API invokes {@link RefCounted#decRef()} and ensures idempotency using a {@link OneWayGate}.
+ *
+ * @opensearch.internal
  */
 public class AutoCloseableRefCounted<T extends RefCounted> implements AutoCloseable {
 

server/src/main/java/org/opensearch/common/concurrent/GatedCloseable.java

@@ -22,6 +22,8 @@ import java.io.IOException;
  * Decorator class that wraps an object reference with a {@link CheckedRunnable} that is
  * invoked when {@link #close()} is called. The internal {@link OneWayGate} instance ensures
  * that this is invoked only once. See also {@link AutoCloseableRefCounted}
+ *
+ * @opensearch.internal
  */
 public class GatedCloseable<T> implements Closeable {
 

server/src/main/java/org/opensearch/common/concurrent/OneWayGate.java

@@ -18,6 +18,8 @@ import java.util.concurrent.atomic.AtomicBoolean;
 /**
  * Encapsulates logic for a one-way gate. Guarantees idempotency via the {@link AtomicBoolean} instance
  * and the return value of the {@link #close()} function.
+ *
+ * @opensearch.internal
  */
 public class OneWayGate {
 

server/src/main/java/org/opensearch/common/concurrent/RefCountedReleasable.java

@@ -20,6 +20,8 @@ import org.opensearch.common.util.concurrent.AbstractRefCounted;
  * Decorator class that wraps an object reference as a {@link AbstractRefCounted} instance.
  * In addition to a {@link String} name, it accepts a {@link Runnable} shutdown hook that is
  * invoked when the reference count reaches zero i.e. on {@link #closeInternal()}.
+ *
+ * @opensearch.internal
  */
 public class RefCountedReleasable<T> extends AbstractRefCounted implements Releasable {
 

server/src/main/java/org/opensearch/common/document/DocumentField.java

@@ -55,6 +55,8 @@ import static org.opensearch.common.xcontent.XContentParserUtils.parseFieldsValu
  *
  * @see SearchHit
  * @see GetResult
+ *
+ * @opensearch.internal
  */
 public class DocumentField implements Writeable, ToXContentFragment, Iterable<Object> {
 

server/src/main/java/org/opensearch/common/geo/GeoBoundingBox.java

@@ -52,6 +52,8 @@ import java.util.Objects;
 /**
  * A class representing a Geo-Bounding-Box for use by Geo queries and aggregations
  * that deal with extents/rectangles representing rectangular areas of interest.
+ *
+ * @opensearch.internal
  */
 public class GeoBoundingBox implements ToXContentObject, Writeable {
     private static final WellKnownText WKT_PARSER = new WellKnownText(true, new StandardValidator(true));

server/src/main/java/org/opensearch/common/geo/GeoDistance.java

@@ -42,6 +42,8 @@ import java.util.Locale;
 
 /**
  * Geo distance calculation.
+ *
+ * @opensearch.internal
  */
 public enum GeoDistance implements Writeable {
     PLANE,

server/src/main/java/org/opensearch/common/geo/GeoJson.java

@@ -593,6 +593,11 @@ public final class GeoJson {
         });
     }
 
+    /**
+     * A node for a geo coordinate
+     *
+     * @opensearch.internal
+     */
     private static class CoordinateNode implements ToXContentObject {
         public final Point coordinate;
         public final List<CoordinateNode> children;

server/src/main/java/org/opensearch/common/geo/GeoJsonGeometryFormat.java

@@ -39,6 +39,11 @@ import org.opensearch.geometry.Geometry;
 
 import java.io.IOException;
 
+/**
+ * Geometry format for geojson
+ *
+ * @opensearch.internal
+ */
 public class GeoJsonGeometryFormat implements GeometryFormat<Geometry> {
     public static final String NAME = "geojson";
 

server/src/main/java/org/opensearch/common/geo/GeoLineDecomposer.java

@@ -42,6 +42,8 @@ import static org.opensearch.common.geo.GeoUtils.normalizePoint;
 
 /**
  * Splits lines by datelines.
+ *
+ * @opensearch.internal
  */
 public class GeoLineDecomposer {
 

server/src/main/java/org/opensearch/common/geo/GeoPoint.java

@@ -56,6 +56,11 @@ import java.util.Locale;
 
 import static org.opensearch.index.mapper.AbstractPointGeometryFieldMapper.Names.IGNORE_Z_VALUE;
 
+/**
+ * Core geo point
+ *
+ * @opensearch.internal
+ */
 public class GeoPoint implements ToXContentFragment {
 
     protected double lat;

server/src/main/java/org/opensearch/common/geo/GeoPolygonDecomposer.java

@@ -55,6 +55,8 @@ import static org.opensearch.common.geo.GeoUtils.normalizeLon;
 
 /**
  * Splits polygons by datelines.
+ *
+ * @opensearch.internal
  */
 public class GeoPolygonDecomposer {
 

server/src/main/java/org/opensearch/common/geo/GeoShapeType.java

@@ -57,6 +57,8 @@ import java.util.Map;
 
 /**
  * Enumeration that lists all {@link GeoShapeType}s that can be parsed and indexed
+ *
+ * @opensearch.internal
  */
 public enum GeoShapeType {
     POINT("point") {

server/src/main/java/org/opensearch/common/geo/GeoShapeUtils.java

@@ -39,6 +39,8 @@ import org.opensearch.geometry.Rectangle;
 
 /**
  * Utility class that transforms OpenSearch geometry objects to the Lucene representation
+ *
+ * @opensearch.internal
  */
 public class GeoShapeUtils {
 

server/src/main/java/org/opensearch/common/geo/GeoUtils.java

@@ -54,6 +54,11 @@ import org.opensearch.index.fielddata.SortingNumericDoubleValues;
 import java.io.IOException;
 import java.util.Collections;
 
+/**
+ * Useful geo utilities
+ *
+ * @opensearch.internal
+ */
 public class GeoUtils {
 
     /** Maximum valid latitude in degrees. */

server/src/main/java/org/opensearch/common/geo/GeometryFormat.java

@@ -41,6 +41,8 @@ import java.text.ParseException;
 
 /**
  * Geometry serializer/deserializer
+ *
+ * @opensearch.internal
  */
 public interface GeometryFormat<ParsedFormat> {
 

server/src/main/java/org/opensearch/common/geo/GeometryIO.java

@@ -55,6 +55,8 @@ import java.util.Locale;
 
 /**
  * Utility class for binary serializtion/deserialization of libs/geo classes
+ *
+ * @opensearch.internal
  */
 public final class GeometryIO {
 

server/src/main/java/org/opensearch/common/geo/GeometryParser.java

@@ -53,6 +53,8 @@ import java.util.Map;
 
 /**
  * An utility class with a geometry parser methods supporting different shape representation formats
+ *
+ * @opensearch.internal
  */
 public final class GeometryParser {
 

server/src/main/java/org/opensearch/common/geo/ShapeRelation.java

@@ -43,6 +43,8 @@ import java.util.Locale;
 /**
  * Enum representing the relationship between a Query / Filter Shape and indexed Shapes
  * that will be used to determine if a Document should be matched or not
+ *
+ * @opensearch.internal
  */
 public enum ShapeRelation implements Writeable {
 

server/src/main/java/org/opensearch/common/geo/ShapesAvailability.java

@@ -32,6 +32,11 @@
 
 package org.opensearch.common.geo;
 
+/**
+ * Checks if certain geometry packages are available
+ *
+ * @opensearch.internal
+ */
 public class ShapesAvailability {
 
     public static final boolean SPATIAL4J_AVAILABLE;

server/src/main/java/org/opensearch/common/geo/SpatialStrategy.java

@@ -37,6 +37,14 @@ import org.opensearch.common.io.stream.Writeable;
 
 import java.io.IOException;
 
+/**
+ * Spatial strategy for legacy prefix trees
+ *
+ * @deprecated will be removed in future version
+ *
+ * @opensearch.internal
+ */
+@Deprecated
 public enum SpatialStrategy implements Writeable {
 
     TERM("term"),

server/src/main/java/org/opensearch/common/geo/WKTGeometryFormat.java

@@ -41,6 +41,11 @@ import org.opensearch.geometry.utils.WellKnownText;
 import java.io.IOException;
 import java.text.ParseException;
 
+/**
+ * Well Known Text Format
+ *
+ * @opensearch.internal
+ */
 public class WKTGeometryFormat implements GeometryFormat<Geometry> {
     public static final String NAME = "wkt";
 

server/src/main/java/org/opensearch/common/geo/XShapeCollection.java

@@ -40,6 +40,8 @@ import java.util.List;
 
 /**
  * Extends spatial4j ShapeCollection for points_only shape indexing support
+ *
+ * @opensearch.internal
  */
 public class XShapeCollection<S extends Shape> extends ShapeCollection<S> {
 

server/src/main/java/org/opensearch/common/geo/builders/CircleBuilder.java

@@ -47,6 +47,11 @@ import org.opensearch.common.xcontent.XContentBuilder;
 import java.io.IOException;
 import java.util.Objects;
 
+/**
+ * Builds a circle geometry
+ *
+ * @opensearch.internal
+ */
 public class CircleBuilder extends ShapeBuilder<Circle, org.opensearch.geometry.Circle, CircleBuilder> {
 
     public static final ParseField FIELD_RADIUS = new ParseField("radius");

server/src/main/java/org/opensearch/common/geo/builders/CoordinatesBuilder.java

@@ -44,6 +44,8 @@ import java.util.List;
  * A builder for a list of coordinates.
  * Enables chaining of individual coordinates either as long/lat pairs
  * or as {@link Coordinate} elements, arrays or collections.
+ *
+ * @opensearch.internal
  */
 public class CoordinatesBuilder {
 

server/src/main/java/org/opensearch/common/geo/builders/EnvelopeBuilder.java

@@ -45,6 +45,11 @@ import org.opensearch.common.xcontent.XContentBuilder;
 import java.io.IOException;
 import java.util.Objects;
 
+/**
+ * Builds an envelope geometry
+ *
+ * @opensearch.internal
+ */
 public class EnvelopeBuilder extends ShapeBuilder<Rectangle, org.opensearch.geometry.Rectangle, EnvelopeBuilder> {
 
     public static final GeoShapeType TYPE = GeoShapeType.ENVELOPE;