rename to blocklist, added javadocs

Signed-off-by: Attila Mészáros <a_meszaros@apple.com>

Author: csviri

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java

@@ -452,7 +452,22 @@ default boolean previousAnnotationForDependentResourcesEventFiltering() {
     return true;
   }
 
-  default List<Class<? extends HasMetadata>> previousAnnotationUsageBlacklist() {
+  /**
+   * For dependent resources framework can add an annotation to filter our events that are results
+   * of changes made by the framework. There are, however, few resources that do not follow the K8S
+   * API convention that changes in metadata do not increase the "metadata.generation". For these
+   * resources, the generation is increased by adding the annotation and their controller increases
+   * the observedGeneration in the status. This results in a new event, that if not handled
+   * correctly with the resource matcher yet again results in an update and a previous version
+   * annotation change, thus results in an infinite loop.
+   *
+   * <p>As a workaround, we automatically skip adding previous annotation for those well-known
+   * resources. Note that if you are sure that the matcher works (most of the cases does) for your
+   * case, you can remove the resource from the blocklist.
+   *
+   * @return blocklist of resource classes where the previous version annotation won't be used.
+   */
+  default List<Class<? extends HasMetadata>> previousAnnotationUsageBlocklist() {
     return List.of(Deployment.class, StatefulSet.class, ReplicaSet.class);
   }
 

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationServiceOverrider.java

@@ -41,7 +41,7 @@ public class ConfigurationServiceOverrider {
   private Boolean parseResourceVersions;
   private Boolean useSSAToPatchPrimaryResource;
   private Boolean cloneSecondaryResourcesWhenGettingFromCache;
-  private List<Class<? extends HasMetadata>> previousAnnotationUsageBlacklist;
+  private List<Class<? extends HasMetadata>> previousAnnotationUsageBlocklist;
 
   @SuppressWarnings("rawtypes")
   private DependentResourceFactory dependentResourceFactory;
@@ -190,9 +190,9 @@ public ConfigurationServiceOverrider withCloneSecondaryResourcesWhenGettingFromC
     return this;
   }
 
-  public ConfigurationServiceOverrider previousAnnotationUsageBlacklist(
+  public ConfigurationServiceOverrider previousAnnotationUsageBlocklist(
       List<Class<? extends HasMetadata>> previousAnnotationUsageBlacklist) {
-    this.previousAnnotationUsageBlacklist = previousAnnotationUsageBlacklist;
+    this.previousAnnotationUsageBlocklist = previousAnnotationUsageBlacklist;
     return this;
   }
 
@@ -338,10 +338,10 @@ public boolean cloneSecondaryResourcesWhenGettingFromCache() {
       }
 
       @Override
-      public List<Class<? extends HasMetadata>> previousAnnotationUsageBlacklist() {
+      public List<Class<? extends HasMetadata>> previousAnnotationUsageBlocklist() {
         return overriddenValueOrDefault(
-            previousAnnotationUsageBlacklist,
-            ConfigurationService::previousAnnotationUsageBlacklist);
+            previousAnnotationUsageBlocklist,
+            ConfigurationService::previousAnnotationUsageBlocklist);
       }
     };
   }

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

@@ -170,7 +170,7 @@ private boolean usePreviousAnnotation(Context<P> context) {
               && !context
                   .getControllerConfiguration()
                   .getConfigurationService()
-                  .previousAnnotationUsageBlacklist()
+                  .previousAnnotationUsageBlocklist()
                   .contains(this.resourceType());
     }
     return usePreviousAnnotationForEventFiltering;