feat: improve Context / EventSource API

- Record type handled by EventSource so that we can retrieve an 
  associated secondary resource from a primary one directly from 
  the Context
- Introduce `ResourceEventSource` concept
- Update sample reconcilers to use the new Context functionality
- Make `EventSourceInitializer` return list of `EventSource`s
  This makes the intent clearer: the `EventSourceInitializer` prepares
  `EventSource`s that the SDK then registers automatically, without the
  reconciler having to call the register method in `prepareEventSources`.
  This also allows for removing the `EventSourceRegistry` interface
  altogether.
- Extract interfaces for mappers instead of using `Function`
- Introduce `EventSourceInitializationContext` for future-proofing

Author: metacosm

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

@@ -2,6 +2,7 @@
 
 import java.util.Locale;
 
+import io.javaoperatorsdk.operator.api.reconciler.Constants;
 import io.javaoperatorsdk.operator.api.reconciler.ControllerConfiguration;
 import io.javaoperatorsdk.operator.api.reconciler.Reconciler;
 
@@ -19,7 +20,7 @@ public static String getNameFor(Class<? extends Reconciler> reconcilerClass) {
     final var annotation = reconcilerClass.getAnnotation(ControllerConfiguration.class);
     if (annotation != null) {
       final var name = annotation.name();
-      if (!ControllerConfiguration.EMPTY_STRING.equals(name)) {
+      if (!Constants.EMPTY_STRING.equals(name)) {
         return name;
       }
     }

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

@@ -7,6 +7,7 @@
 import io.fabric8.kubernetes.api.model.HasMetadata;
 import io.fabric8.kubernetes.client.CustomResource;
 import io.javaoperatorsdk.operator.ReconcilerUtils;
+import io.javaoperatorsdk.operator.api.reconciler.Constants;
 import io.javaoperatorsdk.operator.processing.event.source.controller.ResourceEventFilter;
 import io.javaoperatorsdk.operator.processing.event.source.controller.ResourceEventFilters;
 
@@ -67,7 +68,7 @@ static boolean currentNamespaceWatched(Set<String> namespaces) {
     return namespaces != null
         && namespaces.size() == 1
         && namespaces.contains(
-            io.javaoperatorsdk.operator.api.reconciler.ControllerConfiguration.WATCH_CURRENT_NAMESPACE);
+            Constants.WATCH_CURRENT_NAMESPACE);
   }
 
   /**
@@ -99,7 +100,7 @@ default RetryConfiguration getRetryConfiguration() {
   default void setConfigurationService(ConfigurationService service) {}
 
   default boolean useFinalizer() {
-    return !io.javaoperatorsdk.operator.api.reconciler.ControllerConfiguration.NO_FINALIZER
+    return !Constants.NO_FINALIZER
         .equals(getFinalizer());
   }
 

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

@@ -0,0 +1,10 @@
+package io.javaoperatorsdk.operator.api.reconciler;
+
+public final class Constants {
+
+  public static final String EMPTY_STRING = "";
+  public static final String WATCH_CURRENT_NAMESPACE = "JOSDK_WATCH_CURRENT";
+  public static final String NO_FINALIZER = "JOSDK_NO_FINALIZER";
+
+  private Constants() {}
+}

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

@@ -6,4 +6,5 @@ public interface Context {
 
   Optional<RetryInfo> getRetryInfo();
 
+  <T> T getSecondaryResource(Class<T> expectedType, String... qualifier);
 }

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

@@ -11,20 +11,16 @@
 @Target({ElementType.TYPE})
 public @interface ControllerConfiguration {
 
-  String EMPTY_STRING = "";
-  String WATCH_CURRENT_NAMESPACE = "JOSDK_WATCH_CURRENT";
-  String NO_FINALIZER = "JOSDK_NO_FINALIZER";
-
-  String name() default EMPTY_STRING;
+  String name() default Constants.EMPTY_STRING;
 
   /**
    * Optional finalizer name, if it is not provided, one will be automatically generated. If the
-   * provided value is the value specified by {@link #NO_FINALIZER}, then no finalizer will be added
-   * to custom resources.
+   * provided value is the value specified by {@link Constants#NO_FINALIZER}, then no finalizer will
+   * be added to custom resources.
    *
    * @return the finalizer name
    */
-  String finalizerName() default EMPTY_STRING;
+  String finalizerName() default Constants.EMPTY_STRING;
 
   /**
    * If true, will dispatch new event to the controller if generation increased since the last
@@ -50,7 +46,7 @@
    *
    * @return the label selector
    */
-  String labelSelector() default EMPTY_STRING;
+  String labelSelector() default Constants.EMPTY_STRING;
 
 
   /**

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

@@ -2,16 +2,30 @@
 
 import java.util.Optional;
 
-public class DefaultContext implements Context {
+import io.fabric8.kubernetes.api.model.HasMetadata;
+import io.javaoperatorsdk.operator.processing.Controller;
+
+public class DefaultContext<P extends HasMetadata> implements Context {
 
   private final RetryInfo retryInfo;
+  private final Controller<P> controller;
+  private final P primaryResource;
 
-  public DefaultContext(RetryInfo retryInfo) {
+  public DefaultContext(RetryInfo retryInfo, Controller<P> controller, P primaryResource) {
     this.retryInfo = retryInfo;
+    this.controller = controller;
+    this.primaryResource = primaryResource;
   }
 
   @Override
   public Optional<RetryInfo> getRetryInfo() {
     return Optional.ofNullable(retryInfo);
   }
+
+  @Override
+  public <T> T getSecondaryResource(Class<T> expectedType, String... qualifier) {
+    final var eventSource =
+        controller.getEventSourceManager().getResourceEventSourceFor(expectedType, qualifier);
+    return eventSource.map(es -> es.getAssociated(primaryResource)).orElse(null);
+  }
 }

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

@@ -0,0 +1,17 @@
+package io.javaoperatorsdk.operator.api.reconciler;
+
+import io.fabric8.kubernetes.api.model.HasMetadata;
+import io.javaoperatorsdk.operator.processing.event.source.ResourceCache;
+
+public class EventSourceInitializationContext<P extends HasMetadata> {
+
+  private final ResourceCache<P> primaryCache;
+
+  public EventSourceInitializationContext(ResourceCache<P> primaryCache) {
+    this.primaryCache = primaryCache;
+  }
+
+  public ResourceCache<P> getPrimaryCache() {
+    return primaryCache;
+  }
+}

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

@@ -1,17 +1,24 @@
 package io.javaoperatorsdk.operator.api.reconciler;
 
+import java.util.List;
+
 import io.fabric8.kubernetes.api.model.HasMetadata;
-import io.javaoperatorsdk.operator.processing.event.source.EventSourceRegistry;
+import io.javaoperatorsdk.operator.processing.event.source.EventSource;
 
-public interface EventSourceInitializer<T extends HasMetadata> {
+/**
+ * An interface that a {@link Reconciler} can implement to have the SDK register the provided
+ * {@link EventSource}
+ * 
+ * @param <P> the primary resource type handled by the associated {@link Reconciler}
+ */
+public interface EventSourceInitializer<P extends HasMetadata> {
 
   /**
-   * Reconciler can implement this interface typically to register event sources. But can access
-   * CustomResourceEventSource, what might be useful for some edge cases.
+   * Prepares a list of {@link EventSource} implementations to be registered by the SDK.
    * 
-   * @param eventSourceRegistry the {@link EventSourceRegistry} where event sources can be
-   *        registered.
+   * @param primaryCache a cache providing direct access to primary resources so that event sources
+   *        can extract relevant information from primary resources as needed
    */
-  void prepareEventSources(EventSourceRegistry<T> eventSourceRegistry);
+  List<EventSource> prepareEventSources(EventSourceInitializationContext<P> context);
 
 }

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

@@ -40,5 +40,4 @@ public interface Reconciler<R extends HasMetadata> {
   default DeleteControl cleanup(R resource, Context context) {
     return DeleteControl.defaultDelete();
   }
-
 }

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

@@ -1,5 +1,6 @@
 package io.javaoperatorsdk.operator.processing;
 
+import java.util.List;
 import java.util.Objects;
 
 import io.fabric8.kubernetes.api.model.HasMetadata;
@@ -15,11 +16,12 @@
 import io.javaoperatorsdk.operator.api.monitoring.Metrics.ControllerExecution;
 import io.javaoperatorsdk.operator.api.reconciler.Context;
 import io.javaoperatorsdk.operator.api.reconciler.DeleteControl;
+import io.javaoperatorsdk.operator.api.reconciler.EventSourceInitializationContext;
 import io.javaoperatorsdk.operator.api.reconciler.EventSourceInitializer;
 import io.javaoperatorsdk.operator.api.reconciler.Reconciler;
 import io.javaoperatorsdk.operator.api.reconciler.UpdateControl;
 import io.javaoperatorsdk.operator.processing.event.EventSourceManager;
-import io.javaoperatorsdk.operator.processing.event.source.EventSourceRegistry;
+import io.javaoperatorsdk.operator.processing.event.source.EventSource;
 
 public class Controller<R extends HasMetadata> implements Reconciler<R>,
     LifecycleAware, EventSourceInitializer<R> {
@@ -96,7 +98,7 @@ public UpdateControl<R> execute() {
   }
 
   @Override
-  public void prepareEventSources(EventSourceRegistry<R> eventSourceRegistry) {
+  public List<EventSource> prepareEventSources(EventSourceInitializationContext<R> context) {
     throw new UnsupportedOperationException("This method should never be called directly");
   }
 
@@ -169,7 +171,10 @@ public void start() throws OperatorException {
 
       eventSourceManager = new EventSourceManager<>(this);
       if (reconciler instanceof EventSourceInitializer) {
-        ((EventSourceInitializer<R>) reconciler).prepareEventSources(eventSourceManager);
+        ((EventSourceInitializer<R>) reconciler)
+            .prepareEventSources(new EventSourceInitializationContext<>(
+                eventSourceManager.getControllerResourceEventSource().getResourceCache()))
+            .forEach(eventSourceManager::registerEventSource);
       }
       if (failOnMissingCurrentNS()) {
         throw new OperatorException(