docs: javadoc fixes and updates as well as spotless fixes

skaha/build.gradle

@@ -4,6 +4,7 @@ plugins {
     id 'com.diffplug.spotless' version '6.25.0'
     id 'java'
     id 'jacoco'
+    id 'checkstyle'
     id 'org.jetbrains.dokka' version '1.6.0'
 }
 
@@ -37,7 +38,10 @@ dependencies {
     implementation 'com.fasterxml.jackson.core:jackson-databind:2.17.2'
     implementation 'com.google.code.gson:gson:2.8.9'
     implementation 'commons-io:commons-io:[2.14.0,3.0.0)'
+
+    // Used to merge YAML sections to fully configure Job files.
     implementation 'io.kubernetes:client-java:21.0.2'
+
     implementation 'org.opencadc:cadc-access-control:[1.1.23,)'
     implementation 'org.opencadc:cadc-access-control-identity:[1.1.0,)'
     implementation 'org.opencadc:cadc-cdp:[1.2,)'
@@ -72,6 +76,12 @@ spotless {
     palantirJavaFormat('2.50.0').formatJavadoc(true)
     // Format annotations on a single line
     formatAnnotations()
+
+    // Checks for javadoc formatting
+    checkstyle {
+      // Point to the same checkstyle.xml file as the checkstyle task
+      configFile file("$rootDir/checkstyle.xml")
+    }
   }
 }
 check.dependsOn spotlessCheck
@@ -105,12 +115,12 @@ tasks.dokkaHtml.configure {
         register("main") {
             sourceRoots.from(file("src/main/java"))
         }
-      configureEach {
-        jdkVersion.set(11)
-        sourceLink {
-        localDirectory.set(file("src/main/java"))
-        remoteUrl.set("https://github.com/opencadc/science-platform/tree/main/skaha/src/main/java")
-      }
-      }
+        configureEach {
+            jdkVersion.set(11)
+            sourceLink {
+                localDirectory.set(file("src/main/java"))
+                remoteUrl.set("https://github.com/opencadc/science-platform/tree/main/skaha/src/main/java")
+            }
+        }
     }
 }

skaha/checkstyle.xml

@@ -0,0 +1,11 @@
+<!DOCTYPE module PUBLIC
+        "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+        "https://checkstyle.org/dtds/configuration_1_3.dtd">
+<module name="Checker">
+    <module name="TreeWalker">
+        <module name="JavadocStyle">
+            <property name="checkEmptyJavadoc" value="true"/>
+            <property name="scope" value="public"/>
+        </module>
+    </module>
+</module>

skaha/src/intTest/java/org/opencadc/skaha/DesktopAppLifecycleTest.java

