feat: ResourceIDMapper for external event sources, external dependents and bulk dependents

docs/content/en/docs/documentation/dependent-resource-and-workflows/dependent-resources.md

@@ -370,13 +370,13 @@ or we can use a matcher based SSA in most of the cases if the resource is manage
 
 Unfortunately this is not true for external resources. So to make sure we are selecting
 the target resources from an event source, we provide a [mechanism](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/AbstractExternalDependentResource.java#L114-L138) that helps with that logic.
-Your POJO representing an external resource can implement [`ExternalResourceIDProvider`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/ExternalDependentIDProvider.java) : 
+Your POJO representing an external resource can implement [`ResourceIDProvider`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/ResourceIDProvider.java) : 
 
 ```java
 
-public interface ExternalDependentIDProvider<T> {
+public interface ResourceIDProvider<T> {
 
-  T externalResourceId();
+  T resourceId();
 }
 ```
 

docs/content/en/docs/migration/v5-2-migration.md

@@ -0,0 +1,21 @@
+---
+title: Migrating from v5.1 to v5.2
+description: Migrating from v5.1 to v5.2
+---
+
+Version 5.2 brings some breaking changes on some components, for those we provide 
+a migration guide. For all the new features see release notes.
+
+## Custom ID types and ResourceIDProvider across multiple components 
+
+TODO
+
+See also:
+ - related issue: [link](https://github.com/operator-framework/java-operator-sdk/issues/2972)
+ - related pull requests: 
+   - [2970](https://github.com/operator-framework/java-operator-sdk/pull/2970)
+   - [3020](https://github.com/operator-framework/java-operator-sdk/pull/3020)
+
+
+
+

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

@@ -0,0 +1,58 @@
+/*
+ * Copyright Java Operator SDK Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.javaoperatorsdk.operator.processing;
+
+import io.fabric8.kubernetes.api.model.HasMetadata;
+import io.javaoperatorsdk.operator.processing.event.ResourceID;
+import io.javaoperatorsdk.operator.processing.event.source.ExternalResourceCachingEventSource;
+
+/**
+ * Provides id for the target resource. This mapper is used across multiple component of the
+ * framework, like the {@link
+ * io.javaoperatorsdk.operator.processing.dependent.AbstractExternalDependentResource}, in {@link
+ * ExternalResourceCachingEventSource}, and {@link
+ * io.javaoperatorsdk.operator.processing.dependent.KubernetesBulkDependentResource}.
+ */
+public interface ResourceIDMapper<R, ID> {
+
+  ID idFor(R resource);
+
+  /**
+   * Can be used if a polling event source handles only single secondary resource and the id is
+   * String. See also docs for: {@link ExternalResourceCachingEventSource}
+   *
+   * @return static id mapper, all resources are mapped for same id.
+   * @param <R> secondary resource type
+   */
+  static <R> ResourceIDMapper<R, String> singleResourceResourceIDMapper() {
+    return r -> "id";
+  }
+
+  static <R, ID> ResourceIDMapper<R, ID> resourceIdProviderMapper() {
+    return r -> {
+      if (r instanceof ResourceIDProvider resourceIDProvider) {
+        return (ID) resourceIDProvider.resourceId();
+      } else {
+        throw new IllegalStateException(
+            "Resource does not implement ExternalDependentIDProvider: " + r.getClass());
+      }
+    };
+  }
+
+  static <R extends HasMetadata> ResourceIDMapper<R, ResourceID> kubernetesResourceIdMapper() {
+    return ResourceID::fromResource;
+  }
+}

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

@@ -0,0 +1,33 @@
+/*
+ * Copyright Java Operator SDK Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.javaoperatorsdk.operator.processing;
+
+/**
+ * Provides the identifier for an object that represents resource. This ID is used to select target
+ * external resource for a dependent resource from the resources returned by `{@link
+ * io.javaoperatorsdk.operator.api.reconciler.Context#getSecondaryResources(Class)}`. But also for
+ * {@link ResourceIDMapper} for event sources in external resources. But also for bulk dependent
+ * resource see {@link
+ * io.javaoperatorsdk.operator.processing.dependent.ExternalBulkDependentResource} and external
+ * event sources, see {@link
+ * io.javaoperatorsdk.operator.processing.event.source.ExternalResourceCachingEventSource}
+ *
+ * @param <ID>
+ */
+public interface ResourceIDProvider<ID> {
+
+  ID resourceId();
+}

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

@@ -63,7 +63,7 @@ protected AbstractDependentResource(String name) {
 
     dependentResourceReconciler =
         this instanceof BulkDependentResource
-            ? new BulkDependentResourceReconciler<>((BulkDependentResource<R, P>) this)
+            ? new BulkDependentResourceReconciler<>((BulkDependentResource<R, P, ?>) this)
             : new SingleDependentResourceReconciler<>(this);
     this.name = name == null ? DependentResource.defaultNameFor(this.getClass()) : name;
   }

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

@@ -22,19 +22,22 @@
 import io.fabric8.kubernetes.api.model.HasMetadata;
 import io.javaoperatorsdk.operator.api.reconciler.Context;
 import io.javaoperatorsdk.operator.api.reconciler.dependent.RecentOperationCacheFiller;
+import io.javaoperatorsdk.operator.processing.ResourceIDMapper;
 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.informer.InformerEventSource;
 
 public abstract class AbstractExternalDependentResource<
-        R, P extends HasMetadata, T extends EventSource<R, P>>
+        R, P extends HasMetadata, T extends EventSource<R, P>, ID>
     extends AbstractEventSourceHolderDependentResource<R, P, T> {
 
   private final boolean isDependentResourceWithExplicitState =
       this instanceof DependentResourceWithExplicitState;
   private final boolean isBulkDependentResource = this instanceof BulkDependentResource;
 
+  protected ResourceIDMapper<R, ID> resourceIDMapper = ResourceIDMapper.resourceIdProviderMapper();
+
   @SuppressWarnings("rawtypes")
   private DependentResourceWithExplicitState dependentResourceWithExplicitState;
 
@@ -131,24 +134,23 @@ protected Optional<R> selectTargetSecondaryResource(
       Set<R> secondaryResources, P primary, Context<P> context) {
     R desired = desired(primary, context);
     List<R> targetResources;
-    if (desired instanceof ExternalDependentIDProvider<?> desiredWithId) {
-      targetResources =
-          secondaryResources.stream()
-              .filter(
-                  r ->
-                      ((ExternalDependentIDProvider<?>) r)
-                          .externalResourceId()
-                          .equals(desiredWithId.externalResourceId()))
-              .toList();
-    } else {
-      throw new IllegalStateException(
-          "Either implement ExternalDependentIDProvider or override this "
-              + " (selectTargetSecondaryResource) method.");
-    }
+    var desiredID = resourceIDMapper.idFor(desired);
+    targetResources =
+        secondaryResources.stream()
+            .filter(r -> resourceIDMapper.idFor(r).equals(desiredID))
+            .toList();
     if (targetResources.size() > 1) {
       throw new IllegalStateException(
           "More than one secondary resource related to primary: " + targetResources);
     }
     return targetResources.isEmpty() ? Optional.empty() : Optional.of(targetResources.get(0));
   }
+
+  public ResourceIDMapper<R, ID> resourceIDMapper() {
+    return resourceIDMapper;
+  }
+
+  public void setResourceIDMapper(ResourceIDMapper<R, ID> resourceIDMapper) {
+    this.resourceIDMapper = resourceIDMapper;
+  }
 }

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

@@ -27,10 +27,11 @@
  * implementing this interface will typically also implement one or more additional interfaces such
  * as {@link Creator}, {@link Updater}, {@link Deleter}.
  *
+ * @param <ID> type of the id to distinguish resource
  * @param <R> the dependent resource type
  * @param <P> the primary resource type
  */
-public interface BulkDependentResource<R, P extends HasMetadata> {
+public interface BulkDependentResource<R, P extends HasMetadata, ID> {
 
   /**
    * Retrieves a map of desired secondary resources associated with the specified primary resource,
@@ -42,7 +43,7 @@ public interface BulkDependentResource<R, P extends HasMetadata> {
    * @return a Map associating desired secondary resources with the specified primary via arbitrary
    *     identifiers
    */
-  default Map<String, R> desiredResources(P primary, Context<P> context) {
+  default Map<ID, R> desiredResources(P primary, Context<P> context) {
     throw new IllegalStateException(
         "Implement desiredResources in case a non read-only bulk dependent resource");
   }
@@ -57,7 +58,7 @@ default Map<String, R> desiredResources(P primary, Context<P> context) {
    * @return a Map associating actual secondary resources with the specified primary via arbitrary
    *     identifiers
    */
-  Map<String, R> getSecondaryResources(P primary, Context<P> context);
+  Map<ID, R> getSecondaryResources(P primary, Context<P> context);
 
   /**
    * Deletes the actual resource identified by the specified key if it's not in the set of desired
@@ -69,7 +70,7 @@ default Map<String, R> desiredResources(P primary, Context<P> context) {
    * @param key key of the resource
    * @param context actual context
    */
-  void deleteTargetResource(P primary, R resource, String key, Context<P> context);
+  void deleteTargetResource(P primary, R resource, ID key, Context<P> context);
 
   /**
    * Determines whether the specified secondary resource matches the desired state with target index

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

@@ -29,19 +29,19 @@
 import io.javaoperatorsdk.operator.api.reconciler.dependent.ReconcileResult;
 import io.javaoperatorsdk.operator.processing.dependent.Matcher.Result;
 
-class BulkDependentResourceReconciler<R, P extends HasMetadata>
+class BulkDependentResourceReconciler<R, P extends HasMetadata, ID>
     implements DependentResourceReconciler<R, P> {
 
-  private final BulkDependentResource<R, P> bulkDependentResource;
+  private final BulkDependentResource<R, P, ID> bulkDependentResource;
 
-  BulkDependentResourceReconciler(BulkDependentResource<R, P> bulkDependentResource) {
+  BulkDependentResourceReconciler(BulkDependentResource<R, P, ID> bulkDependentResource) {
     this.bulkDependentResource = bulkDependentResource;
   }
 
   @Override
   public ReconcileResult<R> reconcile(P primary, Context<P> context) {
 
-    Map<String, R> actualResources = bulkDependentResource.getSecondaryResources(primary, context);
+    Map<ID, R> actualResources = bulkDependentResource.getSecondaryResources(primary, context);
     if (!(bulkDependentResource instanceof Creator<?, ?>)
         && !(bulkDependentResource instanceof Deleter<?>)
         && !(bulkDependentResource instanceof Updater<?, ?>)) {
@@ -73,7 +73,7 @@ public void delete(P primary, Context<P> context) {
   }
 
   private void deleteExtraResources(
-      Set<String> expectedKeys, Map<String, R> actualResources, P primary, Context<P> context) {
+      Set<ID> expectedKeys, Map<ID, R> actualResources, P primary, Context<P> context) {
     actualResources.forEach(
         (key, value) -> {
           if (!expectedKeys.contains(key)) {
@@ -90,13 +90,13 @@ private void deleteExtraResources(
    * @param <P>
    */
   @Ignore
-  private static class BulkDependentResourceInstance<R, P extends HasMetadata>
+  private static class BulkDependentResourceInstance<R, P extends HasMetadata, ID>
       extends AbstractDependentResource<R, P> implements Creator<R, P>, Deleter<P>, Updater<R, P> {
-    private final BulkDependentResource<R, P> bulkDependentResource;
+    private final BulkDependentResource<R, P, ID> bulkDependentResource;
     private final R desired;
 
     private BulkDependentResourceInstance(
-        BulkDependentResource<R, P> bulkDependentResource, R desired) {
+        BulkDependentResource<R, P, ID> bulkDependentResource, R desired) {
       this.bulkDependentResource = bulkDependentResource;
       this.desired = desired;
     }

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

@@ -18,5 +18,5 @@
 import io.fabric8.kubernetes.api.model.HasMetadata;
 import io.javaoperatorsdk.operator.api.reconciler.dependent.Deleter;
 
-public interface CRUDBulkDependentResource<R, P extends HasMetadata>
-    extends BulkDependentResource<R, P>, Creator<R, P>, BulkUpdater<R, P>, Deleter<P> {}
+public interface CRUDBulkDependentResource<R, P extends HasMetadata, ID>
+    extends BulkDependentResource<R, P, ID>, Creator<R, P>, BulkUpdater<R, P>, Deleter<P> {}

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/CacheKeyMapper.java → operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/CRUDExternalBulkDependentResource.java

@@ -13,20 +13,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package io.javaoperatorsdk.operator.processing.event.source;
+package io.javaoperatorsdk.operator.processing.dependent;
 
-public interface CacheKeyMapper<R> {
+import io.fabric8.kubernetes.api.model.HasMetadata;
+import io.javaoperatorsdk.operator.api.reconciler.dependent.Deleter;
+import io.javaoperatorsdk.operator.processing.ResourceIDProvider;
 
-  String keyFor(R resource);
-
-  /**
-   * Used if a polling event source handles only single secondary resource. See also docs for:
-   * {@link ExternalResourceCachingEventSource}
-   *
-   * @return static id mapper, all resources are mapped for same id.
-   * @param <T> secondary resource type
-   */
-  static <T> CacheKeyMapper<T> singleResourceCacheKeyMapper() {
-    return r -> "id";
-  }
-}
+public interface CRUDExternalBulkDependentResource<
+        R extends ResourceIDProvider<ID>, P extends HasMetadata, ID>
+    extends ExternalBulkDependentResource<R, P, ID>, Creator<R, P>, BulkUpdater<R, P>, Deleter<P> {}

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/ExternalDependentIDProvider.java → operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/CRUDKubernetesBulkDependentResource.java

@@ -15,14 +15,9 @@
  */
 package io.javaoperatorsdk.operator.processing.dependent;
 
-/**
- * Provides the identifier for an object that represents an external resource. This ID is used to
- * select target resource for a dependent resource from the resources returned by `{@link
- * io.javaoperatorsdk.operator.api.reconciler.Context#getSecondaryResources(Class)}`.
- *
- * @param <T>
- */
-public interface ExternalDependentIDProvider<T> {
+import io.fabric8.kubernetes.api.model.HasMetadata;
+import io.javaoperatorsdk.operator.api.reconciler.dependent.Deleter;
+import io.javaoperatorsdk.operator.processing.event.ResourceID;
 
-  T externalResourceId();
-}
+public interface CRUDKubernetesBulkDependentResource<R, P extends HasMetadata>
+    extends BulkDependentResource<R, P, ResourceID>, Creator<R, P>, BulkUpdater<R, P>, Deleter<P> {}

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

@@ -0,0 +1,33 @@
+/*
+ * Copyright Java Operator SDK Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.javaoperatorsdk.operator.processing.dependent;
+
+import io.fabric8.kubernetes.api.model.HasMetadata;
+import io.javaoperatorsdk.operator.processing.ResourceIDMapper;
+import io.javaoperatorsdk.operator.processing.ResourceIDProvider;
+
+/**
+ * Specialized interface for bulk dependent resources where resource implement {@link
+ * ResourceIDProvider}.
+ */
+public interface ExternalBulkDependentResource<
+        R extends ResourceIDProvider<ID>, P extends HasMetadata, ID>
+    extends ResourceIDMapperBulkDependentResource<R, P, ID> {
+
+  default ResourceIDMapper<R, ID> resourceIDMapper() {
+    return ResourceIDMapper.resourceIdProviderMapper();
+  }
+}