wip

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

Author: csviri

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

@@ -24,9 +24,22 @@
 @SuppressWarnings("unchecked")
 public interface ResourceCache<T extends HasMetadata> extends Cache<T> {
 
+  /**
+   * Lists all resources in the given namespace.
+   *
+   * @param namespace the namespace to list resources from
+   * @return a stream of all cached resources in the namespace
+   */
   default Stream<T> list(String namespace) {
     return list(namespace, TRUE);
   }
 
+  /**
+   * Lists resources in the given namespace that match the provided predicate.
+   *
+   * @param namespace the namespace to list resources from
+   * @param predicate filter to apply on the resources
+   * @return a stream of cached resources matching the predicate
+   */
   Stream<T> list(String namespace, Predicate<T> predicate);
 }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/Cache.java

@@ -25,17 +25,45 @@
 public interface Cache<T> {
   Predicate TRUE = (a) -> true;
 
+  /**
+   * Retrieves a resource from the cache by its {@link ResourceID}.
+   *
+   * @param resourceID the identifier of the resource
+   * @return an optional containing the resource if present in the cache
+   */
   Optional<T> get(ResourceID resourceID);
 
+  /**
+   * Checks whether a resource with the given {@link ResourceID} exists in the cache.
+   *
+   * @param resourceID the identifier of the resource
+   * @return {@code true} if the resource is present in the cache
+   */
   default boolean contains(ResourceID resourceID) {
     return get(resourceID).isPresent();
   }
 
+  /**
+   * Returns a stream of all {@link ResourceID}s currently in the cache.
+   *
+   * @return a stream of resource identifiers
+   */
   Stream<ResourceID> keys();
 
+  /**
+   * Lists all resources in the cache.
+   *
+   * @return a stream of all cached resources
+   */
   default Stream<T> list() {
     return list(TRUE);
   }
 
+  /**
+   * Lists resources in the cache that match the provided predicate.
+   *
+   * @param predicate filter to apply on the resources
+   * @return a stream of cached resources matching the predicate
+   */
   Stream<T> list(Predicate<T> predicate);
 }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/ManagedInformerEventSource.java

@@ -234,23 +234,47 @@ public void addIndexers(Map<String, Function<R, List<String>>> indexers) {
     this.indexers.putAll(indexers);
   }
 
+  /**
+   * {@inheritDoc}
+   *
+   * <p>This implementation is read-cache-after-write consistent. Results are merged with the
+   * temporary resource cache to ensure recently written resources are reflected in the output.
+   */
   @Override
   public Stream<R> list(String namespace, Predicate<R> predicate) {
     return mergeWithWithTempCacheResources(
         manager().list(namespace, predicate), namespace, predicate);
   }
 
+  /**
+   * {@inheritDoc}
+   *
+   * <p>This implementation is read-cache-after-write consistent. Results are merged with the
+   * temporary resource cache to ensure recently written resources are reflected in the output.
+   */
   @Override
   public Stream<R> list(Predicate<R> predicate) {
     return mergeWithWithTempCacheResources(cache.list(predicate), null, predicate);
   }
 
+  /**
+   * {@inheritDoc}
+   *
+   * <p>This implementation is read-cache-after-write consistent. Results are merged with the
+   * temporary resource cache to ensure recently written resources are reflected in the output.
+   */
   @Override
   public Stream<R> byIndexStream(String indexName, String indexKey) {
     return mergeWithWithTempCacheResources(
         manager().byIndexStream(indexName, indexKey), indexName, indexKey);
   }
 
+  /**
+   * {@inheritDoc}
+   *
+   * <p>This implementation is read-cache-after-write consistent. Results are merged with the
+   * temporary resource cache to ensure recently written resources are reflected in the output.
+   */
   @Override
   public List<R> byIndex(String indexName, String indexKey) {
     return mergeWithWithTempCacheResources(