Jules was unable to complete the task in time. Please review the work done so far and provide feedback for Jules to continue.

Author: google-labs-jules[bot]

commons/src/main/java/org/restheart/cache/Cache.java

@@ -23,30 +23,78 @@
 import java.util.Optional;
 
 /**
+ * A generic cache interface that defines common caching operations.
  *
  * @author Andrea Di Cesare {@literal <andrea@softinstigate.com>}
- * @param <K> the class of the keys
- * @param <V> the class of the values
+ * @param <K> the type of keys maintained by this cache
+ * @param <V> the type of mapped values
  */
 public interface Cache<K, V> {
+    /**
+     * Defines the expiration policies for cache entries.
+     */
     public enum EXPIRE_POLICY {
-        NEVER, AFTER_WRITE, AFTER_READ
+        /** Cache entries never expire. */
+        NEVER,
+        /** Cache entries expire after a fixed duration an entry is written. */
+        AFTER_WRITE,
+        /** Cache entries expire after a fixed duration an entry is accessed. */
+        AFTER_READ
     }
 
+    /**
+     * Returns the value associated with the specified key, or {@code Optional.empty()}
+     * if there is no cached value for the key.
+     *
+     * @param key the key whose associated value is to be returned
+     * @return an {@code Optional} containing the value associated with the key,
+     *         or {@code Optional.empty()} if no mapping for the key exists
+     */
     public Optional<V> get(K key);
 
+    /**
+     * Removes the mapping for a key from this cache if it is present.
+     *
+     * @param key the key whose mapping is to be removed from the cache
+     * @return an {@code Optional} containing the previous value associated with the key,
+     *         or {@code Optional.empty()} if there was no mapping for the key.
+     */
     public Optional<V> remove(K key);
 
+    /**
+     * Associates the specified value with the specified key in this cache.
+     * If the cache previously contained a mapping for the key, the old
+     * value is replaced by the specified value.
+     *
+     * @param key   the key with which the specified value is to be associated
+     * @param value the value to be associated with the specified key
+     */
     public void put(K key, V value);
 
     /**
      * Performs any pending maintenance operations needed by the cache.
+     * This might include tasks like eviction of expired entries.
      */
     public void cleanUp();
 
+    /**
+     * Invalidates the cache entry associated with the specified key.
+     *
+     * @param key the key to invalidate
+     */
     public void invalidate(K key);
 
+    /**
+     * Invalidates all entries in this cache.
+     */
     public void invalidateAll();
 
+    /**
+     * Returns a view of the entries stored in this cache as a {@code Map}.
+     * Modifications to the returned map may or may not be reflected in the cache,
+     * depending on the cache implementation.
+     *
+     * @return a map view of the cache
+     */
     public Map<K, Optional<V>> asMap();
 }

commons/src/main/java/org/restheart/cache/CacheFactory.java

