Mutability or deepcopy requirements on interface javadocs

[wylswz]

Do you think it is helpful to have documentations of whether resource object accepted or returned by interfaces should be deep copied?

For instance,

public interface BulkDependentResource<R, P extends HasMetadata>
    extends Creator<R, P>, Deleter<P> {
  /**
   * Retrieves a map of desired secondary resources associated with the specified primary resource,
   * identified by an arbitrary key.
   *
   * @param primary the primary resource with which we want to identify which secondary resources
   *        are associated
   * @param context the {@link Context} associated with the current reconciliation
   * @return a Map associating desired secondary resources with the specified primary via arbitrary
   *         identifiers
   */
  // currently the implementers have no idea about whether P primary should be copied before being mutated
  // or R shoud be copied before being returned without reading invokers of this interface
  Map<String, R> desiredResources(P primary, Context<P> context);
}

[metacosm]

Yes, it might indeed be helpful. In the case of the desired methods, though, the intent is to compute a desired state based on data from the primary, and therefore the primary resource shouldn't be modified at all, just read from.

[csviri]

Yes, so note that prior v5 when accessing the resources through context, it was automatically cloned. From v5 this it is not, but can be turned on. For SSA it is anyways natural to not modify an object, but to construct a new one (actually it is quite natural when some thinks in desired state to construct (usually) from the primary.

[csviri]

see also: https://javaoperatorsdk.io/blog/2024/12/06/version-5-released-beta1/#cloning-accessing-secondary-resources