improve: generic cache-aware secondary resource lookup for dependent resources

Introduces a cache-aware O(1) secondary resource lookup path at the
AbstractEventSourceHolderDependentResource level, generalising the
optimisation that was previously only available in a Kubernetes-specific
branch (optimize-kube-dependent).

## Problem

AbstractDependentResource.getSecondaryResource() calls
Context.getSecondaryResources(resourceType()), which loads all secondary
resources into a Set<R> and then delegates to selectTargetSecondaryResource()
to filter down to the single expected resource. For KubernetesDependentResource
this additionally calls getOrComputeDesired() inside
selectTargetSecondaryResource() just to derive the target name/namespace —
even though InformerEventSource already provides an O(1) cache.get(ResourceID)
API.  For AbstractExternalDependentResource, selectTargetSecondaryResource()
calls desired(primary, context) equally wastefully for a mere lookup.

## Solution

AbstractEventSourceHolderDependentResource: overrides getSecondaryResource()
to check whether the event source implements Cache<R>. When it does, and when
targetSecondaryResourceID() returns a non-null ResourceID, the framework
calls cache.get(resourceID) directly — a single O(1) hash-map lookup.
Adds targetSecondaryResourceID() returning null by default (fully backward
compatible: existing subclasses see no change).

KubernetesDependentResource: the existing targetSecondaryResourceID() override
naturally wires into the new generic parent mechanism. selectTargetSecondaryResource()
is retained as a fallback for shared/non-informer event source scenarios.
Both methods re-documented to clarify the preferred fast path.

AbstractExternalDependentResource: overrides getSecondaryResource() to call
ExternalResourceCachingEventSource.getSecondaryResource(primaryID) directly,
bypassing desired() computation in selectTargetSecondaryResource().

All changes are strictly additive/override-with-fallback — no API removed,
no existing subclass needs to change.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Mohit Gupta

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

@@ -27,6 +27,7 @@
 import io.javaoperatorsdk.operator.api.reconciler.dependent.RecentOperationCacheFiller;
 import io.javaoperatorsdk.operator.processing.event.EventSourceRetriever;
 import io.javaoperatorsdk.operator.processing.event.ResourceID;
+import io.javaoperatorsdk.operator.processing.event.source.Cache;
 import io.javaoperatorsdk.operator.processing.event.source.EventSource;
 
 @Ignore
@@ -123,6 +124,60 @@ public Optional<T> eventSource() {
     return Optional.ofNullable(eventSource);
   }
 