@@ -28,61 +28,78 @@
 import org.restheart.cache.impl.HashMapLoadingCache;
 
 /**
+ * A factory class for creating {@link Cache} and {@link LoadingCache} instances.
+ * This factory provides methods to create different cache implementations,
+ * such as Caffeine-based caches and HashMap-based loading caches.
  *
  * @author Andrea Di Cesare {@literal <andrea@softinstigate.com>}
  */
 public class CacheFactory {
     /**
+     * Creates a new Caffeine-based {@link LoadingCache} with the specified configuration.
      *
      * @param <K>          the type of the cache keys
      * @param <V>          the type of the cached values
-     * @param size         the size of the cache
-     * @param expirePolicy specifies how and when each entry should be automatically
-     *                     removed from the cache
-     * @param ttl          Time To Live in milliseconds
-     * @param loader       the cache loader used to obtain new values
-     * @return the cache
+     * @param size         the maximum number of entries the cache can hold
+     * @param expirePolicy the policy that specifies how and when each entry
+     *                     should be automatically removed from the cache
+     * @param ttl          the Time To Live (TTL) for cache entries in milliseconds
+     * @param loader       the function used to load values for keys that are not
+     *                     already in the cache
+     * @return a new {@link LoadingCache} instance configured as specified
      */
     public static <K, V> LoadingCache<K, V> createLocalLoadingCache(long size, Cache.EXPIRE_POLICY expirePolicy, long ttl, Function<K, V> loader) {
         return new CaffeineLoadingCache<>(size, expirePolicy, ttl, loader);
     }
 
     /**
+     * Creates a new HashMap-based {@link LoadingCache}.
+     * This cache does not have a size limit or expiration policy.
+     *
      * @param <K>    the type of the cache keys
      * @param <V>    the type of the cached values
-     * @param loader the cache loader used to obtain new values
-     * @return the cache
+     * @param loader the function used to load values for keys that are not
+     *               already in the cache
+     * @return a new {@link LoadingCache} instance using a HashMap backend
      */
     public static <K, V> LoadingCache<K, V> createHashMapLoadingCache(Function<K, V> loader) {
         return new HashMapLoadingCache<>(loader);
     }
 
     /**
+     * Creates a new Caffeine-based {@link Cache} with the specified configuration.
      *
-     * @param <K> the type of the cache keys
-     * @param <V> the type of the cached values
-     * @param size the size of the cache
-     * @param expirePolicy specifies how and when each entry should be automatically removed from the cache
-     * @param ttl Time To Live in milliseconds
-     * @return the cache.
+     * @param <K>          the type of the cache keys
+     * @param <V>          the type of the cached values
+     * @param size         the maximum number of entries the cache can hold
+     * @param expirePolicy the policy that specifies how and when each entry
+     *                     should be automatically removed from the cache
+     * @param ttl          the Time To Live (TTL) for cache entries in milliseconds
+     * @return a new {@link Cache} instance configured as specified
     */
     public static <K,V> Cache<K,V> createLocalCache(long size, Cache.EXPIRE_POLICY expirePolicy, long ttl) {
         return new CaffeineCache<>(size, expirePolicy, ttl);
     }
+
     /**
+     * Creates a new Caffeine-based {@link Cache} with the specified configuration,
+     * including a custom removal listener.
      *
-     * @param <K> the type of the cache keys.
-     * @param <V> the type of the cached values.
-     * @param size the size of the cache.
-     * @param expirePolicy specifies how and when each entry should be automatically removed from the cache.
-     * @param ttl Time To Live in milliseconds.
-     * @param remover the cache remover to invoke each time a value is automatically removed from the cache according to the expire xpolicy
-     * @return the cache.
+     * @param <K>          the type of the cache keys
+     * @param <V>          the type of the cached values
+     * @param size         the maximum number of entries the cache can hold
+     * @param expirePolicy the policy that specifies how and when each entry
+     *                     should be automatically removed from the cache
+     * @param ttl          the Time To Live (TTL) for cache entries in milliseconds
+     * @param remover      a {@link Consumer} that is invoked when an entry is removed
+     *                     from the cache due to expiration or eviction
+     * @return a new {@link Cache} instance configured as specified
     */
     public static <K,V> Cache<K,V> createLocalCache(long size, Cache.EXPIRE_POLICY expirePolicy, long ttl, Consumer<Map.Entry<K, Optional<V>>> remover) {
         return new CaffeineCache<>(size, expirePolicy, ttl, remover);
     }
 
     private CacheFactory() {
+        // Prevent instantiation
     }
 }

commons/src/main/java/org/restheart/cache/LoadingCache.java

@@ -22,11 +22,27 @@
 import java.util.Optional;
 
 /**
+ * A {@link Cache} that supports atomic computation of values for keys that are
+ * not already in the cache. This interface extends the basic {@link Cache}
+ * interface by adding a method to retrieve a value, loading it if necessary.
  *
  * @author Andrea Di Cesare {@literal <andrea@softinstigate.com>}
- * @param <K> the class of the keys
- * @param <V> the class of the values
+ * @param <K> the type of keys maintained by this cache
+ * @param <V> the type of mapped values
  */
 public interface LoadingCache<K,V> extends Cache<K,V> {
+    /**
+     * Returns the value associated with the specified key.
+     * If the key is not already in the cache, this method will attempt to load
+     * the value using the cache's configured loader. If the value is successfully
+     * loaded, it will be stored in the cache and returned.
+     * <p>
+     * If the loading process fails or returns null, this method will return
+     * {@code Optional.empty()} and no mapping will be stored in the cache.
+     *
+     * @param key the key whose associated value is to be returned or loaded
+     * @return an {@code Optional} containing the value associated with the key,
+     *         or {@code Optional.empty()} if the key is not found or loading fails
+     */
     public Optional<V> getLoading(K key);
 }

