feat(core): add by-name secondary resource lookup on Context

Signed-off-by: Antonio Fernandez Alhambra <antonio.alhambra@hivemq.com>

Author: afalhambra-hivemq

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

@@ -25,6 +25,7 @@
 import io.javaoperatorsdk.operator.api.config.ControllerConfiguration;
 import io.javaoperatorsdk.operator.api.reconciler.dependent.managed.ManagedWorkflowAndDependentResourceContext;
 import io.javaoperatorsdk.operator.processing.event.EventSourceRetriever;
+import io.javaoperatorsdk.operator.processing.event.ResourceID;
 import io.javaoperatorsdk.operator.processing.event.source.IndexerResourceCache;
 
 public interface Context<P extends HasMetadata> {
@@ -114,6 +115,88 @@ default <R> Stream<R> getSecondaryResourcesAsStream(Class<R> expectedType) {
 
   <R> Optional<R> getSecondaryResource(Class<R> expectedType, String eventSourceName);
 
+  /**
+   * Retrieves a specific secondary resource by its {@link ResourceID} from the event source
+   * identified by the given name.
+   *
+   * <p>This is a typed convenience over manually retrieving the {@link
+   * io.javaoperatorsdk.operator.processing.event.source.EventSource} and calling its cache. When
+   * the underlying event source implements {@link
+   * io.javaoperatorsdk.operator.processing.event.source.Cache}, the lookup is a direct cache lookup
+   * and read-cache-after-write consistent.
+   *
+   * <p>{@code eventSourceName} may be {@code null}. When {@code null} and {@code expectedType} is
+   * part of a managed workflow whose activation condition may not have registered the event source,
+   * an empty {@link Optional} is returned instead of throwing {@link
+   * io.javaoperatorsdk.operator.processing.event.NoEventSourceForClassException}.
+   *
+   * @param expectedType the class representing the type of secondary resource to retrieve
+   * @param eventSourceName the name of the event source to look in (may be {@code null})
+   * @param resourceID the {@link ResourceID} identifying the secondary resource
+   * @param <R> the type of secondary resource to retrieve
+   * @return an {@link Optional} containing the matching secondary resource, or {@link
+   *     Optional#empty()} if none matches
+   * @throws io.javaoperatorsdk.operator.processing.event.NoEventSourceForClassException if no event
+   *     source is registered for the given type and name (and no workflow activation condition
+   *     accounts for it)
+   * @since 5.3.5
+   */
+  <R> Optional<R> getSecondaryResource(
+      Class<R> expectedType, String eventSourceName, ResourceID resourceID);
+
+  /**
+   * Convenience overload of {@link #getSecondaryResource(Class, String, ResourceID)} that
+   * constructs the {@link ResourceID} using the given name and the primary resource's namespace.
+   *
+   * <p>If the primary resource is cluster-scoped (no namespace), the lookup is performed against
+   * the cluster scope. To target a specific namespace from a cluster-scoped primary, use {@link
+   * #getSecondaryResource(Class, String, ResourceID)} directly.
+   *
+   * <p>{@code eventSourceName} may be {@code null} with the same semantics as in {@link
+   * #getSecondaryResource(Class, String, ResourceID)}.
+   *
+   * @param expectedType the class representing the type of secondary resource to retrieve
+   * @param eventSourceName the name of the event source to look in (may be {@code null})
+   * @param name the name of the secondary resource (namespace inferred from the primary)
+   * @param <R> the type of secondary resource to retrieve
+   * @return an {@link Optional} containing the matching secondary resource, or {@link
+   *     Optional#empty()} if none matches
+   * @since 5.3.5
+   */
+  default <R> Optional<R> getSecondaryResource(
+      Class<R> expectedType, String eventSourceName, String name) {
+    return getSecondaryResource(
+        expectedType,
+        eventSourceName,
+        new ResourceID(name, getPrimaryResource().getMetadata().getNamespace()));
+  }
+
+  /**
+   * Retrieves a {@link Stream} of the secondary resources of the specified type from the event
+   * source identified by the given name. Useful when several event sources are registered for the
+   * same type and you need to scope retrieval to one of them, or when you want to apply a custom
+   * filter at the call site.
+   *
+   * <p>When the underlying event source implements {@link ResourceCache}, the stream is
+   * read-cache-after-write consistent.
+   *
+   * <p>{@code eventSourceName} may be {@code null} with the same semantics as in {@link
+   * #getSecondaryResource(Class, String, ResourceID)}: when {@code null} and {@code expectedType}
+   * is part of a managed workflow whose activation condition may not have registered the event
+   * source, an empty {@link Stream} is returned instead of throwing {@link
+   * io.javaoperatorsdk.operator.processing.event.NoEventSourceForClassException}.
+   *
+   * @param expectedType the class representing the type of secondary resources to retrieve
+   * @param eventSourceName the name of the event source to look in (may be {@code null})
+   * @param <R> the type of secondary resources to retrieve
+   * @return a {@link Stream} of secondary resources of the specified type
+   * @throws io.javaoperatorsdk.operator.processing.event.NoEventSourceForClassException if no event
+   *     source is registered for the given type and name (and no workflow activation condition
+   *     accounts for it)
+   * @since 5.3.5
+   */
+  <R> Stream<R> getSecondaryResourcesAsStream(Class<R> expectedType, String eventSourceName);
+
   ControllerConfiguration<P> getControllerConfiguration();
 
   /**

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

@@ -36,6 +36,7 @@
 import io.javaoperatorsdk.operator.processing.event.EventSourceRetriever;
 import io.javaoperatorsdk.operator.processing.event.NoEventSourceForClassException;
 import io.javaoperatorsdk.operator.processing.event.ResourceID;
+import io.javaoperatorsdk.operator.processing.event.source.Cache;
 
 public class DefaultContext<P extends HasMetadata> implements Context<P> {
   private RetryInfo retryInfo;
@@ -95,6 +96,20 @@ public <R> Stream<R> getSecondaryResourcesAsStream(Class<R> expectedType, boolea
     }
   }
 
+  /**
+   * Whether a missing event source for the given type is the expected case, in which case callers
+   * should return an empty result instead of propagating the {@link
+   * NoEventSourceForClassException}.
+   *
+   * <p>If a workflow has an activation condition there can be event sources which are only
+   * registered if the activation condition holds, but to provide a consistent API we return an
+   * empty result instead of throwing an exception. Note that not only the resource which has an
+   * activation condition might not be registered but dependents which depend on it.
+   */
+  private boolean isMissingEventSourceExpected(String eventSourceName, Class<?> expectedType) {
+    return eventSourceName == null && controller.workflowContainsDependentForType(expectedType);
+  }
+
   private <R> Map<ResourceID, R> deduplicatedMap(Stream<R> stream) {
     return stream.collect(
         Collectors.toUnmodifiableMap(
@@ -120,19 +135,53 @@ public <T> Optional<T> getSecondaryResource(Class<T> expectedType, String eventS
           .getEventSourceFor(expectedType, eventSourceName)
           .getSecondaryResource(primaryResource);
     } catch (NoEventSourceForClassException e) {
-      /*
-       * If a workflow has an activation condition there can be event sources which are only
-       * registered if the activation condition holds, but to provide a consistent API we return an
-       * Optional instead of throwing an exception.
-       *
-       * Note that not only the resource which has an activation condition might not be registered
-       * but dependents which depend on it.
-       */
-      if (eventSourceName == null && controller.workflowContainsDependentForType(expectedType)) {
+      if (isMissingEventSourceExpected(eventSourceName, expectedType)) {
         return Optional.empty();
-      } else {
-        throw e;
       }
+      throw e;
+    }
+  }
+
+  @Override
+  public <R> Optional<R> getSecondaryResource(
+      Class<R> expectedType, String eventSourceName, ResourceID resourceID) {
+    try {
+      final var eventSource =
+          controller.getEventSourceManager().getEventSourceFor(expectedType, eventSourceName);
+      if (eventSource instanceof Cache<?> cache) {
+        return cache.get(resourceID).map(expectedType::cast);
+      }
+      return eventSource.getSecondaryResources(primaryResource).stream()
+          .filter(HasMetadata.class::isInstance)
+          .map(HasMetadata.class::cast)
+          .filter(r -> ResourceID.fromResource(r).equals(resourceID))
+          .findFirst()
+          .map(expectedType::cast);
+    } catch (NoEventSourceForClassException e) {
+      if (isMissingEventSourceExpected(eventSourceName, expectedType)) {
+        return Optional.empty();
+      }
+      throw e;
+    }
+  }
+
+  @Override
+  public <R> Stream<R> getSecondaryResourcesAsStream(
+      Class<R> expectedType, String eventSourceName) {
+    try {
+      final var eventSource =
+          controller.getEventSourceManager().getEventSourceFor(expectedType, eventSourceName);
+      if (eventSource instanceof ResourceCache<?> resourceCache) {
+        final var ns = primaryResource.getMetadata().getNamespace();
+        final Stream<?> stream = ns == null ? resourceCache.list() : resourceCache.list(ns);
+        return stream.map(expectedType::cast);
+      }
+      return eventSource.getSecondaryResources(primaryResource).stream().map(expectedType::cast);
+    } catch (NoEventSourceForClassException e) {
+      if (isMissingEventSourceExpected(eventSourceName, expectedType)) {
+        return Stream.empty();
+      }
+      throw e;
     }
   }