chore(docs): add some javadoc (#2452)

Signed-off-by: Chris Laprun <claprun@redhat.com>

Author: metacosm

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/AbstractConfigurationService.java

@@ -10,6 +10,9 @@
 import io.javaoperatorsdk.operator.ReconcilerUtils;
 import io.javaoperatorsdk.operator.api.reconciler.Reconciler;
 
+/**
+ * An abstract implementation of {@link ConfigurationService} meant to ease custom implementations
+ */
 @SuppressWarnings("rawtypes")
 public class AbstractConfigurationService implements ConfigurationService {
   private final Map<String, ControllerConfiguration> configurations = new ConcurrentHashMap<>();
@@ -18,11 +21,11 @@ public class AbstractConfigurationService implements ConfigurationService {
   private Cloner cloner;
   private ExecutorServiceManager executorServiceManager;
 
-  public AbstractConfigurationService(Version version) {
+  protected AbstractConfigurationService(Version version) {
     this(version, null);
   }
 
-  public AbstractConfigurationService(Version version, Cloner cloner) {
+  protected AbstractConfigurationService(Version version, Cloner cloner) {
     this(version, cloner, null, null);
   }
 

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java

@@ -33,6 +33,68 @@ public interface ConfigurationService {
   Logger log = LoggerFactory.getLogger(ConfigurationService.class);
 
   int DEFAULT_MAX_CONCURRENT_REQUEST = 512;
+  /**
+   * The default numbers of concurrent reconciliations
+   */
+  int DEFAULT_RECONCILIATION_THREADS_NUMBER = 50;
+  /**
+   * The default number of threads used to process dependent workflows
+   */
+  int DEFAULT_WORKFLOW_EXECUTOR_THREAD_NUMBER = DEFAULT_RECONCILIATION_THREADS_NUMBER;
+
+  /**
+   * Creates a new {@link ConfigurationService} instance used to configure an
+   * {@link io.javaoperatorsdk.operator.Operator} instance, starting from the specified base
+   * configuration and overriding specific aspects according to the provided
+   * {@link ConfigurationServiceOverrider} instance.
+   *
+   * <p>
+   * <em>NOTE:</em> This overriding mechanism should only be used <strong>before</strong> creating
+   * your Operator instance as the configuration service is set at creation time and cannot be
+   * subsequently changed. As a result, overriding values this way after the Operator has been
+   * configured will not take effect.
+   * </p>
+   *
+   * @param baseConfiguration the {@link ConfigurationService} to start from
+   * @param overrider the {@link ConfigurationServiceOverrider} used to change the values provided
+   *        by the base configuration
+   * @return a new {@link ConfigurationService} starting from the configuration provided as base but
+   *         with overridden values.
+   */
+  static ConfigurationService newOverriddenConfigurationService(
+      ConfigurationService baseConfiguration,
+      Consumer<ConfigurationServiceOverrider> overrider) {
+    if (overrider != null) {
+      final var toOverride = new ConfigurationServiceOverrider(baseConfiguration);
+      overrider.accept(toOverride);
+      return toOverride.build();
+    }
+    return baseConfiguration;
+  }
+
+  /**
+   * Creates a new {@link ConfigurationService} instance used to configure an
+   * {@link io.javaoperatorsdk.operator.Operator} instance, starting from the default configuration
+   * and overriding specific aspects according to the provided {@link ConfigurationServiceOverrider}
+   * instance.
+   *
+   * <p>
+   * <em>NOTE:</em> This overriding mechanism should only be used <strong>before</strong> creating
+   * your Operator instance as the configuration service is set at creation time and cannot be
+   * subsequently changed. As a result, overriding values this way after the Operator has been
+   * configured will not take effect.
+   * </p>
+   *
+   * @param overrider the {@link ConfigurationServiceOverrider} used to change the values provided
+   *        by the default configuration
+   * @return a new {@link ConfigurationService} overriding the default values with the ones provided
+   *         by the specified {@link ConfigurationServiceOverrider}
+   * @since 4.4.0
+   */
+  static ConfigurationService newOverriddenConfigurationService(
+      Consumer<ConfigurationServiceOverrider> overrider) {
+    return newOverriddenConfigurationService(new BaseConfigurationService(), overrider);
+  }
 
   /**
    * Retrieves the configuration associated with the specified reconciler
@@ -44,7 +106,6 @@ public interface ConfigurationService {
    */
   <R extends HasMetadata> ControllerConfiguration<R> getConfigurationFor(Reconciler<R> reconciler);
 
-
   /**
    * Used to clone custom resources.
    *
@@ -128,8 +189,6 @@ default boolean checkCRDAndValidateLocalModel() {
     return false;
   }
 
-  int DEFAULT_RECONCILIATION_THREADS_NUMBER = 50;
-
   /**
    * The number of threads the operator can spin out to dispatch reconciliation requests to
    * reconcilers with the default executors
@@ -140,8 +199,6 @@ default int concurrentReconciliationThreads() {
     return DEFAULT_RECONCILIATION_THREADS_NUMBER;
   }
 
-  int DEFAULT_WORKFLOW_EXECUTOR_THREAD_NUMBER = DEFAULT_RECONCILIATION_THREADS_NUMBER;
-
   /**
    * Number of threads the operator can spin out to be used in the workflows with the default
    * executor.
@@ -152,27 +209,64 @@ default int concurrentWorkflowExecutorThreads() {
     return DEFAULT_WORKFLOW_EXECUTOR_THREAD_NUMBER;
   }
 
+  /**
+   * Override to provide a custom {@link Metrics} implementation
+   * 
+   * @return the {@link Metrics} implementation
+   */
   default Metrics getMetrics() {
     return Metrics.NOOP;
   }
 
+  /**
+   * Override to provide a custom {@link ExecutorService} implementation to change how threads
+   * handle concurrent reconciliations
+   * 
+   * @return the {@link ExecutorService} implementation to use for concurrent reconciliation
+   *         processing
+   */
   default ExecutorService getExecutorService() {
     return Executors.newFixedThreadPool(concurrentReconciliationThreads());
   }
 
+  /**
+   * Override to provide a custom {@link ExecutorService} implementation to change how dependent
+   * workflows are processed in parallel
+   * 
+   * @return the {@link ExecutorService} implementation to use for dependent workflow processing
+   */
   default ExecutorService getWorkflowExecutorService() {
     return Executors.newFixedThreadPool(concurrentWorkflowExecutorThreads());
   }
 
+  /**
+   * Determines whether the associated Kubernetes client should be closed when the associated
+   * {@link io.javaoperatorsdk.operator.Operator} is stopped.
+   * 
+   * @return {@code true} if the Kubernetes should be closed on stop, {@code false} otherwise
+   */
   default boolean closeClientOnStop() {
     return true;
   }
 
+  /**
+   * Override to provide a custom {@link DependentResourceFactory} implementation to change how
+   * {@link io.javaoperatorsdk.operator.api.reconciler.dependent.DependentResource} are instantiated
+   * 
+   * @return the custom {@link DependentResourceFactory} implementation
+   */
   @SuppressWarnings("rawtypes")
   default DependentResourceFactory dependentResourceFactory() {
     return DependentResourceFactory.DEFAULT;
   }
 
+  /**
+   * Retrieves the optional {@link LeaderElectionConfiguration} to specify how the associated
+   * {@link io.javaoperatorsdk.operator.Operator} handles leader election to ensure only one
+   * instance of the operator runs on the cluster at any given time
+   * 
+   * @return the {@link LeaderElectionConfiguration}
+   */
   default Optional<LeaderElectionConfiguration> getLeaderElectionConfiguration() {
     return Optional.empty();
   }
@@ -228,65 +322,23 @@ default Optional<InformerStoppedHandler> getInformerStoppedHandler() {
     });
   }
 
+  /**
+   * Override to provide a custom {@link ManagedWorkflowFactory} implementation to change how
+   * {@link io.javaoperatorsdk.operator.processing.dependent.workflow.ManagedWorkflow} are
+   * instantiated
+   * 
+   * @return the custom {@link ManagedWorkflowFactory} implementation
+   */
   @SuppressWarnings("rawtypes")
   default ManagedWorkflowFactory getWorkflowFactory() {
     return ManagedWorkflowFactory.DEFAULT;
   }
 
   /**
-   * Creates a new {@link ConfigurationService} instance used to configure an
-   * {@link io.javaoperatorsdk.operator.Operator} instance, starting from the specified base
-   * configuration and overriding specific aspects according to the provided
-   * {@link ConfigurationServiceOverrider} instance.
-   *
-   * <p>
-   * <em>NOTE:</em> This overriding mechanism should only be used <strong>before</strong> creating
-   * your Operator instance as the configuration service is set at creation time and cannot be
-   * subsequently changed. As a result, overriding values this way after the Operator has been
-   * configured will not take effect.
-   * </p>
-   *
-   * @param baseConfiguration the {@link ConfigurationService} to start from
-   * @param overrider the {@link ConfigurationServiceOverrider} used to change the values provided
-   *        by the base configuration
-   * @return a new {@link ConfigurationService} starting from the configuration provided as base but
-   *         with overridden values.
-   */
-  static ConfigurationService newOverriddenConfigurationService(
-      ConfigurationService baseConfiguration,
-      Consumer<ConfigurationServiceOverrider> overrider) {
-    if (overrider != null) {
-      final var toOverride = new ConfigurationServiceOverrider(baseConfiguration);
-      overrider.accept(toOverride);
-      return toOverride.build();
-    }
-    return baseConfiguration;
-  }
-
-  /**
-   * Creates a new {@link ConfigurationService} instance used to configure an
-   * {@link io.javaoperatorsdk.operator.Operator} instance, starting from the default configuration
-   * and overriding specific aspects according to the provided {@link ConfigurationServiceOverrider}
-   * instance.
-   *
-   * <p>
-   * <em>NOTE:</em> This overriding mechanism should only be used <strong>before</strong> creating
-   * your Operator instance as the configuration service is set at creation time and cannot be
-   * subsequently changed. As a result, overriding values this way after the Operator has been
-   * configured will not take effect.
-   * </p>
-   *
-   * @param overrider the {@link ConfigurationServiceOverrider} used to change the values provided
-   *        by the default configuration
-   * @return a new {@link ConfigurationService} overriding the default values with the ones provided
-   *         by the specified {@link ConfigurationServiceOverrider}
-   * @since 4.4.0
+   * Override to provide a custom {@link ExecutorServiceManager} implementation
+   * 
+   * @return the custom {@link ExecutorServiceManager} implementation
    */
-  static ConfigurationService newOverriddenConfigurationService(
-      Consumer<ConfigurationServiceOverrider> overrider) {
-    return newOverriddenConfigurationService(new BaseConfigurationService(), overrider);
-  }
-
   default ExecutorServiceManager getExecutorServiceManager() {
     return new ExecutorServiceManager(this);
   }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/dependent/DependentResource.java

@@ -15,6 +15,18 @@
  */
 public interface DependentResource<R, P extends HasMetadata> {
 
+  /**
+   * Computes a default name for the specified DependentResource class
+   *
+   * @param dependentResourceClass the DependentResource class for which we want to compute a
+   *        default name
+   * @return the default name for the specified DependentResource class
+   */
+  @SuppressWarnings("rawtypes")
+  static String defaultNameFor(Class<? extends DependentResource> dependentResourceClass) {
+    return dependentResourceClass.getName();
+  }
+
   /**
    * Reconciles the dependent resource given the desired primary state
    *
@@ -65,21 +77,23 @@ default Optional<R> getSecondaryResource(P primary, Context<P> context) {
   }
 
   /**
-   * Computes a default name for the specified DependentResource class
+   * Determines whether resources associated with this dependent need explicit handling when
+   * deleted, usually meaning that the dependent implements {@link Deleter}
    *
-   * @param dependentResourceClass the DependentResource class for which we want to compute a
-   *        default name
-   * @return the default name for the specified DependentResource class
+   * @return {@code true} if explicit handling of resource deletion is needed, {@link false}
+   *         otherwise
    */
-  @SuppressWarnings("rawtypes")
-  static String defaultNameFor(Class<? extends DependentResource> dependentResourceClass) {
-    return dependentResourceClass.getName();
-  }
-
   default boolean isDeletable() {
     return this instanceof Deleter;
   }
 
+
+  /**
+   * Retrieves the name identifying this DependentResource implementation, useful to refer to this
+   * in {@link io.javaoperatorsdk.operator.processing.dependent.workflow.Workflow} instances
+   *
+   * @return the name identifying this DependentResource implementation
+   */
   default String name() {
     return defaultNameFor(getClass());
   }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/health/EventSourceHealthIndicator.java

@@ -2,5 +2,12 @@
 
 public interface EventSourceHealthIndicator {
 
+  /**
+   * Retrieves the health status of an
+   * {@link io.javaoperatorsdk.operator.processing.event.source.EventSource}
+   *
+   * @return the health status
+   * @see Status
+   */
   Status getStatus();
 }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/health/Status.java

@@ -1,5 +1,8 @@
 package io.javaoperatorsdk.operator.health;
 
+/**
+ * The health status of an {@link io.javaoperatorsdk.operator.processing.event.source.EventSource}
+ */
 public enum Status {
 
   HEALTHY, UNHEALTHY,

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/AbstractDependentResource.java

@@ -16,6 +16,14 @@
 import io.javaoperatorsdk.operator.processing.dependent.Matcher.Result;
 import io.javaoperatorsdk.operator.processing.event.ResourceID;
 
+/**
+ * An abstract implementation of {@link DependentResource} to be used as base for custom
+ * implementations, providing, in particular, the core {@link #reconcile(HasMetadata, Context)}
+ * logic for dependents
+ * 
+ * @param <R> the dependent resource type
+ * @param <P> the associated primary resource type
+ */
 @Ignore
 public abstract class AbstractDependentResource<R, P extends HasMetadata>
     implements DependentResource<R, P>, NameSetter {
@@ -24,18 +32,16 @@ public abstract class AbstractDependentResource<R, P extends HasMetadata>
   private final boolean creatable = this instanceof Creator;
   private final boolean updatable = this instanceof Updater;
   private final boolean deletable = this instanceof Deleter;
-
+  private final DependentResourceReconciler<R, P> dependentResourceReconciler;
   protected Creator<R, P> creator;
   protected Updater<R, P> updater;
-  private final DependentResourceReconciler<R, P> dependentResourceReconciler;
-
   protected String name;
 
-  @SuppressWarnings({"unchecked"})
   protected AbstractDependentResource() {
     this(null);
   }
 
+  @SuppressWarnings("unchecked")
   protected AbstractDependentResource(String name) {
     creator = creatable ? (Creator<R, P>) this : null;
     updater = updatable ? (Updater<R, P>) this : null;
@@ -120,7 +126,8 @@ public Optional<R> getSecondaryResource(P primary, Context<P> context) {
    * secondary candidates for equality with the specified desired state, which might end up costly.
    *
    * @param secondaryResources to select the target resource from
-   *
+   * @param primary the primary resource
+   * @param context the context in which this method is called
    * @return the matching secondary resource or {@link Optional#empty()} if none matches
    * @throws IllegalStateException if more than one candidate is found, in which case some other
    *         mechanism might be necessary to distinguish between candidate secondary resources

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/BulkDependentResource.java

@@ -12,6 +12,9 @@
  * dependent resource is to manage the number of secondary resources dynamically it implement
  * {@link Creator} and {@link Deleter} interfaces out of the box. A concrete dependent resource can
  * implement additionally also {@link Updater}.
+ *
+ * @param <R> the dependent resource type
+ * @param <P> the primary resource type
  */
 public interface BulkDependentResource<R, P extends HasMetadata> {