commons/src/main/java/org/restheart/cache/impl/CaffeineCache.java

@@ -35,15 +35,30 @@
 import com.github.benmanes.caffeine.cache.RemovalCause;
 
 /**
+ * A {@link org.restheart.cache.Cache} implementation backed by a
+ * <a href="https://github.com/ben-manes/caffeine">Caffeine</a> cache.
+ * This class wraps a Caffeine cache instance and adapts it to the
+ * {@code org.restheart.cache.Cache} interface.
+ * <p>
+ * Values are stored as {@code Optional<V>} to allow caching of null values.
  *
  * @author Andrea Di Cesare {@literal <andrea@softinstigate.com>}
- * @param <K> the class of the keys.
- * @param <V> the class of the values (is Optional-ized).
+ * @param <K> the type of keys maintained by this cache
+ * @param <V> the type of mapped values
  */
 public class CaffeineCache<K, V> implements org.restheart.cache.Cache<K, V> {
     private static final Executor virtualThreadsExecutor = ThreadsUtils.virtualThreadsExecutor();
     private final Cache<K, Optional<V>> wrapped;
 
+    /**
+     * Constructs a new {@code CaffeineCache} with the specified configuration.
+     *
+     * @param size         the maximum number of entries the cache can hold
+     * @param expirePolicy the policy that specifies how and when each entry
+     *                     should be automatically removed from the cache
+     * @param ttl          the Time To Live (TTL) for cache entries in milliseconds.
+     *                     If zero or negative, entries do not expire based on time.
+     */
     public CaffeineCache(long size, EXPIRE_POLICY expirePolicy, long ttl) {
         var builder = Caffeine.newBuilder().executor(virtualThreadsExecutor);
 
@@ -58,6 +73,20 @@ public CaffeineCache(long size, EXPIRE_POLICY expirePolicy, long ttl) {
         wrapped = builder.build();
     }
 
+    /**
+     * Constructs a new {@code CaffeineCache} with the specified configuration,
+     * including a custom removal listener.
+     *
+     * @param size         the maximum number of entries the cache can hold
+     * @param expirePolicy the policy that specifies how and when each entry
+     *                     should be automatically removed from the cache
+     * @param ttl          the Time To Live (TTL) for cache entries in milliseconds.
+     *                     If zero or negative, entries do not expire based on time.
+     * @param remover      a {@link Consumer} that is invoked when an entry is
+     *                     removed from the cache due to expiration or eviction.
+     *                     The entry passed to the consumer contains the key and the
+     *                     {@code Optional<V>} value.
+     */
     public CaffeineCache(long size, EXPIRE_POLICY expirePolicy, long ttl, Consumer<Map.Entry<K, Optional<V>>> remover) {
         var builder = Caffeine.newBuilder().executor(virtualThreadsExecutor);
 
@@ -75,38 +104,59 @@ public CaffeineCache(long size, EXPIRE_POLICY expirePolicy, long ttl, Consumer<M
         }).build();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public Optional<V> get(K key) {
         return wrapped.getIfPresent(key);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public synchronized Optional<V> remove(K key) {
         var ret = wrapped.getIfPresent(key);
         wrapped.invalidate(key);
         return ret;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public void put(K key, V value) {
         wrapped.put(key, Optional.ofNullable(value));
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public void invalidate(K key) {
         wrapped.invalidate(key);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public void invalidateAll() {
         wrapped.invalidateAll();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public Map<K, Optional<V>> asMap() {
         return wrapped.asMap();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public void cleanUp() {
         wrapped.cleanUp();