[Refactor] core.common to new opensearch-common library (#5976)

Refactors all of o.opensearch.common classes in the core library to a new
opensearch-commons library (inspired by apache commons). The intent is to
refactor any o.opensearch.common.* classes in :server module to this new
library. This will be done with care such that the dependencies are carefully
managed to avoid any cyclic or unnecessarily complicated dependencies.

Signed-off-by: Nicholas Walter Knize <[email protected]>

CHANGELOG.md

@@ -94,6 +94,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Use ReplicationFailedException instead of OpensearchException in ReplicationTarget ([#4725](https://github.com/opensearch-project/OpenSearch/pull/4725))
 - [Refactor] Use local opensearch.common.SetOnce instead of lucene's utility class ([#5947](https://github.com/opensearch-project/OpenSearch/pull/5947))
 - Cluster health call to throw decommissioned exception for local decommissioned node([#6008](https://github.com/opensearch-project/OpenSearch/pull/6008))
+- [Refactor] core.common to new opensearch-common library ([#5976](https://github.com/opensearch-project/OpenSearch/pull/5976))
 
 ### Deprecated
 

buildSrc/build.gradle

@@ -191,6 +191,7 @@ if (project != rootProject) {
     distribution project(':distribution:archives:linux-tar')
     distribution project(':distribution:archives:windows-zip')
 
+    integTestRuntimeOnly(project(":libs:opensearch-common"))
     integTestRuntimeOnly(project(":libs:opensearch-core"))
   }
 

buildSrc/src/main/java/org/opensearch/gradle/precommit/JarHellPrecommitPlugin.java

@@ -44,11 +44,11 @@ public class JarHellPrecommitPlugin extends PrecommitPlugin {
     @Override
     public TaskProvider<? extends Task> createTask(Project project) {
         Configuration jarHellConfig = project.getConfigurations().create("jarHell");
-        if (BuildParams.isInternal() && project.getPath().equals(":libs:opensearch-core") == false) {
+        if (BuildParams.isInternal() && project.getPath().equals(":libs:opensearch-common") == false) {
             // External plugins will depend on this already via transitive dependencies.
             // Internal projects are not all plugins, so make sure the check is available
             // we are not doing this for this project itself to avoid jar hell with itself
-            project.getDependencies().add("jarHell", project.project(":libs:opensearch-core"));
+            project.getDependencies().add("jarHell", project.project(":libs:opensearch-common"));
         }
 
         TaskProvider<JarHellTask> jarHell = project.getTasks().register("jarHell", JarHellTask.class);

gradle/missing-javadoc.gradle

@@ -96,7 +96,6 @@ configure([
   project(":client:rest-high-level"),
   project(":client:test"),
   project(":libs:opensearch-cli"),
-  project(":libs:opensearch-core"),
   project(":libs:opensearch-dissect"),
   project(":libs:opensearch-geo"),
   project(":libs:opensearch-grok"),
@@ -162,7 +161,11 @@ configure([
   }
 }
 
-configure(project(":server")) {
+configure([
+  project(":libs:opensearch-common"),
+  project(":libs:opensearch-core"),
+  project(":server")
+]) {
   project.tasks.withType(MissingJavadocTask) {
     // TODO: bump to variable missing level after increasing javadoc coverage
     javadocMissingLevel = "class"

libs/build.gradle

@@ -44,11 +44,12 @@ subprojects {
       dependencies.matching { it instanceof ProjectDependency }.all { ProjectDependency dep ->
         Project depProject = dep.dependencyProject
         if (depProject != null
-          && false == depProject.path.equals(':libs:opensearch-core')
+          && (false == depProject.path.equals(':libs:opensearch-core') &&
+              false == depProject.path.equals(':libs:opensearch-common'))
           && depProject.path.startsWith(':libs')) {
           throw new InvalidUserDataException("projects in :libs "
             + "may not depend on other projects libs except "
-            + ":libs:opensearch-core but "
+            + ":libs:opensearch-core or :libs:opensearch-common but "
             + "${project.path} depends on ${depProject.path}")
         }
       }

libs/cli/build.gradle

@@ -33,6 +33,7 @@ apply plugin: 'opensearch.publish'
 
 dependencies {
   api 'net.sf.jopt-simple:jopt-simple:5.0.4'
+  api project(':libs:opensearch-common')
   api project(':libs:opensearch-core')
 }
 

libs/common/build.gradle

@@ -0,0 +1,35 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ *
+ * Modifications Copyright OpenSearch Contributors. See
+ * GitHub history for details.
+ */
+
+import org.opensearch.gradle.info.BuildParams
+
+apply plugin: 'opensearch.publish'
+
+archivesBaseName = 'opensearch-common'
+
+dependencies {
+  // This dependency is used only by :libs:core for null-checking interop with other tools
+  compileOnly "com.google.code.findbugs:jsr305:3.0.2"
+
+  testImplementation "com.carrotsearch.randomizedtesting:randomizedtesting-runner:${versions.randomizedrunner}"
+  testImplementation "junit:junit:${versions.junit}"
+  testImplementation "org.hamcrest:hamcrest:${versions.hamcrest}"
+
+  testImplementation(project(":test:framework")) {
+    exclude group: 'org.opensearch', module: 'opensearch-common'
+  }
+}
+
+tasks.named('forbiddenApisMain').configure {
+  // :libs:opensearch-common does not depend on server
+  // TODO: Need to decide how we want to handle for forbidden signatures with the changes to server
+  replaceSignatureFiles 'jdk-signatures'
+}

libs/core/src/main/java/org/opensearch/bootstrap/JarHell.java → libs/common/src/main/java/org/opensearch/bootstrap/JarHell.java

@@ -71,6 +71,8 @@
  *   <li>Checks any {@code X-Compile-OpenSearch-Version} value in
  *       the jar manifest is compatible with the current ES</li>
  * </ul>
+ *
+ * @opensearch.internal
  */
 public class JarHell {
 

libs/core/src/main/java/org/opensearch/bootstrap/JdkJarHellCheck.java → libs/common/src/main/java/org/opensearch/bootstrap/JdkJarHellCheck.java

@@ -44,6 +44,11 @@
 import java.util.HashSet;
 import java.util.Set;
 
+/**
+ * Checks for jdk jar hell
+ *
+ * @opensearch.internal
+ */
 public class JdkJarHellCheck {
 
     private Set<String> detected = new HashSet<>();

libs/common/src/main/java/org/opensearch/bootstrap/package-info.java

@@ -0,0 +1,10 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+/** Contains JarHell Classes */
+package org.opensearch.bootstrap;

libs/core/src/main/java/org/opensearch/common/Booleans.java → libs/common/src/main/java/org/opensearch/common/Booleans.java

@@ -32,6 +32,11 @@
 
 package org.opensearch.common;
 
+/**
+ * Boolean class utilities
+ *
+ * @opensearch.api
+ */
 public final class Booleans {
     private Booleans() {
         throw new AssertionError("No instances intended");

libs/core/src/main/java/org/opensearch/common/CharArrays.java → libs/common/src/main/java/org/opensearch/common/CharArrays.java

@@ -40,6 +40,8 @@
 
 /**
  * Helper class similar to Arrays to handle conversions for Char arrays
+ *
+ * @opensearch.api
  */
 public final class CharArrays {
 

libs/core/src/main/java/org/opensearch/common/CheckedConsumer.java → libs/common/src/main/java/org/opensearch/common/CheckedConsumer.java

@@ -36,6 +36,8 @@
 
 /**
  * A {@link Consumer}-like interface which allows throwing checked exceptions.
+ *
+ * @opensearch.api
  */
 @FunctionalInterface
 public interface CheckedConsumer<T, E extends Exception> {

libs/core/src/main/java/org/opensearch/common/CheckedFunction.java → libs/common/src/main/java/org/opensearch/common/CheckedFunction.java

@@ -36,6 +36,8 @@
 
 /**
  * A {@link Function}-like interface which allows throwing checked exceptions.
+ *
+ * @opensearch.api
  */
 @FunctionalInterface
 public interface CheckedFunction<T, R, E extends Exception> {

libs/core/src/main/java/org/opensearch/common/CheckedRunnable.java → libs/common/src/main/java/org/opensearch/common/CheckedRunnable.java

@@ -34,6 +34,8 @@
 
 /**
  * A {@link Runnable}-like interface which allows throwing checked exceptions.
+ *
+ * @opensearch.api
  */
 @FunctionalInterface
 public interface CheckedRunnable<E extends Exception> {

libs/core/src/main/java/org/opensearch/common/Glob.java → libs/common/src/main/java/org/opensearch/common/Glob.java

@@ -34,6 +34,8 @@
 
 /**
  * Utility class for glob-like matching
+ *
+ * @opensearch.api
  */
 public class Glob {
 

libs/core/src/main/java/org/opensearch/common/MemoizedSupplier.java → libs/common/src/main/java/org/opensearch/common/MemoizedSupplier.java

@@ -34,6 +34,11 @@
 
 import java.util.function.Supplier;
 
+/**
+ * A base supplier using memoization optimization technique
+ *
+ * @opensearch.api
+ */
 public class MemoizedSupplier<T> implements Supplier<T> {
     private Supplier<T> supplier;
     private T value;

libs/core/src/main/java/org/opensearch/common/Nullable.java → libs/common/src/main/java/org/opensearch/common/Nullable.java

@@ -45,7 +45,7 @@
  * {@code null} is an acceptable value for that parameter.  It should not be
  * used for parameters of primitive types.
  *
- *
+ * @opensearch.api
  */
 @Documented
 @TypeQualifierNickname

libs/core/src/main/java/org/opensearch/common/SuppressForbidden.java → libs/common/src/main/java/org/opensearch/common/SuppressForbidden.java

@@ -38,6 +38,8 @@
 
 /**
  * Annotation to suppress forbidden-apis errors inside a whole class, a method, or a field.
+ *
+ * @opensearch.api
  */
 @Retention(RetentionPolicy.CLASS)
 @Target({ ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.METHOD, ElementType.TYPE })

libs/core/src/main/java/org/opensearch/common/collect/List.java → libs/common/src/main/java/org/opensearch/common/collect/List.java

@@ -34,6 +34,13 @@
 
 import java.util.Collection;
 
+/**
+ * Java 9 List
+ *
+ * todo: deprecate and remove w/ min jdk upgrade to 11?
+ *
+ * @opensearch.internal
+ */
 public class List {
 
     /**

libs/core/src/main/java/org/opensearch/common/collect/Map.java → libs/common/src/main/java/org/opensearch/common/collect/Map.java

@@ -32,6 +32,13 @@
 
 package org.opensearch.common.collect;
 
+/**
+ * Java 9 Map
+ *
+ * todo: deprecate and remove w/ min jdk upgrade to 11?
+ *
+ * @opensearch.internal
+ */
 public class Map {
 
     /**

libs/core/src/main/java/org/opensearch/common/collect/Set.java → libs/common/src/main/java/org/opensearch/common/collect/Set.java

@@ -34,6 +34,13 @@
 
 import java.util.Collection;
 
+/**
+ * Java 9 Set
+ *
+ * todo: deprecate and remove w/ min jdk upgrade to 11?
+ *
+ * @opensearch.internal
+ */
 public class Set {
 
     /**

libs/core/src/main/java/org/opensearch/common/collect/Tuple.java → libs/common/src/main/java/org/opensearch/common/collect/Tuple.java

@@ -32,6 +32,13 @@
 
 package org.opensearch.common.collect;
 
+/**
+ * Java 9 Tuple
+ *
+ * todo: deprecate and remove w/ min jdk upgrade to 11?
+ *
+ * @opensearch.internal
+ */
 public class Tuple<V1, V2> {
 
     public static <V1, V2> Tuple<V1, V2> tuple(V1 v1, V2 v2) {

libs/common/src/main/java/org/opensearch/common/collect/package-info.java

@@ -0,0 +1,10 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+/** Common collections classes used across opensearch. */
+package org.opensearch.common.collect;

libs/core/src/main/java/org/opensearch/common/concurrent/CompletableContext.java → libs/common/src/main/java/org/opensearch/common/concurrent/CompletableContext.java

@@ -41,6 +41,8 @@
  * an exceptional result. This allows attaching listeners that only handle {@link Exception}.
  *
  * @param <T> the result type
+ *
+ * @opensearch.api
  */
 public class CompletableContext<T> {
 

libs/common/src/main/java/org/opensearch/common/concurrent/package-info.java

@@ -0,0 +1,10 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+/** Common concurrency utilities used across opensearch. */
+package org.opensearch.common.concurrent;

libs/core/src/main/java/org/opensearch/common/io/PathUtils.java → libs/common/src/main/java/org/opensearch/common/io/PathUtils.java

@@ -46,6 +46,8 @@
  * <p>
  * This class allows the default filesystem to
  * be changed during tests.
+ *
+ * @opensearch.internal
  */
 @SuppressForbidden(reason = "accesses the default filesystem by design")
 // TODO: can we move this to the .env package and make it package-private?

libs/common/src/main/java/org/opensearch/common/io/package-info.java

@@ -0,0 +1,10 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+/** Common i/o utilities used across opensearch. */
+package org.opensearch.common.io;

libs/common/src/main/java/org/opensearch/common/package-info.java

@@ -0,0 +1,10 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+/** Common Library of Utilties and Data Structures used across OpenSearch. */
+package org.opensearch.common;

libs/core/src/main/java/org/opensearch/common/unit/TimeValue.java → libs/common/src/main/java/org/opensearch/common/unit/TimeValue.java

@@ -36,6 +36,11 @@
 import java.util.Objects;
 import java.util.concurrent.TimeUnit;
 
+/**
+ * Time value unit of measurement
+ *
+ * @opensearch.api
+ */
 public class TimeValue implements Comparable<TimeValue> {
 
     /** How many nano-seconds in one milli-second */

libs/common/src/main/java/org/opensearch/common/unit/package-info.java

@@ -0,0 +1,10 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+/** Common units of measurement used across opensearch. */
+package org.opensearch.common.unit;

libs/core/src/main/java/org/opensearch/common/util/FastMath.java → libs/common/src/main/java/org/opensearch/common/util/FastMath.java

@@ -47,6 +47,8 @@
 
 /**
  * Additions or modifications to this class should only come from the original org.math.plot.utils.FastMath source
+ *
+ * @opensearch.api
  */
 final class FastMath {
 

libs/core/src/main/java/org/opensearch/common/util/OpenSearchSloppyMath.java → libs/common/src/main/java/org/opensearch/common/util/OpenSearchSloppyMath.java

@@ -34,6 +34,8 @@
 
 /**
  * Similar to Lucene's SloppyMath, but for additional math functions.
+ *
+ * @opensearch.api
  */
 public class OpenSearchSloppyMath {
 

libs/core/src/main/java/org/opensearch/common/util/concurrent/AbstractRefCounted.java → libs/common/src/main/java/org/opensearch/common/util/concurrent/AbstractRefCounted.java

@@ -38,6 +38,8 @@
  * A basic RefCounted implementation that is initialized with a
  * ref count of 1 and calls {@link #closeInternal()} once it reaches
  * a 0 ref count
+ *
+ * @opensearch.api
  */
 public abstract class AbstractRefCounted implements RefCounted {
     private final AtomicInteger refCount = new AtomicInteger(1);