From d6ecd265257429d99f66f24895dc458cb40b3700 Mon Sep 17 00:00:00 2001 From: Greg Gibeling Date: Mon, 21 Apr 2025 12:29:11 -0700 Subject: [PATCH 1/2] Add javadocs to cache API --- .../com/g2forge/reassert/cache/ICache.java | 3 + .../reassert/cache/ICacheAreaDescriptor.java | 72 +++++++++++++++++-- .../cache/store/DirectoryCacheStore.java | 3 + .../reassert/cache/store/FileCacheStore.java | 3 + .../reassert/cache/store/ICacheStore.java | 22 ++++++ .../cache/store/JacksonCacheStore.java | 3 + .../store/ObjectSerializationCacheStore.java | 4 ++ 7 files changed, 105 insertions(+), 5 deletions(-) diff --git a/re-cache/src/main/java/com/g2forge/reassert/cache/ICache.java b/re-cache/src/main/java/com/g2forge/reassert/cache/ICache.java index 23ae5a1..7d6c269 100644 --- a/re-cache/src/main/java/com/g2forge/reassert/cache/ICache.java +++ b/re-cache/src/main/java/com/g2forge/reassert/cache/ICache.java @@ -2,6 +2,9 @@ import com.g2forge.alexandria.java.function.IFunction1; +/** + * An on disk cache, capable of creating multiple cache areas. Each cache area can have it's own key and value types. + */ public interface ICache { public IFunction1 createArea(ICacheAreaDescriptor areaDescriptor); } diff --git a/re-cache/src/main/java/com/g2forge/reassert/cache/ICacheAreaDescriptor.java b/re-cache/src/main/java/com/g2forge/reassert/cache/ICacheAreaDescriptor.java index f1d1ac4..ca7ff82 100644 --- a/re-cache/src/main/java/com/g2forge/reassert/cache/ICacheAreaDescriptor.java +++ b/re-cache/src/main/java/com/g2forge/reassert/cache/ICacheAreaDescriptor.java @@ -2,26 +2,88 @@ import java.nio.file.Path; +import com.g2forge.alexandria.java.adt.name.INamed; import com.g2forge.alexandria.java.function.IFunction1; import com.g2forge.alexandria.java.function.IFunction2; import com.g2forge.reassert.cache.store.ICacheStore; -public interface ICacheAreaDescriptor { +/** + * A descriptor for a cache area. The methods on this interface allow the cache to learn how to compute values, load & store keys, exceptions, and values, and + * where to create cache entries within this area. Caches should cache exceptions when possible, and should verify that the key for any cache entry matches to + * expected key in case of collisions in {@link #getHashFunction()}. + * + * @param + * The type of keys for this cache. + * @param + * The type of values for this cache. + */ +public interface ICacheAreaDescriptor extends INamed { + /** + * Storage abstraction for exceptions from {@link #getFunction()}. Exceptions are cached in order to improve performance. See + * {@link com.g2forge.reassert.cache.store.ObjectSerializationCacheStore} which is strongly recommended as being one of the few ways to serialize and + * deserialize exceptions in Java. + * + * @return Storage abstraction for the cache function exceptions. + */ + public ICacheStore getExceptionConverter(); + + /** + * Get the name of the on-disk exception within the cache entry. + * + * @return The name of the on-disk exception within the cache entry. + */ + public String getExceptionName(); + + /** + * The function to cache. Accepts the key, and the on-disk path where the value should be cached. The path should only be used if this function is + * downloading something, or otherwise making a copy of a large file structure. The path will not exist when this function is called, but it can be created + * by this function. If path is null then the function should download any files to a temp directory instead. Returns the actual + * value. + * + * @return The function whose results we are caching. A function from key and local path to actual value. + */ public IFunction2 getFunction(); + /** + * Key hash function used to determine the on-disk location of the cache entry within the cache area. This function should return a (hopefully, but not + * necessarily always) unique path for each key, which is valid on this operating system. key -> Paths.get(key.toString()), or something + * equally simple, is acceptable if there are never OS-disallowed characters in that string. + * + * @return + */ public IFunction1 getHashFunction(); + /** + * Storage abstraction for the cache keys. See implementations of {@link ICacheStore}. + * + * @return Storage abstraction for the cache keys + */ public ICacheStore getKeyConverter(); + /** + * Get the name of the on-disk key within the cache entry. + * + * @return The name of the on-disk key within the cache entry. + */ public String getKeyName(); + /** + * A name for this cache area. Should be unique to whatever is being cached and stable over time. Paths.get(getClass().getSimpleName()) is + * often a reasonable value. + */ public Path getName(); + /** + * Storage abstraction for the cache values. See implementations of {@link ICacheStore}. + * + * @return Storage abstraction for the cache values. + */ public ICacheStore getValueConverter(); - - public ICacheStore getExceptionConverter(); + /** + * Get the name of the on-disk value within the cache entry. + * + * @return The name of the on-disk value within the cache entry. + */ public String getValueName(); - - public String getExceptionName(); } diff --git a/re-cache/src/main/java/com/g2forge/reassert/cache/store/DirectoryCacheStore.java b/re-cache/src/main/java/com/g2forge/reassert/cache/store/DirectoryCacheStore.java index 56c4f6b..967ea54 100644 --- a/re-cache/src/main/java/com/g2forge/reassert/cache/store/DirectoryCacheStore.java +++ b/re-cache/src/main/java/com/g2forge/reassert/cache/store/DirectoryCacheStore.java @@ -9,6 +9,9 @@ import com.g2forge.alexandria.java.io.RuntimeIOException; import com.g2forge.alexandria.java.io.file.HFile; +/** + * A cache store for directories abstracted as java paths. They are moved into the cache when stored, or copied in if the move fails. + */ public class DirectoryCacheStore implements ICacheStore { @Override public Path load(Path path) { diff --git a/re-cache/src/main/java/com/g2forge/reassert/cache/store/FileCacheStore.java b/re-cache/src/main/java/com/g2forge/reassert/cache/store/FileCacheStore.java index 671312b..1a8f73a 100644 --- a/re-cache/src/main/java/com/g2forge/reassert/cache/store/FileCacheStore.java +++ b/re-cache/src/main/java/com/g2forge/reassert/cache/store/FileCacheStore.java @@ -7,6 +7,9 @@ import com.g2forge.alexandria.java.io.RuntimeIOException; +/** + * A cache store for files abstracted as java paths. They are moved into the cache when stored. + */ public class FileCacheStore implements ICacheStore { @Override public Path load(Path path) { diff --git a/re-cache/src/main/java/com/g2forge/reassert/cache/store/ICacheStore.java b/re-cache/src/main/java/com/g2forge/reassert/cache/store/ICacheStore.java index 4ce1344..3ce0cb0 100644 --- a/re-cache/src/main/java/com/g2forge/reassert/cache/store/ICacheStore.java +++ b/re-cache/src/main/java/com/g2forge/reassert/cache/store/ICacheStore.java @@ -2,8 +2,30 @@ import java.nio.file.Path; +/** + * A type-specific storage abstraction for cached keys and values. + * + * @param + * The type being stored. + */ public interface ICacheStore { + /** + * Load a value from the specified path. + * + * @param path + * The file or directory to load. + * @return The loaded value. + */ public T load(Path path); + /** + * Store a value to the specified path. + * + * @param path + * The file or directory to store a value to. This may or may not exist. + * @param value + * The value to store. + * @return The value that was stored. + */ public T store(Path path, T value); } diff --git a/re-cache/src/main/java/com/g2forge/reassert/cache/store/JacksonCacheStore.java b/re-cache/src/main/java/com/g2forge/reassert/cache/store/JacksonCacheStore.java index 6270d88..b1aaec9 100644 --- a/re-cache/src/main/java/com/g2forge/reassert/cache/store/JacksonCacheStore.java +++ b/re-cache/src/main/java/com/g2forge/reassert/cache/store/JacksonCacheStore.java @@ -11,6 +11,9 @@ import lombok.Getter; import lombok.RequiredArgsConstructor; +/** + * A cache store for objects, which uses a jackson object mapper to serialize and deserialize them. + */ @Getter @RequiredArgsConstructor public class JacksonCacheStore implements ICacheStore { diff --git a/re-cache/src/main/java/com/g2forge/reassert/cache/store/ObjectSerializationCacheStore.java b/re-cache/src/main/java/com/g2forge/reassert/cache/store/ObjectSerializationCacheStore.java index 2aa4978..fd0d2f7 100644 --- a/re-cache/src/main/java/com/g2forge/reassert/cache/store/ObjectSerializationCacheStore.java +++ b/re-cache/src/main/java/com/g2forge/reassert/cache/store/ObjectSerializationCacheStore.java @@ -12,6 +12,10 @@ import lombok.Getter; import lombok.RequiredArgsConstructor; +/** + * A cache store for objects, which uses java object serialization. This is particularly suited to storing exceptions on disk, and is often used for + * {@link com.g2forge.reassert.cache.ICacheAreaDescriptor#getExceptionConverter()}. + */ @Getter @RequiredArgsConstructor public class ObjectSerializationCacheStore implements ICacheStore { From 5a537450016749267f6cdb0e6c715d2fbb4d65ba Mon Sep 17 00:00:00 2001 From: Greg Gibeling Date: Mon, 21 Apr 2025 14:04:45 -0700 Subject: [PATCH 2/2] Fix javadoc error & warnings --- .../main/java/com/g2forge/reassert/cache/ICache.java | 11 +++++++++++ .../g2forge/reassert/cache/ICacheAreaDescriptor.java | 12 ++++++------ .../reassert/cache/store/JacksonCacheStore.java | 5 +++++ .../cache/store/ObjectSerializationCacheStore.java | 4 ++++ 4 files changed, 26 insertions(+), 6 deletions(-) diff --git a/re-cache/src/main/java/com/g2forge/reassert/cache/ICache.java b/re-cache/src/main/java/com/g2forge/reassert/cache/ICache.java index 7d6c269..e1ee3e0 100644 --- a/re-cache/src/main/java/com/g2forge/reassert/cache/ICache.java +++ b/re-cache/src/main/java/com/g2forge/reassert/cache/ICache.java @@ -6,5 +6,16 @@ * An on disk cache, capable of creating multiple cache areas. Each cache area can have it's own key and value types. */ public interface ICache { + /** + * Create a cache area from it's descriptor. + * + * @param + * The type of keys for this cache area. + * @param + * The type of values for this cache area. + * @param areaDescriptor + * The cache area descriptor. + * @return A cache area. A function from keys to values. + */ public IFunction1 createArea(ICacheAreaDescriptor areaDescriptor); } diff --git a/re-cache/src/main/java/com/g2forge/reassert/cache/ICacheAreaDescriptor.java b/re-cache/src/main/java/com/g2forge/reassert/cache/ICacheAreaDescriptor.java index ca7ff82..2f66dea 100644 --- a/re-cache/src/main/java/com/g2forge/reassert/cache/ICacheAreaDescriptor.java +++ b/re-cache/src/main/java/com/g2forge/reassert/cache/ICacheAreaDescriptor.java @@ -8,14 +8,14 @@ import com.g2forge.reassert.cache.store.ICacheStore; /** - * A descriptor for a cache area. The methods on this interface allow the cache to learn how to compute values, load & store keys, exceptions, and values, and - * where to create cache entries within this area. Caches should cache exceptions when possible, and should verify that the key for any cache entry matches to - * expected key in case of collisions in {@link #getHashFunction()}. + * A descriptor for a cache area. The methods on this interface allow the cache to learn how to compute values, load & store keys, exceptions, and values, + * and where to create cache entries within this area. Caches should cache exceptions when possible, and should verify that the key for any cache entry matches + * to expected key in case of collisions in {@link #getHashFunction()}. * * @param - * The type of keys for this cache. + * The type of keys for this cache area. * @param - * The type of values for this cache. + * The type of values for this cache area. */ public interface ICacheAreaDescriptor extends INamed { /** @@ -49,7 +49,7 @@ public interface ICacheAreaDescriptor extends INamed { * necessarily always) unique path for each key, which is valid on this operating system. key -> Paths.get(key.toString()), or something * equally simple, is acceptable if there are never OS-disallowed characters in that string. * - * @return + * @return The key hash function. */ public IFunction1 getHashFunction(); diff --git a/re-cache/src/main/java/com/g2forge/reassert/cache/store/JacksonCacheStore.java b/re-cache/src/main/java/com/g2forge/reassert/cache/store/JacksonCacheStore.java index b1aaec9..8f129d5 100644 --- a/re-cache/src/main/java/com/g2forge/reassert/cache/store/JacksonCacheStore.java +++ b/re-cache/src/main/java/com/g2forge/reassert/cache/store/JacksonCacheStore.java @@ -13,12 +13,17 @@ /** * A cache store for objects, which uses a jackson object mapper to serialize and deserialize them. + * + * @param + * The type of the values being stored. */ @Getter @RequiredArgsConstructor public class JacksonCacheStore implements ICacheStore { + /** The jackson mapper to use during serdes. */ protected final ObjectMapper mapper; + /** The type of the values being stored. */ protected final ITypeRef type; @Override diff --git a/re-cache/src/main/java/com/g2forge/reassert/cache/store/ObjectSerializationCacheStore.java b/re-cache/src/main/java/com/g2forge/reassert/cache/store/ObjectSerializationCacheStore.java index fd0d2f7..cea0cad 100644 --- a/re-cache/src/main/java/com/g2forge/reassert/cache/store/ObjectSerializationCacheStore.java +++ b/re-cache/src/main/java/com/g2forge/reassert/cache/store/ObjectSerializationCacheStore.java @@ -15,10 +15,14 @@ /** * A cache store for objects, which uses java object serialization. This is particularly suited to storing exceptions on disk, and is often used for * {@link com.g2forge.reassert.cache.ICacheAreaDescriptor#getExceptionConverter()}. + * + * @param + * The type of the values being stored. */ @Getter @RequiredArgsConstructor public class ObjectSerializationCacheStore implements ICacheStore { + /** The type of the values being stored. */ protected final ITypeRef type; @Override