chore: polish and add some minimal javadoc to the junit5 extension

Author: lburgazzoli

Diff for: operator-framework-junit5/src/main/java/io/javaoperatorsdk/operator/junit/OperatorExtension.java

@@ -1,20 +1,6 @@
 package io.javaoperatorsdk.operator.junit;
 
-import java.io.InputStream;
-import java.util.ArrayList;
-import java.util.List;
-import java.util.Locale;
-import java.util.concurrent.TimeUnit;
-import java.util.stream.Collectors;
-
-import org.awaitility.Awaitility;
-import org.junit.jupiter.api.extension.AfterAllCallback;
-import org.junit.jupiter.api.extension.AfterEachCallback;
-import org.junit.jupiter.api.extension.BeforeAllCallback;
-import org.junit.jupiter.api.extension.BeforeEachCallback;
-import org.junit.jupiter.api.extension.ExtensionContext;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
+import static io.javaoperatorsdk.operator.api.config.ControllerConfigurationOverrider.override;
 
 import io.fabric8.kubernetes.api.model.HasMetadata;
 import io.fabric8.kubernetes.api.model.KubernetesResourceList;
@@ -32,8 +18,20 @@
 import io.javaoperatorsdk.operator.api.config.Version;
 import io.javaoperatorsdk.operator.processing.ConfiguredController;
 import io.javaoperatorsdk.operator.processing.retry.Retry;
-
-import static io.javaoperatorsdk.operator.api.config.ControllerConfigurationOverrider.override;
+import java.io.InputStream;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.concurrent.TimeUnit;
+import java.util.stream.Collectors;
+import org.awaitility.Awaitility;
+import org.junit.jupiter.api.extension.AfterAllCallback;
+import org.junit.jupiter.api.extension.AfterEachCallback;
+import org.junit.jupiter.api.extension.BeforeAllCallback;
+import org.junit.jupiter.api.extension.BeforeEachCallback;
+import org.junit.jupiter.api.extension.ExtensionContext;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 public class OperatorExtension
     implements HasKubernetesClient,
@@ -67,6 +65,11 @@ private OperatorExtension(
     this.waitForNamespaceDeletion = waitForNamespaceDeletion;
   }
 
+  /**
+   * Creates a {@link Builder} to set up an {@link OperatorExtension} instance.
+   *
+   * @return the builder.
+   */
   public static Builder builder() {
     return new Builder();
   }
@@ -96,17 +99,32 @@ public KubernetesClient getKubernetesClient() {
     return kubernetesClient;
   }
 
+  /**
+   * Returns the test namespace.
+   *
+   * @return the namespace name.
+   */
   public String getNamespace() {
     return namespace;
   }
 
+  /**
+   * The list of controllers known by the operator.
+   *
+   * @return the list of {@link ResourceController}.
+   */
   @SuppressWarnings({"rawtypes"})
   public List<ResourceController> getControllers() {
     return operator.getControllers().stream()
         .map(ConfiguredController::getController)
         .collect(Collectors.toUnmodifiableList());
   }
 
+  /**
+   * The list of controllers of the give {@code type} known by the operator.
+   *
+   * @return the list of {@link ResourceController} matching the required type.
+   */
   @SuppressWarnings({"rawtypes"})
   public <T extends ResourceController> T getControllerOfType(Class<T> type) {
     return operator.getControllers().stream()
@@ -123,22 +141,42 @@ public <T extends HasMetadata> NonNamespaceOperation<T, KubernetesResourceList<T
     return kubernetesClient.resources(type).inNamespace(namespace);
   }
 
