Core: Deprecate ContentCache.invalidateAll (apache#10494)

* Deprecate ContentCache.invalidateAll

This method does only best-effort invalidation and is susceptible to a
race condition. If the caller changed the state that could be cached
(perhaps files on the storage) and calls this method, there is no
guarantee that the cache will not contain stale entries some time after
this method returns. This is a similar problem as the one described at
google/guava#1881. `ContentCache` doesn't use
a Guava Cache, it uses Caffeine. Caffeine offers partial solution to
this issue, but not for `invalidateAll` call.  To avoid accidental
incorrect use of ContentCache, deprecate the `invalidateAll` method,
which can be deceptive for the caller and remove it later.

* Document ContentCache.invalidate blocking nature

* empty

Author: findepi

core/src/main/java/org/apache/iceberg/io/ContentCache.java

@@ -129,10 +129,23 @@ public InputFile tryCache(InputFile input) {
     return input;
   }
 
+  /**
+   * Invalidate the cache entry for the given key.
+   *
+   * <p>Note: if there is ongoing load, this is a blocking operation, i.e. it will wait for the load
+   * to complete before invalidating the entry.
+   */
   public void invalidate(String key) {
     cache.invalidate(key);
   }
 
+  /**
+   * @deprecated since 1.6.0, will be removed in 1.7.0; This method does only best-effort
+   *     invalidation and is susceptible to a race condition. If the caller changed the state that
+   *     could be cached (perhaps files on the storage) and calls this method, there is no guarantee
+   *     that the cache will not contain stale entries some time after this method returns.
+   */
+  @Deprecated
   public void invalidateAll() {
     cache.invalidateAll();
   }