@@ -83,6 +83,8 @@
 import org.opencadc.skaha.session.SessionAction;
 
 /**
+ * Integration test for session lifecycle creation and deletion for Desktops and their applications.
+ *
  * @author majorb
  */
 public class DesktopAppLifecycleTest {

skaha/src/intTest/java/org/opencadc/skaha/ExpiryTimeRenewalTest.java

@@ -87,7 +87,11 @@
 import org.opencadc.skaha.session.Session;
 import org.opencadc.skaha.session.SessionAction;
 
-/** @author majorb */
+/**
+ * Integration Test to test renewing existing Sessions.
+ *
+ * @author majorb
+ */
 public class ExpiryTimeRenewalTest {
 
     public static final String CARTA_IMAGE_SUFFIX = "/skaha/carta:latest";

skaha/src/intTest/java/org/opencadc/skaha/ImagesTest.java

@@ -87,6 +87,8 @@
 import org.opencadc.skaha.image.Image;
 
 /**
+ * Integration test for Image GET requests.
+ *
  * @author yeunga
  */
 public class ImagesTest {

skaha/src/intTest/java/org/opencadc/skaha/SessionLifecycleTest.java

@@ -82,6 +82,8 @@
 import org.opencadc.skaha.session.SessionAction;
 
 /**
+ * Integration test for session lifecycle creation and deletion.
+ *
  * @author majorb
  */
 public class SessionLifecycleTest {

skaha/src/main/java/org/opencadc/skaha/K8SUtil.java

@@ -80,15 +80,6 @@ public static String getHostName() {
         return System.getenv("skaha.hostname");
     }
 
-    /**
-     * Helps reduce string constants in many places.
-     *
-     * @return The Skaha namespace
-     */
-    public static String getNamespace() {
-        return "skaha-system";
-    }
-
     public static String getWorkloadNamespace() {
         return System.getenv("skaha.namespace");
     }
@@ -109,7 +100,6 @@ public static String getJobName(String sessionID, String type, String userID) {
         return ("skaha-" + type + "-" + userJobID + "-" + sessionID).toLowerCase();
     }
 
-    // skaha-notebook-svc-rdcc0219
     public static String getServiceName(String sessionID, String type) {
         return "skaha-" + type + "-svc-" + sessionID;
     }

skaha/src/main/java/org/opencadc/skaha/context/ResourceContexts.java

@@ -76,8 +76,9 @@
 import org.opencadc.skaha.SkahaAction;
 
 /**
- * @author majorb
+ * Describes the JSON file that contains the default and available resources for the Kubernetes cluster.
  *
+ * @author majorb
  */
 public class ResourceContexts {
 

skaha/src/main/java/org/opencadc/skaha/image/GetAction.java

@@ -74,8 +74,9 @@
 import org.opencadc.skaha.SkahaAction;
 
 /**
- * @author majorb
+ * Handle GET requests for images. This will optionally list by type.
  *
+ * @author majorb
  */
 public class GetAction extends SkahaAction {
 
@@ -100,7 +101,7 @@ public void doAction() throws Exception {
         syncOutput.getOutputStream().write(json.getBytes());
     }
 
-    protected List<Image> getImages(String type) throws Exception {
+    protected List<Image> getImages(String type) {
         if (null != type && !SESSION_TYPES.contains(type)) {
             log.error("unknown image type: " + type);
             throw new IllegalArgumentException("unknown type: " + type);

skaha/src/main/java/org/opencadc/skaha/image/Image.java

@@ -70,18 +70,17 @@
 import java.util.Set;
 
 /**
- * @author majorb
+ * Represents a single Image to be used in a Job. An Image is identified by an id and a digest.
  *
+ * @author majorb
  */
 public class Image {
 
     private String id;
     private Set<String> types;
     private String digest;
 
-    /**
-     * The following constructor is used by the ObjectMapper class for creating instances using reflection
-     */
+    /** The following constructor is used by the ObjectMapper class for creating instances using reflection. */
     public Image() {}
 
     public Image(String id, Set<String> types, String digest) {

skaha/src/main/java/org/opencadc/skaha/session/DeleteAction.java

@@ -76,7 +76,11 @@
 import org.opencadc.skaha.utils.CommandExecutioner;
 import org.opencadc.skaha.utils.KubectlCommandBuilder;
 
-/** @author majorb */
+/**
+ * Handle a delete request for a session or an app.
+ *
+ * @author majorb
+ */
 public class DeleteAction extends SessionAction {
 
     private static final Logger log = Logger.getLogger(DeleteAction.class);

skaha/src/main/java/org/opencadc/skaha/session/PostAction.java

@@ -99,7 +99,12 @@
 import org.opencadc.skaha.utils.KubectlCommandBuilder;
 import org.opencadc.skaha.utils.PosixCache;
 
-/** @author majorb */
+/**
+ * POST submission for creating a new session or app, or updating (renewing) an existing session. Configuration is
+ * pulled from the environment.
+ *
+ * @author majorb
+ */
 public class PostAction extends SessionAction {
 
     // variables replaced in kubernetes yaml config files for

skaha/src/main/java/org/opencadc/skaha/session/PublicSession.java

@@ -69,19 +69,18 @@
 import org.apache.log4j.Logger;
 
 /**
- * @author majorb
- *
  * Public session information.
  *
+ * @author majorb
  */
 public class PublicSession {
 
     private static final Logger log = Logger.getLogger(PublicSession.class);
 
-    private String userid;
-    private String type;
-    private String status;
-    private String startTime;
+    private final String userid;
+    private final String type;
+    private final String status;
+    private final String startTime;
 
     public PublicSession(String userid, String type, String status, String startTime) {
         this.userid = userid;

skaha/src/main/java/org/opencadc/skaha/session/ResourceStats.java

@@ -69,16 +69,18 @@
 import org.apache.log4j.Logger;
 
 /**
- * @author yeunga
+ * Current resource usage within the Kubernetes cluster, based on the number of sessions and the resources requested by
+ * the sessions.
  *
+ * @author yeunga
  */
 public class ResourceStats {
 
     private static final Logger log = Logger.getLogger(ResourceStats.class);
 
-    private JobInstances instances;
-    private Core cores;
-    private Ram ram;
+    private final JobInstances instances;
+    private final Core cores;
+    private final Ram ram;
 
     public ResourceStats(
             int desktopCount,

skaha/src/main/java/org/opencadc/skaha/session/Session.java

@@ -71,10 +71,9 @@
 import org.apache.log4j.Logger;
 
 /**
- * @author majorb
- *
  * Represents a session running in skaha.
  *
+ * @author majorb
  */
 public class Session {
 
@@ -241,9 +240,10 @@ public String getAppId() {
     }
 
     /**
-     * See the array of Supplemental Group IDs.  To ensure the integrity of this Session's Supplemental groups, this
+     * See the array of Supplemental Group IDs. To ensure the integrity of this Session's Supplemental groups, this
      * method will return a copy.
-     * @return  Integer array, never null.
+     *
+     * @return Integer array, never null.
      */
     public Integer[] getSupplementalGroups() {
         return Arrays.copyOf(this.supplementalGroups, this.supplementalGroups.length);

skaha/src/main/java/org/opencadc/skaha/utils/KubectlCommandBuilder.java

@@ -3,6 +3,11 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * A builder for constructing kubectl commands.
+ *
+ * @author anujachaitanya
+ */
 public class KubectlCommandBuilder {
     public static KubectlCommand command(String operation) {
         return new KubectlCommand(operation);

skaha/src/test/java/org/opencadc/skaha/image/GetActionTest.java

@@ -79,7 +79,11 @@
 import org.opencadc.skaha.utils.RedisCache;
 import org.opencadc.skaha.utils.TestUtils;
 
-/** @author majorb */
+/**
+ * Unit Test for GetAction class for images.
+ *
+ * @author majorb
+ */
 @RunWith(MockitoJUnitRunner.class)
 public class GetActionTest {