refactor: renaming core classes and APIs (#646)

Renaming and refactoring structures based on the rational described in #655

Author: csviri

.github/workflows/pr.yml

@@ -35,7 +35,7 @@ jobs:
       - name: Set up Minikube
         uses: manusa/actions-setup-minikube@v2.4.2
         with:
-          minikube version: 'v1.22.0'
+          minikube version: 'v1.24.0'
           kubernetes version: ${{ matrix.kubernetes }}
           driver: 'docker'
       - name: Run integration tests

DECISION_LOG.md

@@ -146,7 +146,7 @@ The Controller implements the business logic and describes all the classes neede
 
 ```java
 
-@Controller
+@ControllerConfiguration
 public class WebServerController implements ResourceController<WebServer> {
 
   // Return the changed resource, so it gets updated. See javadoc for details.

README.md

@@ -45,14 +45,14 @@ Finalizers are automatically added by the framework as the first step, thus when
 before the first reconciliation, the custom resource is updated via a Kubernetes API call. As a result of this update, the
 finalizer will be present. The subsequent event will be received, which will trigger the first reconciliation.
 
-The finalizer that is automatically added will be also removed after the `deleteResource` is executed on the controller.
+The finalizer that is automatically added will be also removed after the `deleteResource` is executed on the controllerConfiguration.
 However, the removal behavior can be further customized, and can be instructed to "not remove yet" - this is useful just
 in some specific corner cases, when there would be a long waiting period for some dependent resource cleanup.
 
 The name of the finalizers can be specified, in case it is not, a name will be generated.
 
 This behavior can be turned off, so when configured no finalizer will be added or removed.  
-See [`@Controller`](https://github.com/java-operator-sdk/java-operator-sdk/blob/master/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/Controller.java)
+See [`@ControllerConfiguration`](https://github.com/java-operator-sdk/java-operator-sdk/blob/master/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/ControllerConfiguration.java)
 annotation for more details.
 
 ### When not to Use Finalizers?

docs/documentation/features.md

@@ -5,8 +5,8 @@
 import java.util.List;
 import java.util.Map;
 
-import io.javaoperatorsdk.operator.api.RetryInfo;
 import io.javaoperatorsdk.operator.api.monitoring.Metrics;
+import io.javaoperatorsdk.operator.api.reconciler.RetryInfo;
 import io.javaoperatorsdk.operator.processing.event.CustomResourceID;
 import io.javaoperatorsdk.operator.processing.event.Event;
 import io.micrometer.core.instrument.MeterRegistry;

docs/etc/v1_model.drawio.svg

@@ -2,8 +2,8 @@
 
 import java.util.Locale;
 
-import io.javaoperatorsdk.operator.api.Controller;
-import io.javaoperatorsdk.operator.api.ResourceController;
+import io.javaoperatorsdk.operator.api.reconciler.ControllerConfiguration;
+import io.javaoperatorsdk.operator.api.reconciler.Reconciler;
 
 @SuppressWarnings("rawtypes")
 public class ControllerUtils {
@@ -14,33 +14,32 @@ public static String getDefaultFinalizerName(String crdName) {
     return crdName + FINALIZER_NAME_SUFFIX;
   }
 
-  public static String getNameFor(Class<? extends ResourceController> controllerClass) {
+  public static String getNameFor(Class<? extends Reconciler> controllerClass) {
     // if the controller annotation has a name attribute, use it
-    final var annotation = controllerClass.getAnnotation(Controller.class);
+    final var annotation = controllerClass.getAnnotation(ControllerConfiguration.class);
     if (annotation != null) {
       final var name = annotation.name();
-      if (!Controller.EMPTY_STRING.equals(name)) {
+      if (!ControllerConfiguration.EMPTY_STRING.equals(name)) {
         return name;
       }
     }
-
     // otherwise, use the lower-cased full class name
     return getDefaultNameFor(controllerClass);
   }
 
-  public static String getNameFor(ResourceController controller) {
+  public static String getNameFor(Reconciler controller) {
     return getNameFor(controller.getClass());
   }
 
-  public static String getDefaultNameFor(ResourceController controller) {
+  public static String getDefaultNameFor(Reconciler controller) {
     return getDefaultNameFor(controller.getClass());
   }
 
-  public static String getDefaultNameFor(Class<? extends ResourceController> controllerClass) {
-    return getDefaultResourceControllerName(controllerClass.getSimpleName());
+  public static String getDefaultNameFor(Class<? extends Reconciler> reconcilerClass) {
+    return getDefaultReconcilerName(reconcilerClass.getSimpleName());
   }
 
-  public static String getDefaultResourceControllerName(String rcControllerClassName) {
+  public static String getDefaultReconcilerName(String rcControllerClassName) {
     // if the name is fully qualified, extract the simple class name
     final var lastDot = rcControllerClassName.lastIndexOf('.');
     if (lastDot > 0) {

docs/etc/v2_model.drawio.svg

@@ -14,11 +14,11 @@
 import io.fabric8.kubernetes.client.KubernetesClient;
 import io.fabric8.kubernetes.client.Version;
 import io.javaoperatorsdk.operator.api.LifecycleAware;
-import io.javaoperatorsdk.operator.api.ResourceController;
 import io.javaoperatorsdk.operator.api.config.ConfigurationService;
 import io.javaoperatorsdk.operator.api.config.ControllerConfiguration;
 import io.javaoperatorsdk.operator.api.config.ExecutorServiceManager;
-import io.javaoperatorsdk.operator.processing.ConfiguredController;
+import io.javaoperatorsdk.operator.api.reconciler.Reconciler;
+import io.javaoperatorsdk.operator.processing.Controller;
 
 @SuppressWarnings("rawtypes")
 public class Operator implements AutoCloseable, LifecycleAware {
@@ -49,7 +49,7 @@ public ConfigurationService getConfigurationService() {
     return configurationService;
   }
 
-  public List<ConfiguredController> getControllers() {
+  public List<Controller> getControllers() {
     return new ArrayList<>(controllers.controllers.values());
   }
 
@@ -114,7 +114,7 @@ public void close() {
    * @param <R> the {@code CustomResource} type associated with the controller
    * @throws OperatorException if a problem occurred during the registration process
    */
-  public <R extends CustomResource<?, ?>> void register(ResourceController<R> controller)
+  public <R extends CustomResource<?, ?>> void register(Reconciler<R> controller)
       throws OperatorException {
     register(controller, null);
   }
@@ -126,29 +126,29 @@ public void close() {
    * passing it the controller's original configuration. The effective registration of the
    * controller is delayed till the operator is started.
    *
-   * @param controller the controller to register
+   * @param reconciler part of the controller to register
    * @param configuration the configuration with which we want to register the controller, if {@code
    *     null}, the controller's original configuration is used
    * @param <R> the {@code CustomResource} type associated with the controller
    * @throws OperatorException if a problem occurred during the registration process
    */
   public <R extends CustomResource<?, ?>> void register(
-      ResourceController<R> controller, ControllerConfiguration<R> configuration)
+      Reconciler<R> reconciler, ControllerConfiguration<R> configuration)
       throws OperatorException {
-    final var existing = configurationService.getConfigurationFor(controller);
+    final var existing = configurationService.getConfigurationFor(reconciler);
     if (existing == null) {
       throw new OperatorException(
-          "Cannot register controller with name " + controller.getClass().getCanonicalName() +
-              " controller named " + ControllerUtils.getNameFor(controller)
+          "Cannot register controller with name " + reconciler.getClass().getCanonicalName() +
+              " controller named " + ControllerUtils.getNameFor(reconciler)
               + " because its configuration cannot be found.\n" +
               " Known controllers are: " + configurationService.getKnownControllerNames());
     } else {
       if (configuration == null) {
         configuration = existing;
       }
-      final var configuredController =
-          new ConfiguredController<>(controller, configuration, kubernetesClient);
-      controllers.add(configuredController);
+      final var controller =
+          new Controller<>(reconciler, configuration, kubernetesClient);
+      controllers.add(controller);
 
       final var watchedNS =
           configuration.watchAllNamespaces()
@@ -163,7 +163,7 @@ public void close() {
   }
 
   static class ControllerManager implements LifecycleAware {
-    private final Map<String, ConfiguredController> controllers = new HashMap<>();
+    private final Map<String, Controller> controllers = new HashMap<>();
     private boolean started = false;
 
     public synchronized void shouldStart() {
@@ -176,7 +176,7 @@ public synchronized void shouldStart() {
     }
 
     public synchronized void start() {
-      controllers.values().parallelStream().forEach(ConfiguredController::start);
+      controllers.values().parallelStream().forEach(Controller::start);
       started = true;
     }
 
@@ -193,18 +193,18 @@ public synchronized void stop() {
       started = false;
     }
 
-    public synchronized void add(ConfiguredController configuredController) {
-      final var configuration = configuredController.getConfiguration();
+    public synchronized void add(Controller controller) {
+      final var configuration = controller.getConfiguration();
       final var crdName = configuration.getCRDName();
       final var existing = controllers.get(crdName);
       if (existing != null) {
         throw new OperatorException("Cannot register controller '" + configuration.getName()
             + "': another controller named '" + existing.getConfiguration().getName()
             + "' is already registered for CRD '" + crdName + "'");
       }
-      this.controllers.put(crdName, configuredController);
+      this.controllers.put(crdName, controller);
       if (started) {
-        configuredController.start();
+        controller.start();
       }
     }
   }

micrometer-support/src/main/java/io/javaoperatorsdk/operator/monitoring/micrometer/MicrometerMetrics.java

@@ -3,6 +3,7 @@
 import java.util.Optional;
 
 import io.fabric8.kubernetes.client.CustomResource;
+import io.javaoperatorsdk.operator.api.reconciler.UpdateControl;
 
 /**
  * If the custom resource's status implements this interface, the observed generation will be

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/ControllerUtils.java

@@ -7,7 +7,7 @@
 
 import io.fabric8.kubernetes.client.CustomResource;
 import io.javaoperatorsdk.operator.ControllerUtils;
-import io.javaoperatorsdk.operator.api.ResourceController;
+import io.javaoperatorsdk.operator.api.reconciler.Reconciler;
 
 @SuppressWarnings("rawtypes")
 public class AbstractConfigurationService implements ConfigurationService {
@@ -32,7 +32,7 @@ public AbstractConfigurationService(Version version) {
     if (failIfExisting) {
       final var existing = configurations.get(name);
       if (existing != null) {
-        throwExceptionOnNameCollision(config.getAssociatedControllerClassName(), existing);
+        throwExceptionOnNameCollision(config.getAssociatedReconcilerClassName(), existing);
       }
     }
     configurations.put(name, config);
@@ -45,14 +45,14 @@ public AbstractConfigurationService(Version version) {
         "Controller name '"
             + existing.getName()
             + "' is used by both "
-            + existing.getAssociatedControllerClassName()
+            + existing.getAssociatedReconcilerClassName()
             + " and "
             + newControllerClassName);
   }
 
   @Override
   public <R extends CustomResource<?, ?>> ControllerConfiguration<R> getConfigurationFor(
-      ResourceController<R> controller) {
+      Reconciler<R> controller) {
     final var key = keyFor(controller);
     final var configuration = configurations.get(key);
     if (configuration == null) {
@@ -73,7 +73,7 @@ private String getControllersNameMessage() {
         + ".";
   }
 
-  protected <R extends CustomResource<?, ?>> String keyFor(ResourceController<R> controller) {
+  protected <R extends CustomResource<?, ?>> String keyFor(Reconciler<R> controller) {
     return ControllerUtils.getNameFor(controller);
   }
 

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/Operator.java

@@ -6,8 +6,8 @@
 
 import io.fabric8.kubernetes.client.Config;
 import io.fabric8.kubernetes.client.CustomResource;
-import io.javaoperatorsdk.operator.api.ResourceController;
 import io.javaoperatorsdk.operator.api.monitoring.Metrics;
+import io.javaoperatorsdk.operator.api.reconciler.Reconciler;
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -37,7 +37,7 @@ public interface ConfigurationService {
    * null} if no configuration exists for the controller
    */
   <R extends CustomResource<?, ?>> ControllerConfiguration<R> getConfigurationFor(
-      ResourceController<R> controller);
+      Reconciler<R> controller);
 
   /**
    * Retrieves the Kubernetes client configuration

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

@@ -4,8 +4,8 @@
 
 import io.fabric8.kubernetes.client.Config;
 import io.fabric8.kubernetes.client.CustomResource;
-import io.javaoperatorsdk.operator.api.ResourceController;
 import io.javaoperatorsdk.operator.api.monitoring.Metrics;
+import io.javaoperatorsdk.operator.api.reconciler.Reconciler;
 
 public class ConfigurationServiceOverrider {
   private final ConfigurationService original;
@@ -62,7 +62,7 @@ public ConfigurationService build() {
     return new ConfigurationService() {
       @Override
       public <R extends CustomResource<?, ?>> ControllerConfiguration<R> getConfigurationFor(
-          ResourceController<R> controller) {
+          Reconciler<R> controller) {
         return original.getConfigurationFor(controller);
       }
 

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

@@ -6,14 +6,13 @@
 
 import io.fabric8.kubernetes.client.CustomResource;
 import io.javaoperatorsdk.operator.ControllerUtils;
-import io.javaoperatorsdk.operator.api.Controller;
 import io.javaoperatorsdk.operator.processing.event.internal.CustomResourceEventFilter;
 import io.javaoperatorsdk.operator.processing.event.internal.CustomResourceEventFilters;
 
 public interface ControllerConfiguration<R extends CustomResource<?, ?>> {
 
   default String getName() {
-    return ControllerUtils.getDefaultResourceControllerName(getAssociatedControllerClassName());
+    return ControllerUtils.getDefaultReconcilerName(getAssociatedReconcilerClassName());
   }
 
   default String getCRDName() {
@@ -45,7 +44,7 @@ default Class<R> getCustomResourceClass() {
     return (Class<R>) type.getActualTypeArguments()[0];
   }
 
-  String getAssociatedControllerClassName();
+  String getAssociatedReconcilerClassName();
 
   default Set<String> getNamespaces() {
     return Collections.emptySet();
@@ -66,7 +65,8 @@ default boolean watchCurrentNamespace() {
   static boolean currentNamespaceWatched(Set<String> namespaces) {
     return namespaces != null
         && namespaces.size() == 1
-        && namespaces.contains(Controller.WATCH_CURRENT_NAMESPACE);
+        && namespaces.contains(
+            io.javaoperatorsdk.operator.api.reconciler.ControllerConfiguration.WATCH_CURRENT_NAMESPACE);
   }
 
   /**
@@ -98,7 +98,8 @@ default RetryConfiguration getRetryConfiguration() {
   default void setConfigurationService(ConfigurationService service) {}
 
   default boolean useFinalizer() {
-    return !Controller.NO_FINALIZER.equals(getFinalizer());
+    return !io.javaoperatorsdk.operator.api.reconciler.ControllerConfiguration.NO_FINALIZER
+        .equals(getFinalizer());
   }
 
   /**

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

@@ -76,7 +76,7 @@ public ControllerConfigurationOverrider<R> withCustomResourcePredicate(
 
   public ControllerConfiguration<R> build() {
     return new DefaultControllerConfiguration<>(
-        original.getAssociatedControllerClassName(),
+        original.getAssociatedReconcilerClassName(),
         original.getName(),
         original.getCRDName(),
         finalizer,

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

@@ -75,7 +75,7 @@ public boolean isGenerationAware() {
   }
 
   @Override
-  public String getAssociatedControllerClassName() {
+  public String getAssociatedReconcilerClassName() {
     return associatedControllerClassName;
   }