docs: add javadoc and elaborate on discrimination of secondary resources

Signed-off-by: Chris Laprun <claprun@redhat.com>

Author: metacosm

docs/documentation/dependent-resources.md

@@ -388,11 +388,14 @@ tests [here](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/op
 
 When dealing with multiple dependent resources of same type, the dependent resource implementation
 needs to know which specific resource should be targeted when reconciling a given dependent
-resource, since there will be multiple instances of that type which could possibly be used, each
-associated with the same primary resource. The target resource is computed and selected based on 
-desired state automatically.
-
-Formally there were resource discriminators used for this purpose, still present for backwards compatibility:
+resource, since there could be multiple instances of that type which could possibly be used, each
+associated with the same primary resource. In this situation, JOSDK automatically selects the appropriate secondary
+resource which matches the desired state associated with the primary resource. This makes sense because the desired
+state computation already needs to be able to discriminate among multiple related secondary resources to tell JOSDK how
+they should be reconciled.
+
+However, it is also possible to be more explicit about how JOSDK should identify the proper secondary resource by using
+a
 [resource discriminator](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ResourceDiscriminator.java)
 Resource discriminators uniquely identify the target resource of a dependent resource.
 In the managed Kubernetes dependent resources case, the discriminator can be declaratively set
@@ -405,7 +408,9 @@ public class MultipleManagedDependentResourceConfigMap1 {
 //...
 }
 ```
-Resource discriminators still can be used. But might be removed in the future releases.
+
+While using the automated mechanism should work well in most cases, resource discriminators might make sense for
+optimization purposes, especially when computing the desired state is costly.
 
 ### Sharing an Event Source Between Dependent Resources
 

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

@@ -49,6 +49,16 @@ default Optional<? extends ResourceEventSource<R, P>> eventSource(
     return Optional.empty();
   }
 
+  /**
+   * Retrieves the secondary resource (if it exists) associated with the specified primary resource
+   * for this DependentResource.
+   *
+   * @param primary the primary resource for which we want to retrieve the secondary resource
+   *        associated with this DependentResource
+   * @param context the current {@link Context} in which the operation is called
+   * @return the secondary resource or {@link Optional#empty()} if it doesn't exist
+   * @throws IllegalStateException if more than one secondary is found to match the primary resource
+   */
   default Optional<R> getSecondaryResource(P primary, Context<P> context) {
     return Optional.empty();
   }

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

@@ -104,11 +104,25 @@ public Optional<R> getSecondaryResource(P primary, Context<P> context) {
     }
   }
 
+  /**
+   * Selects the actual secondary resource matching the desired state derived from the primary
+   * resource when several resources of the same type are found in the context. This method allows
+   * for optimized implementations in subclasses since this default implementation will check each
+   * secondary candidates for equality with the specified desired state, which might end up costly.
+   *
+   * @param secondaryResources a Set of potential candidates of the looked for resource type
+   * @param desired the desired state that the matching secondary resource must have to match the
+   *        primary resource
+   * @return the matching secondary resource or {@link Optional#empty()} if none matches
+   * @throws IllegalStateException if more than one candidate is found, in which case some other
+   *         mechanism might be necessary to distinguish between candidate secondary resources
+   */
   protected Optional<R> selectSecondaryBasedOnDesiredState(Set<R> secondaryResources, R desired) {
     var targetResources =
         secondaryResources.stream().filter(r -> r.equals(desired)).collect(Collectors.toList());
     if (targetResources.size() > 1) {
-      throw new IllegalStateException("More than 1 secondary resource related to primary");
+      throw new IllegalStateException(
+          "More than one secondary resource related to primary: " + targetResources);
     }
     return targetResources.isEmpty() ? Optional.empty() : Optional.of(targetResources.get(0));
   }
@@ -178,8 +192,7 @@ protected void handleDelete(P primary, R secondary, Context<P> context) {
         "handleDelete method must be implemented if Deleter trait is supported");
   }
 
-  public void setResourceDiscriminator(
-      ResourceDiscriminator<R, P> resourceDiscriminator) {
+  public void setResourceDiscriminator(ResourceDiscriminator<R, P> resourceDiscriminator) {
     this.resourceDiscriminator = resourceDiscriminator;
   }