migration guide

Signed-off-by: Attila Mészáros <[email protected]>

Author: csviri

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

@@ -6,9 +6,32 @@ 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
+## Custom ID types across multiple components using ResourceIDMapper and ResourceIDProvider 
+
+Working with an id of a resource is needed across various component in the framework. 
+Until this version the components provided by the framework assumed that you can easily
+convert an id of the resource into String representation. So for example 
+[BulkDependentResources](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/BulkDependentResource.java#L46)
+worked with a `Map<String,R>` of resources, where id was always type of String. 
+
+Mainly because of the need to manage external dependent resources more elegantly
+we introduced a cross-cutting concept: [`ResourceIDMapper`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/ResourceIDMapper.java).
+That gets the ID of a resource. This is used then across various components, see:
+
+ - [`ExternalResourceCachingEventSource`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/ExternalResourceCachingEventSource.java#L66)
+ - [`ExternalBulkDependentResource`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/ExternalBulkDependentResource.java)
+ - [`AbstractExternalDependentResource`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/AbstractExternalDependentResource.java#L39)
+   and it's subclasses.
+   
+We also added [`ResourceIDProvider`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/ResourceIDProvider.java) 
+that you can implement into you Pojo representing a resource. 
+
+The easiest way to migrate to this new approach is to implement this interface for your (external) resource,
+and set the ID type generics for the components above. The default implementation of the `ResourceIDMapper` 
+works with `ResourceIDProvider` see [related implementation](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/ResourceIDMapper.java#L52).
+
+If you cannot implement `ResourceIDProvider` because for example the class that represents the external resource is generated and final,
+you can always set a custom `ResourceIDMapper` on the components above.
 
 See also:
  - related issue: [link](https://github.com/operator-framework/java-operator-sdk/issues/2972)

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

@@ -20,6 +20,7 @@
 import io.fabric8.kubernetes.api.model.HasMetadata;
 import io.javaoperatorsdk.operator.api.reconciler.EventSourceContext;
 import io.javaoperatorsdk.operator.api.reconciler.Ignore;
+import io.javaoperatorsdk.operator.processing.ResourceIDMapper;
 import io.javaoperatorsdk.operator.processing.event.source.ExternalResourceCachingEventSource;
 import io.javaoperatorsdk.operator.processing.event.source.polling.PerResourcePollingConfigurationBuilder;
 import io.javaoperatorsdk.operator.processing.event.source.polling.PerResourcePollingEventSource;
@@ -29,14 +30,26 @@ public abstract class PerResourcePollingDependentResource<R, P extends HasMetada
     extends AbstractPollingDependentResource<R, P, ID>
     implements PerResourcePollingEventSource.ResourceFetcher<R, P> {
 
-  public PerResourcePollingDependentResource() {}
+  protected PerResourcePollingDependentResource() {}
 
-  public PerResourcePollingDependentResource(Class<R> resourceType) {
+  protected PerResourcePollingDependentResource(
+      Class<R> resourceType, ResourceIDMapper<R, ID> resourceIDMapper) {
     super(resourceType);
+    setResourceIDMapper(resourceIDMapper);
   }
 
-  public PerResourcePollingDependentResource(Class<R> resourceType, Duration pollingPeriod) {
+  protected PerResourcePollingDependentResource(Class<R> resourceType) {
+    super(resourceType);
+  }
+
+  protected PerResourcePollingDependentResource(Class<R> resourceType, Duration pollingPeriod) {
+    super(resourceType, pollingPeriod);
+  }
+
+  protected PerResourcePollingDependentResource(
+      Class<R> resourceType, Duration pollingPeriod, ResourceIDMapper<R, ID> resourceIDMapper) {
     super(resourceType, pollingPeriod);
+    setResourceIDMapper(resourceIDMapper);
   }
 
   @Override

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

@@ -30,17 +30,24 @@ public abstract class PollingDependentResource<R, P extends HasMetadata, ID>
     extends AbstractPollingDependentResource<R, P, ID>
     implements PollingEventSource.GenericResourceFetcher<R> {
 
-  private final ResourceIDMapper<R, ID> resourceIDMapper;
+  protected PollingDependentResource(Class<R> resourceType) {
+    super(resourceType);
+  }
 
-  public PollingDependentResource(Class<R> resourceType, ResourceIDMapper<R, ID> resourceIDMapper) {
+  protected PollingDependentResource(
+      Class<R> resourceType, ResourceIDMapper<R, ID> resourceIDMapper) {
     super(resourceType);
-    this.resourceIDMapper = resourceIDMapper;
+    setResourceIDMapper(resourceIDMapper);
+  }
+
+  protected PollingDependentResource(Class<R> resourceType, Duration pollingPeriod) {
+    super(resourceType, pollingPeriod);
   }
 
-  public PollingDependentResource(
+  protected PollingDependentResource(
       Class<R> resourceType, Duration pollingPeriod, ResourceIDMapper<R, ID> resourceIDMapper) {
     super(resourceType, pollingPeriod);
-    this.resourceIDMapper = resourceIDMapper;
+    setResourceIDMapper(resourceIDMapper);
   }
 
   @Override