+  /**
+   * Returns the secondary resource for the given primary, using an optimized O(1) cache lookup when
+   * the associated event source implements {@link Cache} and {@link
+   * #targetSecondaryResourceID(HasMetadata, Context)} is overridden to return a non-null {@link
+   * ResourceID}.
+   *
+   * <p>When the event source does not implement {@link Cache} or the target {@link ResourceID} is
+   * not known, the method falls back to the default context-based lookup via {@link
+   * AbstractDependentResource#getSecondaryResource(HasMetadata, Context)}, which loads all
+   * secondary resources of the matching type and delegates to {@link
+   * AbstractDependentResource#selectTargetSecondaryResource(java.util.Set, HasMetadata, Context)}.
+   *
+   * @param primary the primary resource
+   * @param context the reconciliation context
+   * @return the secondary resource if found, or {@link Optional#empty()}
+   */
+  @Override
+  public Optional<R> getSecondaryResource(P primary, Context<P> context) {
+    var es = eventSource();
+    if (es.isPresent() && es.get() instanceof Cache<?>) {
+      @SuppressWarnings("unchecked")
+      Cache<R> cache = (Cache<R>) es.get();
+      ResourceID targetID = targetSecondaryResourceID(primary, context);
+      if (targetID != null) {
+        return cache.get(targetID);
+      }
+    }
+    return super.getSecondaryResource(primary, context);
+  }
+
+  /**
+   * Returns the {@link ResourceID} of the expected secondary resource to enable a direct O(1) cache
+   * lookup, bypassing the costlier {@link
+   * io.javaoperatorsdk.operator.api.reconciler.Context#getSecondaryResources} path.
+   *
+   * <p>This hook is called by {@link #getSecondaryResource(HasMetadata, Context)} only when the
+   * associated event source implements {@link Cache}. When this method returns a non-null value,
+   * the framework performs {@code cache.get(resourceID)} directly instead of loading all secondary
+   * resources and filtering through them.
+   *
+   * <p>Implementors are strongly encouraged to return a cheap, statically-derivable {@link
+   * ResourceID} (e.g. based on the primary's name or a fixed naming convention) to avoid computing
+   * the full desired state during secondary resource lookup. See {@code
+   * KubernetesDependentResource#targetSecondaryResourceID} for a concrete example.
+   *
+   * @param primary the primary resource associated with the secondary resource being looked up
+   * @param context the current reconciliation context
+   * @return the {@link ResourceID} identifying the expected secondary resource, or {@code null} if
+   *     not known (falls back to the default lookup path)
+   */
+  protected ResourceID targetSecondaryResourceID(P primary, Context<P> context) {
+    return null;
+  }
+
   protected void onCreated(P primary, R created, Context<P> context) {
     if (isCacheFillerEventSource) {
       recentOperationCacheFiller()

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

@@ -26,6 +26,7 @@
 import io.javaoperatorsdk.operator.processing.event.EventSourceRetriever;
 import io.javaoperatorsdk.operator.processing.event.ResourceID;
 import io.javaoperatorsdk.operator.processing.event.source.EventSource;
+import io.javaoperatorsdk.operator.processing.event.source.ExternalResourceCachingEventSource;
 import io.javaoperatorsdk.operator.processing.event.source.informer.InformerEventSource;
 
 public abstract class AbstractExternalDependentResource<
@@ -103,6 +104,33 @@ protected void handleExplicitStateCreation(P primary, R created, Context<P> cont
     }
   }
 
+  /**
+   * Returns the secondary resource for the given primary, using a direct cache lookup on the
+   * underlying {@link
+   * io.javaoperatorsdk.operator.processing.event.source.ExternalResourceCachingEventSource} when
+   * available. This avoids the default path which calls {@link
+   * io.javaoperatorsdk.operator.api.reconciler.Context#getSecondaryResources} and then delegates to
+   * {@link #selectTargetSecondaryResource(java.util.Set, HasMetadata, Context)}, which in turn
+   * computes the full desired state unnecessarily for a mere lookup.
+   *
+   * <p>Falls back to the standard path when the event source is not cache-aware (e.g. for custom or
+   * shared event source implementations).
+   *
+   * @param primary the primary resource
+   * @param context the reconciliation context
+   * @return the secondary resource if found, or {@link Optional#empty()}
+   */
+  @Override
+  public Optional<R> getSecondaryResource(P primary, Context<P> context) {
+    var es = eventSource();
+    if (es.isPresent() && es.get() instanceof ExternalResourceCachingEventSource<?, ?, ?>) {
+      @SuppressWarnings("unchecked")
+      var extCache = (ExternalResourceCachingEventSource<R, P, ?>) es.get();
+      return extCache.getSecondaryResource(ResourceID.fromResource(primary));
+    }
+    return super.getSecondaryResource(primary, context);
+  }
+
   @Override
   public Matcher.Result<R> match(R resource, P primary, Context<P> context) {
     var desired = getOrComputeDesired(context);

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

@@ -247,6 +247,18 @@ protected void addSecondaryToPrimaryMapperAnnotations(
     annotations.put(typeKey, GroupVersionKind.gvkFor(primary.getClass()).toGVKString());
   }
 
+  /**
+   * Provides a fallback secondary resource selection when the cache-aware lookup path (via {@link
+   * #targetSecondaryResourceID(HasMetadata, Context)}) is not taken. This occurs when the event
+   * source does not implement {@link io.javaoperatorsdk.operator.processing.event.source.Cache} or
+   * when a shared event source is used.
+   *
+   * <p>In the common case where the event source is an {@link
+   * io.javaoperatorsdk.operator.processing.event.source.informer.InformerEventSource}, this method
+   * is <em>not</em> called because {@link #targetSecondaryResourceID(HasMetadata, Context)} is
+   * implemented and {@code InformerEventSource} implements {@code Cache}. Prefer overriding {@link
+   * #targetSecondaryResourceID(HasMetadata, Context)} for performance-critical code paths.
+   */
   @Override
   protected Optional<R> selectTargetSecondaryResource(
       Set<R> secondaryResources, P primary, Context<P> context) {
@@ -262,13 +274,20 @@ protected Optional<R> selectTargetSecondaryResource(
   }
 
   /**
-   * Override this method in order to optimize and not compute the desired when selecting the target
-   * secondary resource. Simply, a static ResourceID can be returned.
+   * Returns the {@link ResourceID} of the target secondary resource, driving the O(1) cache lookup
+   * in the parent class when the event source implements {@link
+   * io.javaoperatorsdk.operator.processing.event.source.Cache}.
    *
-   * @param primary resource
-   * @param context of current reconciliation
-   * @return id of the target managed resource
+   * <p>Override this method to provide a cheap, statically-derivable {@link ResourceID} (e.g.
+   * derived from the primary resource's name or a fixed naming convention) and thereby avoid
+   * computing the full desired state during secondary resource lookup. The base implementation
+   * falls back to {@link #getOrComputeDesired(Context)}, which is correct but may be costlier.
+   *
+   * @param primary the primary resource
+   * @param context the current reconciliation context
+   * @return the {@link ResourceID} of the managed secondary resource
    */
+  @Override
   protected ResourceID targetSecondaryResourceID(P primary, Context<P> context) {
     return ResourceID.fromResource(getOrComputeDesired(context));
   }