-  public <T extends HasMetadata> T getNamedResource(Class<T> type, String name) {
+  /**
+   * Lookup a resource given its {@code type} and {@code name} in the current test namespace.
+   *
+   * @param type Class for resource
+   * @param name the name of the resource
+   * @param <T> T type represents resource type
+   * @return The resource or null if it does not exist
+   */
+  public <T extends HasMetadata> T get(Class<T> type, String name) {
     return kubernetesClient.resources(type).inNamespace(namespace).withName(name).get();
   }
 
+  /**
+   * Creates a resource in the current test namespace.
+   *
+   * @param type Class for resource
+   * @param resource the resource to create
+   * @param <T> T type represents resource type
+   * @return The resource or null if it does not exist
+   */
   public <T extends HasMetadata> T create(Class<T> type, T resource) {
     return kubernetesClient.resources(type).inNamespace(namespace).create(resource);
   }
 
+  /**
+   * Replaces a resource in the current test namespace.
+   *
+   * @param type Class for resource
+   * @param resource the resource to create
+   * @param <T> T type represents resource type
+   * @return The resource or null if it does not exist
+   */
   public <T extends HasMetadata> T replace(Class<T> type, T resource) {
     return kubernetesClient.resources(type).inNamespace(namespace).replace(resource);
   }
 
-  public <T extends HasMetadata> T get(Class<T> type, String name) {
-    return kubernetesClient.resources(type).inNamespace(namespace).withName(name).get();
-  }
-
 
   @SuppressWarnings("unchecked")
   protected void before(ExtensionContext context) {
@@ -225,33 +263,71 @@ protected Builder() {
           true);
     }
 
+    /**
+     * Configures if the test namespace should be preserved in case of error for troubleshooting.
+     *
+     * @param value true if the namespace should be preserved.
+     * @return this builder
+     */
     public Builder preserveNamespaceOnError(boolean value) {
       this.preserveNamespaceOnError = value;
       return this;
     }
 
+    /**
+     * Configures if the extension should wait for the test namespace deletion.
+     *
+     * @param value true if the waiting for namespace deletion is required.
+     * @return this builder
+     */
     public Builder waitForNamespaceDeletion(boolean value) {
       this.waitForNamespaceDeletion = value;
       return this;
     }
 
+    /**
+     * Defines the {@link ConfigurationService} the operator should use.
+     *
+     * @param value the {@link ConfigurationService}.
+     * @return this builder
+     */
     public Builder withConfigurationService(ConfigurationService value) {
       configurationService = value;
       return this;
     }
 
+    /**
+     * Add a {@link ResourceController} to the operator.
+     *
+     * @param value the {@link ResourceController}
+     * @return this builder
+     */
     @SuppressWarnings("rawtypes")
     public Builder withController(ResourceController value) {
       controllers.add(new ControllerSpec(value, null));
       return this;
     }
 
+    /**
+     * Add a {@link ResourceController} to the operator with a {@link Retry} policy.
+     *
+     * @param value the {@link ResourceController}
+     * @param retry the {@link Retry} policy.
+     * @return this builder
+     */
     @SuppressWarnings("rawtypes")
     public Builder withController(ResourceController value, Retry retry) {
       controllers.add(new ControllerSpec(value, retry));
       return this;
     }
 
+    /**
+     * Add a {@link ResourceController} to the operator by providing its class name. The controller
+     * is instantiated using the default empty constructor.
+     *
+     * @param value the {@link ResourceController} type.
+     * @return this builder
+     */
     @SuppressWarnings("rawtypes")
     public Builder withController(Class<? extends ResourceController> value) {
       try {
@@ -262,6 +338,11 @@ public Builder withController(Class<? extends ResourceController> value) {
       return this;
     }
 
+    /**
+     * Build a new {@link OperatorExtension} instance.
+     *
+     * @return a new {@link OperatorExtension} instance.
+     */
     public OperatorExtension build() {
       return new OperatorExtension(
           configurationService,

Diff for: operator-framework/src/test/java/io/javaoperatorsdk/operator/ConcurrencyIT.java

@@ -58,7 +58,7 @@ public void manyResourcesGetCreatedUpdatedAndDeleted() throws InterruptedExcepti
     // update some resources
     for (int i = 0; i < NUMBER_OF_RESOURCES_UPDATED; i++) {
       TestCustomResource tcr =
-          operator.getNamedResource(TestCustomResource.class,
+          operator.get(TestCustomResource.class,
               TestUtils.TEST_CUSTOM_RESOURCE_PREFIX + i);
       tcr.getSpec().setValue(i + UPDATED_SUFFIX);
       operator.resources(TestCustomResource.class)

Diff for: operator-framework/src/test/java/io/javaoperatorsdk/operator/ControllerExecutionIT.java

@@ -52,7 +52,7 @@ void awaitResourcesCreatedOrUpdated() {
         .untilAsserted(
             () -> {
               ConfigMap configMap =
-                  operator.getNamedResource(ConfigMap.class, "test-config-map");
+                  operator.get(ConfigMap.class, "test-config-map");
               assertThat(configMap).isNotNull();
               assertThat(configMap.getData().get("test-key")).isEqualTo("test-value");
             });
@@ -68,7 +68,7 @@ void awaitStatusUpdated(int timeout) {
         .untilAsserted(
             () -> {
               TestCustomResource cr =
-                  operator.getNamedResource(TestCustomResource.class,
+                  operator.get(TestCustomResource.class,
                       TestUtils.TEST_CUSTOM_RESOURCE_NAME);
               assertThat(cr).isNotNull();
               assertThat(cr.getStatus()).isNotNull();

Diff for: operator-framework/src/test/java/io/javaoperatorsdk/operator/InformerEventSourceIT.java

@@ -70,7 +70,7 @@ private InformerEventSourceTestCustomResource initialCustomResource() {
   private void waitForCRStatusValue(String value) {
     await().atMost(10, TimeUnit.SECONDS).untilAsserted(() -> {
       var cr =
-          operator.getNamedResource(InformerEventSourceTestCustomResource.class, RESOURCE_NAME);
+          operator.get(InformerEventSourceTestCustomResource.class, RESOURCE_NAME);
       assertThat(cr.getStatus()).isNotNull();
       assertThat(cr.getStatus().getConfigMapValue()).isEqualTo(value);
     });

Diff for: operator-framework/src/test/java/io/javaoperatorsdk/operator/RetryIT.java

@@ -52,7 +52,7 @@ public void retryFailedExecution() {
                   .isEqualTo(RetryTestCustomResourceController.NUMBER_FAILED_EXECUTIONS + 1);
 
           RetryTestCustomResource finalResource =
-              operator.getNamedResource(RetryTestCustomResource.class,
+              operator.get(RetryTestCustomResource.class,
                   resource.getMetadata().getName());
           assertThat(finalResource.getStatus().getState())
               .isEqualTo(RetryTestCustomResourceStatus.State.SUCCESS);

Diff for: operator-framework/src/test/java/io/javaoperatorsdk/operator/SubResourceUpdateIT.java

@@ -99,7 +99,7 @@ void awaitStatusUpdated(String name) {
         .untilAsserted(
             () -> {
               SubResourceTestCustomResource cr =
-                  operator.getNamedResource(SubResourceTestCustomResource.class, name);
+                  operator.get(SubResourceTestCustomResource.class, name);
               assertThat(cr.getMetadata().getFinalizers()).hasSize(1);
               assertThat(cr).isNotNull();
               assertThat(cr.getStatus()).isNotNull();

Diff for: operator-framework/src/test/java/io/javaoperatorsdk/operator/UpdatingResAndSubResIT.java

@@ -36,7 +36,7 @@ public void updatesSubResourceStatus() {
 
     DoubleUpdateTestCustomResource customResource =
         operator
-            .getNamedResource(DoubleUpdateTestCustomResource.class,
+            .get(DoubleUpdateTestCustomResource.class,
                 resource.getMetadata().getName());
 
     assertThat(TestUtils.getNumberOfExecutions(operator))
@@ -57,7 +57,7 @@ void awaitStatusUpdated(String name) {
         .untilAsserted(
             () -> {
               DoubleUpdateTestCustomResource cr =
-                  operator.getNamedResource(DoubleUpdateTestCustomResource.class, name);
+                  operator.get(DoubleUpdateTestCustomResource.class, name);
 
               assertThat(cr)
                   .isNotNull();