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

Author: afalhambra-hivemq

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

@@ -114,6 +114,89 @@ default <R> Stream<R> getSecondaryResourcesAsStream(Class<R> expectedType) {
 
   <R> Optional<R> getSecondaryResource(Class<R> expectedType, String eventSourceName);
 
+  /**
+   * Retrieves a specific secondary resource by name and namespace 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 name the name of the secondary resource
+   * @param namespace the namespace of the secondary resource (may be {@code null} for
+   *     cluster-scoped resources)
+   * @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.4.0
+   */
+  <R extends HasMetadata> Optional<R> getSecondaryResource(
+      Class<R> expectedType, String eventSourceName, String name, String namespace);
+
+  /**
+   * Convenience overload of {@link #getSecondaryResource(Class, String, String, String)} that uses
+   * 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, String, String)} directly.
+   *
+   * <p>{@code eventSourceName} may be {@code null} with the same semantics as in {@link
+   * #getSecondaryResource(Class, String, String, String)}.
+   *
+   * @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.4.0
+   */
+  default <R extends HasMetadata> Optional<R> getSecondaryResource(
+      Class<R> expectedType, String eventSourceName, String name) {
+    return getSecondaryResource(
+        expectedType, eventSourceName, 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, String, String)}: 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.4.0
+   */
+  <R extends HasMetadata> 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,51 @@ 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 extends HasMetadata> Optional<R> getSecondaryResource(
+      Class<R> expectedType, String eventSourceName, String name, String namespace) {
+    try {
+      final var eventSource =
+          controller.getEventSourceManager().getEventSourceFor(expectedType, eventSourceName);
+      final var resourceID = new ResourceID(name, namespace);
+      if (eventSource instanceof Cache<?> cache) {
+        return cache.get(resourceID).map(expectedType::cast);
+      }
+      return eventSource.getSecondaryResources(primaryResource).stream()
+          .filter(r -> ResourceID.fromResource(r).equals(resourceID))
+          .findFirst();
+    } catch (NoEventSourceForClassException e) {
+      if (isMissingEventSourceExpected(eventSourceName, expectedType)) {
+        return Optional.empty();
+      }
+      throw e;
+    }
+  }
+
+  @Override
+  public <R extends HasMetadata> 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();
+    } catch (NoEventSourceForClassException e) {
+      if (isMissingEventSourceExpected(eventSourceName, expectedType)) {
+        return Stream.empty();
+      }
+      throw e;
     }
   }