Added javadoc for new files/packages

Signed-off-by: Sagar Upadhyaya <sagar.upadhyaya.121@gmail.com>

server/src/main/java/org/opensearch/common/cache/RemovalNotification.java

@@ -32,7 +32,7 @@
 
 package org.opensearch.common.cache;
 
-import org.opensearch.indices.TierType;
+import org.opensearch.common.cache.tier.TierType;
 
 /**
  * Notification when an element is removed from the cache

server/src/main/java/org/opensearch/indices/CachingTier.java → server/src/main/java/org/opensearch/common/cache/tier/CachingTier.java

@@ -6,7 +6,7 @@
  * compatible open source license.
  */
 
-package org.opensearch.indices;
+package org.opensearch.common.cache.tier;
 
 import org.opensearch.common.cache.RemovalListener;
 

server/src/main/java/org/opensearch/indices/DiskCachingTier.java → server/src/main/java/org/opensearch/common/cache/tier/DiskCachingTier.java

@@ -6,7 +6,7 @@
  * compatible open source license.
  */
 
-package org.opensearch.indices;
+package org.opensearch.common.cache.tier;
 
 /**
  * This is specific to disk caching tier and can be used to add methods which are specific to disk tier.

server/src/main/java/org/opensearch/indices/OnHeapCachingTier.java → server/src/main/java/org/opensearch/common/cache/tier/OnHeapCachingTier.java

@@ -6,7 +6,7 @@
  * compatible open source license.
  */
 
-package org.opensearch.indices;
+package org.opensearch.common.cache.tier;
 
 /**
  * This is specific to onHeap caching tier and can be used to add methods which are specific to this tier.

server/src/main/java/org/opensearch/indices/OpenSearchOnHeapCache.java → server/src/main/java/org/opensearch/common/cache/tier/OpenSearchOnHeapCache.java

@@ -6,29 +6,36 @@
  * compatible open source license.
  */
 
-package org.opensearch.indices;
+package org.opensearch.common.cache.tier;
 
 import org.opensearch.common.cache.Cache;
 import org.opensearch.common.cache.CacheBuilder;
 import org.opensearch.common.cache.RemovalListener;
 import org.opensearch.common.cache.RemovalNotification;
 import org.opensearch.common.unit.TimeValue;
 
+import java.util.Objects;
 import java.util.concurrent.ExecutionException;
 import java.util.function.ToLongBiFunction;
 
