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

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

Signed-off-by: Nicholas Walter Knize <[email protected]>
(cherry picked from commit ad7ce4c)

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

@@ -35,6 +35,8 @@
 
 /**
  * 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 @@
 
 /**
  * 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 @@
 
 /**
  * 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 @@
 
 /**
  * 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 @@
 
 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 @@
  * 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 @@
 /**
  * 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 @@
 
 /**
  * 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 @@
  * 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 @@
  * <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 String toString() {
 
     /**
      * How to get instances of {@link LocalTimeOffset}.
+     *
+     * @opensearch.internal
      */
     public abstract static class Lookup {
         /**
@@ -234,6 +238,11 @@ public abstract static class Lookup {
         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 @@ protected String toString(long millis) {
         }
     }
 
+    /**
+     * 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 long startUtcMillis() {
         }
     }
 
+    /**
+     * 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 @@ protected String toString(long millis) {
         }
     }
 
+    /**
+     * 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 @@ protected String toString(long millis) {
         }
     }
 
+    /**
+     * 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 boolean anyMoveBackToPreviousDay() {
     /**
      * 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 boolean anyMoveBackToPreviousDay() {
     /**
      * 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 String toString() {
         }
     }
 
+    /**
+     * 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.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 @@
 
 /**
  * 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 @@
 
 /**
  * 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 @@
  * 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 @@
 /**
  * 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 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.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 @@
  * 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 @@
  * 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 static Builder builder(TimeValue interval) {
         return new Builder(interval);
     }
 
+    /**
+     * Builder for rounding
+     *
+     * @opensearch.internal
+     */
     public static class Builder {
 
         private final DateTimeUnit unit;
@@ -426,6 +433,11 @@ protected Prepared maybeUseArray(long minUtcMillis, long maxUtcMillis, int max)
         }
     }
 
+    /**
+     * Rounding time units
+     *
+     * @opensearch.internal
+     */
     static class TimeUnitRounding extends Rounding {
         static final byte ID = 1;
 
@@ -887,6 +899,11 @@ public final long nextRoundingValue(long utcMillis) {
         }
     }
 
+    /**
+     * Rounding time intervals
+     *
+     * @opensearch.internal
+     */
     static class TimeIntervalRounding extends Rounding {
         static final byte ID = 2;
 
@@ -1204,6 +1221,11 @@ public long nextRoundingValue(long utcMillis) {
         }
     }
 
+    /**
+     * Rounding offsets
+     *
+     * @opensearch.internal
+     */
     static class OffsetRounding extends Rounding {
         static final byte ID = 3;
 
@@ -1315,6 +1337,8 @@ public static Rounding read(StreamInput in) throws IOException {
 
     /**
      * 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 @@
 
 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 @@
  * 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 String toString() {
 
     /**
      * 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 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 @@
 
 /**
  * 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 })