Fail build on missing Javadocs (#45)

* Fail build on missing Javadocs Signed-off-by: Daniel Widdis <widdis@gmail.com> * Fix build errors from package rename Signed-off-by: Daniel Widdis <widdis@gmail.com> * Javadocs for ActionListener Signed-off-by: Daniel Widdis <widdis@gmail.com> * Javadocs for ExtensionsRunner Signed-off-by: Daniel Widdis <widdis@gmail.com> * Replace missing-javadoc and missing-doclet with require-javadoc Signed-off-by: Daniel Widdis <widdis@gmail.com> * Doc updates based on code review. Signed-off-by: Daniel Widdis <widdis@gmail.com> * Add javadocs for ResponseHandler classes Signed-off-by: Daniel Widdis <widdis@gmail.com> * Add javadocs to ExtensionSettings Signed-off-by: Daniel Widdis <widdis@gmail.com> * Disable javadocStrict check on netty4 package Signed-off-by: Daniel Widdis <widdis@gmail.com> * Reenable strict doc checks on netty4, fix errors Signed-off-by: Daniel Widdis <widdis@gmail.com> * Final tweaks Signed-off-by: Daniel Widdis <widdis@gmail.com> * Fix missing Netty4 params causing failure Signed-off-by: Daniel Widdis <widdis@gmail.com> * Don't use Werror, include strict check on private javadocs if present Signed-off-by: Daniel Widdis <widdis@gmail.com> * Exclude netty4 from checks and link to tracking issue Signed-off-by: Daniel Widdis <widdis@gmail.com> * Clarify and add links on future action for temporary exclusions Signed-off-by: Daniel Widdis <widdis@gmail.com> * Update comments per code review Co-authored-by: Owais Kazi <owaiskazi19@gmail.com> Signed-off-by: Daniel Widdis <widdis@gmail.com> * Update require-javadoc version, fix get/set typo Signed-off-by: Daniel Widdis <widdis@gmail.com> Co-authored-by: Owais Kazi <owaiskazi19@gmail.com>
opensearch-project · Jul 14, 2022 · 4a3ac6d · 4a3ac6d
1 parent cd52721
commit 4a3ac6d
Show file tree

Hide file tree

Showing 10 changed files with 203 additions and 24 deletions.
diff --git a/build.gradle b/build.gradle
@@ -27,8 +27,8 @@ apply from: 'gradle/formatting.gradle'
 
 mainClassName = 'org.opensearch.sdk.ExtensionsRunner'
 
-group 'org.example'
-version '1.0-SNAPSHOT'
+group 'org.opensearch.sdk'
+version '1.0.0-SNAPSHOT'
 
 repositories {
     mavenLocal()
@@ -38,6 +38,10 @@ repositories {
     mavenCentral()
 }
 
+configurations {
+  requireJavadoc
+}
+
 dependencies {
     implementation "org.opensearch:opensearch:3.0.0-SNAPSHOT"
     implementation group: 'org.apache.logging.log4j', name: 'log4j-api', version: '2.17.1'
@@ -62,8 +66,40 @@ dependencies {
     testImplementation 'org.junit.jupiter:junit-jupiter-api:5.8.2'
     testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.8.2'
     testImplementation "org.opensearch.test:framework:3.0.0-SNAPSHOT"
+    requireJavadoc "org.plumelib:require-javadoc:1.0.4"
+}
+
+// this task tests for the presence of javadocs but not the content/tags
+task requireJavadoc(type: JavaExec) {
+  group = 'Documentation'
+  description = 'Ensures that Javadoc documentation exists.'
+  mainClass = "org.plumelib.javadoc.RequireJavadoc"
+  classpath = configurations.requireJavadoc
+  args "src/main/java" 
+  // javadocs on private methods optional
+  args "--dont-require-private=true"
+  // javadocs on trivial getters/setters optional
+  args "--dont-require-trivial-properties"
+  // the netty4 package will eventually be published to mavenCentral
+  // See https://github.com/opensearch-project/OpenSearch/issues/3118
+  args "--exclude=netty4"
+}
+check.dependsOn requireJavadoc
 
+// this task checks the content/tags of existing javadocs
+task javadocStrict(type: Javadoc) {
+  group = 'Documentation'
+  description = 'Run Javadoc in strict mode: with -Xdoclint:all, on all members.'
+  source = sourceSets.main.allJava
+  classpath = sourceSets.main.runtimeClasspath
+  options.addStringOption('Xdoclint:all', '-quiet')
+  options.memberLevel = JavadocMemberLevel.PRIVATE
+
+  // the netty4 package will eventually be published to mavenCentral
+  // See https://github.com/opensearch-project/OpenSearch/issues/3118
+  exclude 'org/opensearch/sdk/netty4'
 }
+check.dependsOn javadocStrict
 
 test {
     useJUnitPlatform()

diff --git a/gradle.properties b/gradle.properties
@@ -0,0 +1,37 @@
+#
+# 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.
+#
+
+# Enable build caching
+org.gradle.caching=true
+org.gradle.warning.mode=none
+org.gradle.parallel=true
+# Workaround for https://github.com/diffplug/spotless/issues/834
+org.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError -Xss2m \
+    --add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED \
+    --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED \
+    --add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED \
+    --add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED \
+    --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
+options.forkOptions.memoryMaximumSize=2g
+
+# Disable duplicate project id detection
+# See https://docs.gradle.org/current/userguide/upgrading_version_6.html#duplicate_project_names_may_cause_publication_to_fail
+systemProp.org.gradle.dependency.duplicate.project.detection=false
+
+# Enforce the build to fail on deprecated gradle api usage
+systemProp.org.gradle.warning.mode=fail
+
+# forcing to use TLS1.2 to avoid failure in vault
+# see https://github.com/hashicorp/vault/issues/8750#issuecomment-631236121
+systemProp.jdk.tls.client.protocols=TLSv1.2
+
+# jvm args for faster test execution by default
+systemProp.tests.jvm.argline=-XX:TieredStopAtLevel=1 -XX:ReservedCodeCacheSize=64m
diff --git a/src/main/java/org/opensearch/sdk/ActionListener.java b/src/main/java/org/opensearch/sdk/ActionListener.java
@@ -21,13 +21,30 @@
 import java.net.Socket;
 import java.net.UnknownHostException;
 
+/**
+ * A listener for actions on the local port.
+ */
 public class ActionListener {
 
+    /**
+     * Get the local ephemeral port.
+     *
+     * @return The socket address for localhost.
+     * @throws UnknownHostException if the local host name could not be resolved into an address.
+     */
     @SuppressForbidden(reason = "need local ephemeral port")
     protected static InetSocketAddress getLocalEphemeral() throws UnknownHostException {
         return new InetSocketAddress(InetAddress.getLocalHost(), 0);
     }
 
+    /**
+     * Run the action listener.
+     * This is presently a placeholder; when it receives a byte on the listening port, it terminates.
+     * Socket server to run extensions on the specified port provided in extensions.yml file after integrating SDK
+     *
+     * @param flag  If true, waits for the other side to send a message.
+     * @param timeout  How long to wait, in milliseconds.  If zero, infinite timeout.
+     */
     public void runActionListener(boolean flag, int timeout) {
         try (ServerSocket socket = new ServerSocket()) {
 

diff --git a/src/main/java/org/opensearch/sdk/ClusterSettingsResponseHandler.java b/src/main/java/org/opensearch/sdk/ClusterSettingsResponseHandler.java
@@ -7,9 +7,13 @@
 import org.opensearch.threadpool.ThreadPool;
 import org.opensearch.transport.TransportException;
 import org.opensearch.transport.TransportResponseHandler;
+import org.opensearch.transport.TransportService;
 
 import java.io.IOException;
 
+/**
+ * This class handles the response from OpenSearch to a {@link ExtensionsRunner#sendClusterSettingsRequest(TransportService)} call.
+ */
 public class ClusterSettingsResponseHandler implements TransportResponseHandler<ClusterSettingsResponse> {
     private static final Logger logger = LogManager.getLogger(ClusterSettingsResponseHandler.class);
 

diff --git a/src/main/java/org/opensearch/sdk/ClusterStateResponseHandler.java b/src/main/java/org/opensearch/sdk/ClusterStateResponseHandler.java
@@ -7,9 +7,13 @@
 import org.opensearch.threadpool.ThreadPool;
 import org.opensearch.transport.TransportException;
 import org.opensearch.transport.TransportResponseHandler;
+import org.opensearch.transport.TransportService;
 
 import java.io.IOException;
 
+/**
+ * This class handles the response from OpenSearch to a {@link ExtensionsRunner#sendClusterStateRequest(TransportService)} call.
+ */
 public class ClusterStateResponseHandler implements TransportResponseHandler<ClusterStateResponse> {
     private static final Logger logger = LogManager.getLogger(ClusterStateResponseHandler.class);
 

diff --git a/src/main/java/org/opensearch/sdk/ExtensionSettings.java b/src/main/java/org/opensearch/sdk/ExtensionSettings.java
@@ -11,12 +11,18 @@
 
 package org.opensearch.sdk;
 
+/**
+ * This class encapsulates the settings for an Extension.
+ */
 public class ExtensionSettings {
 
     private String extensionname;
     private String hostaddress;
     private String hostport;
-    // Change the location to extension.yml file of the extension
+
+    /**
+     * Placeholder field. Change the location to extension.yml file of the extension.
+     */
     public static final String EXTENSION_DESCRIPTOR = "src/test/resources/extension.yml";
 
     public String getExtensionname() {
@@ -31,7 +37,7 @@ public String getHostaddress() {
         return hostaddress;
     }
 
-    public void getHostaddress(String hostaddress) {
+    public void setHostaddress(String hostaddress) {
         this.hostaddress = hostaddress;
     }
 

diff --git a/src/main/java/org/opensearch/sdk/ExtensionsRunner.java b/src/main/java/org/opensearch/sdk/ExtensionsRunner.java
@@ -13,6 +13,7 @@
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
+
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 import org.opensearch.Version;
@@ -33,16 +34,15 @@
 import org.opensearch.indices.IndicesModule;
 import org.opensearch.indices.breaker.CircuitBreakerService;
 import org.opensearch.indices.breaker.NoneCircuitBreakerService;
+import org.opensearch.sdk.netty4.Netty4Transport;
+import org.opensearch.sdk.netty4.SharedGroupFactory;
 import org.opensearch.search.SearchModule;
 import org.opensearch.threadpool.ThreadPool;
 import org.opensearch.transport.ClusterConnectionManager;
 import org.opensearch.transport.ConnectionManager;
+import org.opensearch.transport.TransportInterceptor;
 import org.opensearch.transport.TransportService;
 import org.opensearch.transport.TransportSettings;
-import org.opensearch.transport.TransportInterceptor;
-
-import org.opensearch.sdk.netty4.Netty4Transport;
-import org.opensearch.sdk.netty4.SharedGroupFactory;
 
 import java.io.File;
 import java.io.IOException;
@@ -55,10 +55,20 @@
 import static java.util.Collections.emptySet;
 import static org.opensearch.common.UUIDs.randomBase64UUID;
 
+/**
+ * The primary class to run an extension.
+ * <p>
+ * This class Javadoc will eventually be expanded with a full description/tutorial for users.
+ */
 public class ExtensionsRunner {
     private ExtensionSettings extensionSettings = readExtensionSettings();
     private DiscoveryNode opensearchNode;
 
+    /**
+     * Instantiates a new Extensions Runner.
+     *
+     * @throws IOException if the runner failed to connect to the OpenSearch cluster.
+     */
     public ExtensionsRunner() throws IOException {}
 
     private final Settings settings = Settings.builder()
@@ -85,6 +95,12 @@ private DiscoveryNode getOpensearchNode() {
         return opensearchNode;
     }
 
+    /**
+     * Handles a plugin request from OpenSearch.  This is the first request for the transport communication and will initialize the extension and will be a part of OpenSearch bootstrap.
+     *
+     * @param pluginRequest  The request to handle.
+     * @return A response to OpenSearch validating that this is an extension.
+     */
     PluginResponse handlePluginsRequest(PluginRequest pluginRequest) {
         logger.info("Registering Plugin Request received from OpenSearch");
         PluginResponse pluginResponse = new PluginResponse("RealExtension");
@@ -93,6 +109,13 @@ PluginResponse handlePluginsRequest(PluginRequest pluginRequest) {
         return pluginResponse;
     }
 
+    /**
+     * Handles a request for extension point indices from OpenSearch.  The {@link #handlePluginsRequest(PluginRequest)} method must have been called first to initialize the extension.
+     *
+     * @param indicesModuleRequest  The request to handle.
+     * @param transportService  The transport service communicating with OpenSearch.
+     * @return A response to OpenSearch with this extension's index and search listeners.
+     */
     IndicesModuleResponse handleIndicesModuleRequest(IndicesModuleRequest indicesModuleRequest, TransportService transportService) {
         logger.info("Registering Indices Module Request received from OpenSearch");
         IndicesModuleResponse indicesModuleResponse = new IndicesModuleResponse(true, true, true);
@@ -103,16 +126,27 @@ IndicesModuleResponse handleIndicesModuleRequest(IndicesModuleRequest indicesMod
         return indicesModuleResponse;
     }
 
-    // Works as beforeIndexRemoved
+    /**
+     * Handles a request for extension name from OpenSearch.  The {@link #handlePluginsRequest(PluginRequest)} method must have been called first to initialize the extension.
+     *
+     * @param indicesModuleRequest  The request to handle.
+     * @return A response acknowledging the request.
+     */
     IndicesModuleNameResponse handleIndicesModuleNameRequest(IndicesModuleRequest indicesModuleRequest) {
+        // Works as beforeIndexRemoved
         logger.info("Registering Indices Module Name Request received from OpenSearch");
         IndicesModuleNameResponse indicesModuleNameResponse = new IndicesModuleNameResponse(true);
         return indicesModuleNameResponse;
     }
 
-    // method : build netty transport
+    /**
+     * Initializes a Netty4Transport object. This object will be wrapped in a {@link TransportService} object.
+     *
+     * @param settings  The transport settings to configure.
+     * @param threadPool  A thread pool to use.
+     * @return The configured Netty4Transport object.
+     */
     public Netty4Transport getNetty4Transport(Settings settings, ThreadPool threadPool) {
-
         NetworkService networkService = new NetworkService(Collections.emptyList());
         PageCacheRecycler pageCacheRecycler = new PageCacheRecycler(settings);
         IndicesModule indicesModule = new IndicesModule(Collections.emptyList());
@@ -144,7 +178,13 @@ public Netty4Transport getNetty4Transport(Settings settings, ThreadPool threadPo
         return transport;
     }
 
-    public TransportService createTransportService(Settings settings) throws IOException {
+    /**
+     * Creates a TransportService object. This object will control communication between the extension and OpenSearch.
+     *
+     * @param settings  The transport settings to configure.
+     * @return The configured TransportService object.
+     */
+    public TransportService createTransportService(Settings settings) {
 
         ThreadPool threadPool = new ThreadPool(settings);
 
@@ -169,9 +209,12 @@ public TransportService createTransportService(Settings settings) throws IOExcep
         );
     }
 
-    // manager method for transport service
+    /**
+     * Starts a TransportService.
+     *
+     * @param transportService  The TransportService to start.
+     */
     public void startTransportService(TransportService transportService) {
-
         // start transport service and accept incoming requests
         transportService.start();
         transportService.acceptIncomingRequests();
@@ -207,7 +250,11 @@ public void startTransportService(TransportService transportService) {
 
     }
 
-    // Extension can use this API to get ClusterState from OpenSearch
+    /**
+     * Requests the cluster state from OpenSearch.  The result will be handled by a {@link ClusterStateResponseHandler}.
+     *
+     * @param transportService  The TransportService defining the connection to OpenSearch.
+     */
     public void sendClusterStateRequest(TransportService transportService) {
         logger.info("Sending Cluster State request to OpenSearch");
         ClusterStateResponseHandler clusterStateResponseHandler = new ClusterStateResponseHandler();
@@ -223,23 +270,31 @@ public void sendClusterStateRequest(TransportService transportService) {
         }
     }
 
-    // Extension can use this API to get ClusterSettings from OpenSearch
-    public void sendClusterSettingRequest(TransportService transportService) {
+    /**
+     * Requests the cluster settings from OpenSearch.  The result will be handled by a {@link ClusterSettingsResponseHandler}.
+     *
+     * @param transportService  The TransportService defining the connection to OpenSearch.
+     */
+    public void sendClusterSettingsRequest(TransportService transportService) {
         logger.info("Sending Cluster Settings request to OpenSearch");
-        ClusterSettingsResponseHandler clusterSettingResponseHandler = new ClusterSettingsResponseHandler();
+        ClusterSettingsResponseHandler clusterSettingsResponseHandler = new ClusterSettingsResponseHandler();
         try {
             transportService.sendRequest(
                 opensearchNode,
                 ExtensionsOrchestrator.REQUEST_EXTENSION_CLUSTER_SETTINGS,
                 new ExtensionRequest(ExtensionsOrchestrator.RequestType.REQUEST_EXTENSION_CLUSTER_SETTINGS),
-                clusterSettingResponseHandler
+                clusterSettingsResponseHandler
             );
         } catch (Exception e) {
             logger.info("Failed to send Cluster Settings request to OpenSearch", e);
         }
     }
 
-    // Extension can use this API to get LocalNode from OpenSearch
+    /**
+     * Requests the local node from OpenSearch.  The result will be handled by a {@link LocalNodeResponseHandler}.
+     *
+     * @param transportService  The TransportService defining the connection to OpenSearch.
+     */
     public void sendLocalNodeRequest(TransportService transportService) {
         logger.info("Sending Local Node request to OpenSearch");
         LocalNodeResponseHandler localNodeResponseHandler = new LocalNodeResponseHandler();
@@ -259,12 +314,22 @@ private Settings getSettings() {
         return settings;
     }
 
-    // manager method for action listener
+    /**
+     * Starts an ActionListener.
+     *
+     * @param timeout  The timeout for the listener in milliseconds. A timeout of 0 means no timeout.
+     */
     public void startActionListener(int timeout) {
         final ActionListener actionListener = new ActionListener();
         actionListener.runActionListener(true, timeout);
     }
 
+    /**
+     * Run the Extension. Imports settings, establishes a connection with an OpenSearch cluster via a Transport Service, and sets up a listener for responses.
+     *
+     * @param args  Unused
+     * @throws IOException if the runner failed to connect to the OpenSearch cluster.
+     */
     public static void main(String[] args) throws IOException {
 
         ExtensionsRunner extensionsRunner = new ExtensionsRunner();