+/**
+ * This variant of on-heap cache uses OpenSearch custom cache implementation.
+ * @param <K> Type of key
+ * @param <V> Type of value
+ */
 public class OpenSearchOnHeapCache<K, V> implements OnHeapCachingTier<K, V>, RemovalListener<K, V> {
 
     private final Cache<K, V> cache;
     private RemovalListener<K, V> removalListener;
 
-    private OpenSearchOnHeapCache(long maxWeightInBytes, ToLongBiFunction<K, V> weigher, TimeValue expireAfterAcess) {
+    private OpenSearchOnHeapCache(Builder<K, V> builder) {
+        Objects.requireNonNull(builder.weigher);
         CacheBuilder<K, V> cacheBuilder = CacheBuilder.<K, V>builder()
-            .setMaximumWeight(maxWeightInBytes)
-            .weigher(weigher)
+            .setMaximumWeight(builder.maxWeightInBytes)
+            .weigher(builder.weigher)
             .removalListener(this);
-        if (expireAfterAcess != null) {
-            cacheBuilder.setExpireAfterAccess(expireAfterAcess);
+        if (builder.expireAfterAcess != null) {
+            cacheBuilder.setExpireAfterAccess(builder.expireAfterAcess);
         }
         cache = cacheBuilder.build();
     }
@@ -93,6 +100,11 @@ public void onRemoval(RemovalNotification<K, V> notification) {
         removalListener.onRemoval(notification);
     }
 
+    /**
+     * Builder object
+     * @param <K> Type of key
+     * @param <V> Type of value
+     */
     public static class Builder<K, V> {
         private long maxWeightInBytes;
 
@@ -118,7 +130,7 @@ public Builder<K, V> setExpireAfterAccess(TimeValue expireAfterAcess) {
         }
 
         public OpenSearchOnHeapCache<K, V> build() {
-            return new OpenSearchOnHeapCache<K, V>(maxWeightInBytes, weigher, expireAfterAcess);
+            return new OpenSearchOnHeapCache<K, V>(this);
         }
     }
 }

server/src/main/java/org/opensearch/indices/TierType.java → server/src/main/java/org/opensearch/common/cache/tier/TierType.java

@@ -6,8 +6,11 @@
  * compatible open source license.
  */
 
-package org.opensearch.indices;
+package org.opensearch.common.cache.tier;
 
+/**
+ * Tier types in cache.
+ */
 public enum TierType {
 
     ON_HEAP,

server/src/main/java/org/opensearch/indices/TieredCacheEventListener.java → server/src/main/java/org/opensearch/common/cache/tier/TieredCacheEventListener.java

@@ -6,10 +6,15 @@
  * compatible open source license.
  */
 
-package org.opensearch.indices;
+package org.opensearch.common.cache.tier;
 
 import org.opensearch.common.cache.RemovalNotification;
 
+/**
+ * This can be used to listen to tiered caching events
+ * @param <K> Type of key
+ * @param <V> Type of value
+ */
 public interface TieredCacheEventListener<K, V> {
 
     void onMiss(K key, TierType tierType);

server/src/main/java/org/opensearch/indices/TieredCacheLoader.java → server/src/main/java/org/opensearch/common/cache/tier/TieredCacheLoader.java

@@ -6,8 +6,13 @@
  * compatible open source license.
  */
 
-package org.opensearch.indices;
+package org.opensearch.common.cache.tier;
 
+/**
+ * Used to load value in tiered cache if not present.
+ * @param <K> Type of key
+ * @param <V> Type of value
+ */
 public interface TieredCacheLoader<K, V> {
     V load(K key) throws Exception;
 

server/src/main/java/org/opensearch/indices/TieredCacheService.java → server/src/main/java/org/opensearch/common/cache/tier/TieredCacheService.java

@@ -6,7 +6,7 @@
  * compatible open source license.
  */
 
-package org.opensearch.indices;
+package org.opensearch.common.cache.tier;
 
 import java.util.Optional;
 

server/src/main/java/org/opensearch/indices/TieredCacheSpilloverStrategyService.java → server/src/main/java/org/opensearch/common/cache/tier/TieredCacheSpilloverStrategyService.java

@@ -6,7 +6,7 @@
  * compatible open source license.
  */
 
-package org.opensearch.indices;
+package org.opensearch.common.cache.tier;
 
 import org.opensearch.common.cache.RemovalListener;
 import org.opensearch.common.cache.RemovalNotification;
@@ -39,14 +39,10 @@ public class TieredCacheSpilloverStrategyService<K, V> implements TieredCacheSer
      */
     private final List<CachingTier<K, V>> cachingTierList;
 
-    private TieredCacheSpilloverStrategyService(
-        OnHeapCachingTier<K, V> onHeapCachingTier,
-        DiskCachingTier<K, V> diskCachingTier,
-        TieredCacheEventListener<K, V> tieredCacheEventListener
-    ) {
-        this.onHeapCachingTier = Objects.requireNonNull(onHeapCachingTier);
-        this.diskCachingTier = Optional.ofNullable(diskCachingTier);
-        this.tieredCacheEventListener = Objects.requireNonNull(tieredCacheEventListener);
+    private TieredCacheSpilloverStrategyService(Builder<K, V> builder) {
+        this.onHeapCachingTier = Objects.requireNonNull(builder.onHeapCachingTier);
+        this.diskCachingTier = Optional.ofNullable(builder.diskCachingTier);
+        this.tieredCacheEventListener = Objects.requireNonNull(builder.tieredCacheEventListener);
         this.cachingTierList = this.diskCachingTier.map(diskTier -> Arrays.asList(onHeapCachingTier, diskTier))
             .orElse(List.of(onHeapCachingTier));
         setRemovalListeners();
@@ -197,6 +193,11 @@ public static class CacheValue<V> {
         }
     }
 
+    /**
+     * Builder object
+     * @param <K> Type of key
+     * @param <V> Type of value
+     */
     public static class Builder<K, V> {
         private OnHeapCachingTier<K, V> onHeapCachingTier;
         private DiskCachingTier<K, V> diskCachingTier;
@@ -220,11 +221,7 @@ public Builder<K, V> setTieredCacheEventListener(TieredCacheEventListener<K, V>
         }
 
         public TieredCacheSpilloverStrategyService<K, V> build() {
-            return new TieredCacheSpilloverStrategyService<K, V>(
-                this.onHeapCachingTier,
-                this.diskCachingTier,
-                this.tieredCacheEventListener
-            );
+            return new TieredCacheSpilloverStrategyService<K, V>(this);
         }
     }
 

server/src/main/java/org/opensearch/common/cache/tier/package-info.java

@@ -0,0 +1,10 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+/** Base package for cache tier support. */
+package org.opensearch.common.cache.tier;

server/src/main/java/org/opensearch/index/cache/request/ShardRequestCache.java

@@ -33,9 +33,9 @@
 package org.opensearch.index.cache.request;
 
 import org.apache.lucene.util.Accountable;
+import org.opensearch.common.cache.tier.TierType;
 import org.opensearch.common.metrics.CounterMetric;
 import org.opensearch.core.common.bytes.BytesReference;
-import org.opensearch.indices.TierType;
 
 import java.util.EnumMap;
 

server/src/main/java/org/opensearch/indices/AbstractIndexShardCacheEntity.java

@@ -34,6 +34,7 @@
 
 import org.opensearch.common.cache.RemovalNotification;
 import org.opensearch.common.cache.RemovalReason;
+import org.opensearch.common.cache.tier.TierType;
 import org.opensearch.core.common.bytes.BytesReference;
 import org.opensearch.index.cache.request.ShardRequestCache;
 import org.opensearch.index.shard.IndexShard;

server/src/main/java/org/opensearch/indices/IndicesRequestCache.java

@@ -40,6 +40,13 @@
 import org.apache.lucene.util.RamUsageEstimator;
 import org.opensearch.common.CheckedSupplier;
 import org.opensearch.common.cache.RemovalNotification;
+import org.opensearch.common.cache.tier.OnHeapCachingTier;
+import org.opensearch.common.cache.tier.OpenSearchOnHeapCache;
+import org.opensearch.common.cache.tier.TierType;
+import org.opensearch.common.cache.tier.TieredCacheEventListener;
+import org.opensearch.common.cache.tier.TieredCacheLoader;
+import org.opensearch.common.cache.tier.TieredCacheService;
+import org.opensearch.common.cache.tier.TieredCacheSpilloverStrategyService;
 import org.opensearch.common.lucene.index.OpenSearchDirectoryReader;
 import org.opensearch.common.settings.Setting;
 import org.opensearch.common.settings.Setting.Property;
@@ -190,7 +197,7 @@ void invalidate(CacheEntity cacheEntity, DirectoryReader reader, BytesReference
      *
      * @opensearch.internal
      */
-    private static class Loader implements org.opensearch.indices.TieredCacheLoader<Key, BytesReference> {
+    private static class Loader implements TieredCacheLoader<Key, BytesReference> {
 
         private final CacheEntity entity;
         private final CheckedSupplier<BytesReference, IOException> loader;

server/src/test/java/org/opensearch/indices/TieredCacheSpilloverStrategyServiceTests.java → server/src/test/java/org/opensearch/common/cache/tier/TieredCacheSpilloverStrategyServiceTests.java

@@ -6,7 +6,7 @@
  * compatible open source license.
  */
 
-package org.opensearch.indices;
+package org.opensearch.common.cache.tier;
 
 import org.opensearch.common.cache.RemovalListener;
 import org.opensearch.common.cache.RemovalNotification;

server/src/test/java/org/opensearch/indices/IndicesServiceCloseTests.java

@@ -37,6 +37,7 @@
 import org.opensearch.cluster.ClusterName;
 import org.opensearch.cluster.routing.allocation.DiskThresholdSettings;
 import org.opensearch.common.cache.RemovalNotification;
+import org.opensearch.common.cache.tier.TierType;
 import org.opensearch.common.settings.Settings;
 import org.opensearch.common.util.concurrent.OpenSearchExecutors;
 import org.opensearch.core.common.bytes.BytesArray;