[Javadocs] add to o.o.bootstrap, cli, and client (#3163)

Adds javadocs to o.o.bootstrap, o.o.cli, and o.o.client packages.

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

build.gradle

@@ -278,6 +278,7 @@ allprojects {
     // see https://discuss.gradle.org/t/add-custom-javadoc-option-that-does-not-take-an-argument/5959
     javadoc.options.encoding = 'UTF8'
     javadoc.options.addStringOption('Xdoclint:all,-missing', '-quiet')
+    javadoc.options.tags = ["opensearch.internal", "opensearch.api", "opensearch.experimental"]
   }
 
   // support for reproducible builds
@@ -387,7 +388,7 @@ gradle.projectsEvaluated {
       }
     }
   }
-  
+
   dependencies {
     subprojects.findAll { it.pluginManager.hasPlugin('java') }.forEach {
       testReportAggregation it
@@ -413,7 +414,7 @@ subprojects {
 // eclipse configuration
 allprojects {
   apply plugin: 'eclipse'
-  
+
   // Name all the non-root projects after their path so that paths get grouped together when imported into eclipse.
   if (path != ':') {
     eclipse.project.name = path
@@ -573,12 +574,12 @@ subprojects {
 
 reporting {
   reports {
-    testAggregateTestReport(AggregateTestReport) { 
+    testAggregateTestReport(AggregateTestReport) {
       testType = TestSuiteType.UNIT_TEST
     }
   }
 }
 
 tasks.named(JavaBasePlugin.CHECK_TASK_NAME) {
-  dependsOn tasks.named('testAggregateTestReport', TestReport) 
+  dependsOn tasks.named('testAggregateTestReport', TestReport)
 }

server/src/main/java/org/opensearch/bootstrap/Bootstrap.java

@@ -82,6 +82,8 @@ import java.util.concurrent.TimeUnit;
 
 /**
  * Internal startup code.
+ *
+ * @opensearch.internal
  */
 final class Bootstrap {
 

server/src/main/java/org/opensearch/bootstrap/BootstrapCheck.java

@@ -36,6 +36,8 @@ import java.util.Objects;
 
 /**
  * Encapsulates a bootstrap check.
+ *
+ * @opensearch.internal
  */
 public interface BootstrapCheck {
 

server/src/main/java/org/opensearch/bootstrap/BootstrapChecks.java

@@ -71,6 +71,8 @@ import static org.opensearch.discovery.SettingsBasedSeedHostsProvider.DISCOVERY_
  * We enforce bootstrap checks once a node has the transport protocol bound to a non-loopback interface or if the system property {@code
  * opensearch.enforce.bootstrap.checks} is set to {@true}. In this case we assume the node is running in production and
  * all bootstrap checks must pass.
+ *
+ * @opensearch.internal
  */
 final class BootstrapChecks {
 

server/src/main/java/org/opensearch/bootstrap/BootstrapContext.java

@@ -37,6 +37,8 @@ import org.opensearch.env.Environment;
 
 /**
  * Context that is passed to every bootstrap check to make decisions on.
+ *
+ * @opensearch.internal
  */
 public class BootstrapContext {
     /**

server/src/main/java/org/opensearch/bootstrap/BootstrapException.java

@@ -41,6 +41,8 @@ import java.nio.file.Path;
  * these checked exceptions so that
  * {@link Bootstrap#init(boolean, Path, boolean, org.opensearch.env.Environment)}
  * does not have to declare all of these checked exceptions.
+ *
+ * @opensearch.internal
  */
 class BootstrapException extends Exception {
 

server/src/main/java/org/opensearch/bootstrap/BootstrapInfo.java

@@ -39,6 +39,8 @@ import java.util.Enumeration;
 
 /**
  * Exposes system startup information
+ *
+ * @opensearch.internal
  */
 @SuppressForbidden(reason = "exposes read-only view of system properties")
 public final class BootstrapInfo {

server/src/main/java/org/opensearch/bootstrap/BootstrapSettings.java

@@ -35,6 +35,11 @@ package org.opensearch.bootstrap;
 import org.opensearch.common.settings.Setting;
 import org.opensearch.common.settings.Setting.Property;
 
+/**
+ * Settings used for bootstrapping OpenSearch
+ *
+ * @opensearch.internal
+ */
 public final class BootstrapSettings {
 
     private BootstrapSettings() {}

server/src/main/java/org/opensearch/bootstrap/ConsoleCtrlHandler.java

@@ -32,6 +32,11 @@
 
 package org.opensearch.bootstrap;
 
+/**
+ * Handler for ctrl events on the console
+ *
+ * @opensearch.internal
+ */
 public interface ConsoleCtrlHandler {
 
     int CTRL_CLOSE_EVENT = 2;

server/src/main/java/org/opensearch/bootstrap/FilePermissionUtils.java

@@ -40,6 +40,11 @@ import java.nio.file.Files;
 import java.nio.file.Path;
 import java.security.Permissions;
 
+/**
+ * Utility for File Permissions during bootstrap
+ *
+ * @opensearch.internal
+ */
 public class FilePermissionUtils {
 
     /** no instantiation */

server/src/main/java/org/opensearch/bootstrap/JNACLibrary.java

@@ -45,6 +45,8 @@ import java.util.List;
 
 /**
  * java mapping to some libc functions
+ *
+ * @opensearch.internal
  */
 final class JNACLibrary {
 

server/src/main/java/org/opensearch/bootstrap/JNAKernel32Library.java

@@ -51,6 +51,8 @@ import java.util.List;
 
 /**
  * Library for Windows/Kernel32
+ *
+ * @opensearch.internal
  */
 final class JNAKernel32Library {
 

server/src/main/java/org/opensearch/bootstrap/JNANatives.java

@@ -48,6 +48,8 @@ import static org.opensearch.bootstrap.JNAKernel32Library.SizeT;
 /**
  * This class performs the actual work with JNA and library bindings to call native methods. It should only be used after
  * we are sure that the JNA classes are available to the JVM
+ *
+ * @opensearch.internal
  */
 class JNANatives {
 

server/src/main/java/org/opensearch/bootstrap/Natives.java

@@ -40,6 +40,8 @@ import java.nio.file.Path;
 /**
  * The Natives class is a wrapper class that checks if the classes necessary for calling native methods are available on
  * startup. If they are not available, this class will avoid calling code that loads these classes.
+ *
+ * @opensearch.internal
  */
 final class Natives {
     /** no instantiation */

server/src/main/java/org/opensearch/bootstrap/OpenSearch.java

@@ -55,6 +55,8 @@ import java.util.Locale;
 
 /**
  * This class starts opensearch.
+ *
+ * @opensearch.internal
  */
 class OpenSearch extends EnvironmentAwareCommand {
 

server/src/main/java/org/opensearch/bootstrap/OpenSearchPolicy.java

@@ -48,7 +48,11 @@ import java.util.Collections;
 import java.util.Map;
 import java.util.function.Predicate;
 
-/** custom policy for union of static and dynamic permissions */
+/**
+ * custom policy for union of static and dynamic permissions
+ *
+ * @opensearch.internal
+ **/
 final class OpenSearchPolicy extends Policy {
 
     /** template policy file, the one used in tests */

server/src/main/java/org/opensearch/bootstrap/OpenSearchUncaughtExceptionHandler.java

@@ -41,6 +41,11 @@ import java.io.IOError;
 import java.security.AccessController;
 import java.security.PrivilegedAction;
 
+/**
+ * UncaughtException Handler used during bootstrapping
+ *
+ * @opensearch.internal
+ */
 class OpenSearchUncaughtExceptionHandler implements Thread.UncaughtExceptionHandler {
     private static final Logger logger = LogManager.getLogger(OpenSearchUncaughtExceptionHandler.class);
 

server/src/main/java/org/opensearch/bootstrap/Security.java

@@ -116,6 +116,8 @@ import static org.opensearch.bootstrap.FilePermissionUtils.addSingleFilePath;
  * </pre>
  * See <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/security/troubleshooting-security.html">
  * Troubleshooting Security</a> for information.
+ *
+ * @opensearch.internal
  */
 final class Security {
     /** no instantiation */

server/src/main/java/org/opensearch/bootstrap/Spawner.java

@@ -51,6 +51,8 @@ import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
  * Spawns native module controller processes if present. Will only work prior to a system call filter being installed.
+ *
+ * @opensearch.internal
  */
 final class Spawner implements Closeable {
 

server/src/main/java/org/opensearch/bootstrap/StartupException.java

@@ -44,6 +44,8 @@ import java.util.function.Consumer;
  * "reasonably". This means limits on stacktrace frames and
  * cleanup for guice, and some guidance about consulting full
  * logs for the whole exception.
+ *
+ * @opensearch.internal
  */
 // TODO: remove this when guice is removed, and exceptions are cleaned up
 // this is horrible, but its what we must do

server/src/main/java/org/opensearch/bootstrap/SystemCallFilter.java

@@ -102,6 +102,8 @@ import java.util.Map;
  *      https://reverse.put.as/wp-content/uploads/2011/06/The-Apple-Sandbox-BHDC2011-Paper.pdf</a>
  * @see <a href="https://docs.oracle.com/cd/E23824_01/html/821-1456/prbac-2.html">
  *      https://docs.oracle.com/cd/E23824_01/html/821-1456/prbac-2.html</a>
+ *
+ * @opensearch.internal
  */
 // not an example of how to write code!!!
 final class SystemCallFilter {

server/src/main/java/org/opensearch/cli/CommandLoggingConfigurator.java

@@ -39,6 +39,8 @@ import org.opensearch.common.settings.Settings;
 /**
  * Holder class for method to configure logging without OpenSearch configuration files for use in CLI tools that will not read such
  * files.
+ *
+ * @opensearch.internal
  */
 public final class CommandLoggingConfigurator {
 

server/src/main/java/org/opensearch/cli/EnvironmentAwareCommand.java

@@ -46,7 +46,11 @@ import java.util.HashMap;
 import java.util.Locale;
 import java.util.Map;
 
-/** A cli command which requires an {@link org.opensearch.env.Environment} to use current paths and settings. */
+/**
+ * A cli command which requires an {@link org.opensearch.env.Environment} to use current paths and settings.
+ *
+ * @opensearch.internal
+ */
 public abstract class EnvironmentAwareCommand extends Command {
 
     private final OptionSpec<KeyValuePair> settingOption;

server/src/main/java/org/opensearch/cli/KeyStoreAwareCommand.java

@@ -44,6 +44,8 @@ import java.util.Arrays;
 /**
  * An {@link org.opensearch.cli.EnvironmentAwareCommand} that needs to access the opensearch keystore, possibly
  * decrypting it if it is password protected.
+ *
+ * @opensearch.internal
  */
 public abstract class KeyStoreAwareCommand extends EnvironmentAwareCommand {
     public KeyStoreAwareCommand(String description) {

server/src/main/java/org/opensearch/cli/LoggingAwareCommand.java

@@ -35,6 +35,8 @@ package org.opensearch.cli;
 /**
  * A command that is aware of logging. This class should be preferred over the base {@link Command} class for any CLI tools that depend on
  * core OpenSearch as they could directly or indirectly touch classes that touch logging and as such logging needs to be configured.
+ *
+ * @opensearch.internal
  */
 public abstract class LoggingAwareCommand extends Command {
 

server/src/main/java/org/opensearch/cli/LoggingAwareMultiCommand.java

@@ -36,6 +36,8 @@ package org.opensearch.cli;
  * A multi-command that is aware of logging. This class should be preferred over the base {@link MultiCommand} class for any CLI tools that
  * depend on core OpenSearch as they could directly or indirectly touch classes that touch logging and as such logging needs to be
  * configured.
+ *
+ * @opensearch.internal
  */
 public abstract class LoggingAwareMultiCommand extends MultiCommand {
 

server/src/main/java/org/opensearch/client/AdminClient.java

@@ -35,8 +35,9 @@ package org.opensearch.client;
 /**
  * Administrative actions/operations against the cluster or the indices.
  *
- *
  * @see org.opensearch.client.Client#admin()
+ *
+ * @opensearch.internal
  */
 public interface AdminClient {
 

server/src/main/java/org/opensearch/client/Client.java

@@ -93,6 +93,8 @@ import java.util.Map;
  * A client can be retrieved from a started {@link org.opensearch.node.Node}.
  *
  * @see org.opensearch.node.Node#client()
+ *
+ * @opensearch.internal
  */
 public interface Client extends OpenSearchClient, Releasable {
 

server/src/main/java/org/opensearch/client/ClusterAdminClient.java

@@ -139,6 +139,8 @@ import org.opensearch.tasks.TaskId;
  * Administrative actions/operations against indices.
  *
  * @see AdminClient#cluster()
+ *
+ * @opensearch.internal
  */
 public interface ClusterAdminClient extends OpenSearchClient {
 

server/src/main/java/org/opensearch/client/FilterClient.java

@@ -43,6 +43,8 @@ import org.opensearch.threadpool.ThreadPool;
  * A {@link Client} that contains another {@link Client} which it
  * uses as its basic source, possibly transforming the requests / responses along the
  * way or providing additional functionality.
+ *
+ * @opensearch.internal
  */
 public abstract class FilterClient extends AbstractClient {
 

server/src/main/java/org/opensearch/client/IndicesAdminClient.java

@@ -132,6 +132,8 @@ import org.opensearch.common.Nullable;
  * Administrative actions/operations against indices.
  *
  * @see AdminClient#indices()
+ *
+ * @opensearch.internal
  */
 public interface IndicesAdminClient extends OpenSearchClient {
 

server/src/main/java/org/opensearch/client/OpenSearchClient.java

@@ -39,6 +39,11 @@ import org.opensearch.action.ActionRequest;
 import org.opensearch.action.ActionResponse;
 import org.opensearch.threadpool.ThreadPool;
 
+/**
+ * Interface for an OpenSearch client implementation
+ *
+ * @opensearch.internal
+ */
 public interface OpenSearchClient {
 
     /**

server/src/main/java/org/opensearch/client/OriginSettingClient.java

@@ -46,6 +46,8 @@ import java.util.function.Supplier;
  * {@link ThreadContext#stashWithOrigin origin} set to a particular
  * value and calls its {@linkplain ActionListener} in its original
  * {@link ThreadContext}.
+ *
+ * @opensearch.internal
  */
 public final class OriginSettingClient extends FilterClient {
 

server/src/main/java/org/opensearch/client/ParentTaskAssigningClient.java

@@ -43,6 +43,8 @@ import org.opensearch.tasks.TaskId;
 /**
  * A {@linkplain Client} that sets the parent task on all requests that it makes. Use this to conveniently implement actions that cause
  * many other actions.
+ *
+ * @opensearch.internal
  */
 public class ParentTaskAssigningClient extends FilterClient {
     private final TaskId parentTask;

server/src/main/java/org/opensearch/client/Requests.java

@@ -79,6 +79,8 @@ import org.opensearch.common.xcontent.XContentType;
 
 /**
  * A handy one stop shop for creating requests (make sure to import static this class).
+ *
+ * @opensearch.internal
  */
 public class Requests {
 

server/src/main/java/org/opensearch/client/node/NodeClient.java

@@ -52,6 +52,8 @@ import java.util.function.Supplier;
 
 /**
  * Client that executes actions on the local node.
+ *
+ * @opensearch.internal
  */
 public class NodeClient extends AbstractClient {
 

server/src/main/java/org/opensearch/client/support/AbstractClient.java

@@ -366,6 +366,11 @@ import org.opensearch.threadpool.ThreadPool;
 
 import java.util.Map;
 
+/**
+ * Base client used to create concrete client implementations
+ *
+ * @opensearch.internal
+ */
 public abstract class AbstractClient implements Client {
 
     protected final Logger logger;

server/src/main/java/org/opensearch/client/transport/NoNodeAvailableException.java

@@ -40,6 +40,8 @@ import java.io.IOException;
 
 /**
  * An exception indicating no node is available to perform the operation.
+ *
+ * @opensearch.internal
  */
 public class NoNodeAvailableException extends OpenSearchException {