diff --git a/src/main/java/reposense/model/ConfigRunConfiguration.java b/src/main/java/reposense/model/ConfigRunConfiguration.java index 8fb9551ba4..4026c69cbb 100644 --- a/src/main/java/reposense/model/ConfigRunConfiguration.java +++ b/src/main/java/reposense/model/ConfigRunConfiguration.java @@ -2,11 +2,9 @@ import java.io.IOException; import java.nio.file.Files; -import java.nio.file.Path; import java.util.Arrays; import java.util.Collections; import java.util.List; -import java.util.function.Supplier; import java.util.logging.Level; import java.util.logging.Logger; diff --git a/src/main/java/reposense/util/function/FailableOptional.java b/src/main/java/reposense/util/function/FailableOptional.java index e80e4ebd66..1521c287ba 100644 --- a/src/main/java/reposense/util/function/FailableOptional.java +++ b/src/main/java/reposense/util/function/FailableOptional.java @@ -6,16 +6,48 @@ import java.util.function.Supplier; /** - * {@code Optional} monad that enables both an empty and a - * fail option. + * An {@code Optional} monad that enables both an empty and a fail option. * - * @param Type T, unbounded to any type. + * @param Generic Type {@code T}, unbounded to any type. */ public abstract class FailableOptional { + /** + * Creates a new {@code FailableOptional} object. {@code FailableOptional} + * can contain {@code null}. + * + * @param item Item of type {@code T}. + * @param Generic Type {@code T}. + * @return An instance of {@code FailableOptional} instance. + */ + public static FailableOptional of(T item) { + return new Present<>(item); + } + + /** + * Creates a new {@code FailableOptional} object. + * This method can allow null values to be stored within the {@code FailableOptional} object. + * + * @param supplier Produces an object of type {@code T}, which can also be {@code null}. + * This {@code Supplier} cannot throw any Exceptions. + * @param Generic type {@code T}. + * @return {@code FailableOptional} object wrapping an object of type {@code T}. + */ public static FailableOptional of(Supplier supplier) { return of(supplier.get()); } + /** + * Creates a new {@code FailableOptional} object. + * This method can allow null values to be stored within the {@code FailableOptional} object. + * + * @param supplier Produces an object of type {@code T}, which can also be {@code null}. + * This {@code ThrowableSupplier} can throw Exceptions and will be automatically + * converted into a failed instance of {@code ThrowaableSupplier}. + * @param Generic type {@code T}. + * @param Generic type {@code E} bounded to {@code Exception}. + * @return {@code FailableOptional} object wrapping an object of type {@code T} or a failed + * instance of {@code FailableOptional}. + */ public static FailableOptional of(ThrowableSupplier supplier) { try { return of(supplier.produce()); @@ -24,10 +56,44 @@ public static FailableOptional of(ThrowableSupplier< } } + /** + * Creates a new {@code FailableOptional} object. + * {@code null} is automatically converted into an empty instance of {@code FailableOptional} object. + * + * @param item Item of type {@code T}. + * @param Generic Type {@code T}. + * @return An instance of {@code FailableOptional} instance. + */ + public static FailableOptional ofNullable(T item) { + return item == null ? ofAbsent() : of(item); + } + + /** + * Creates a new {@code FailableOptional} object. + * This method converts {@code null} into an empty instance of {@code FailableOptional}. + * + * @param supplier Produces an object of type {@code T}, which can also be {@code null}. + * This {@code Supplier} cannot throw any Exceptions. + * @param Generic type {@code T}. + * @return {@code FailableOptional} object wrapping an object of type {@code T} or an empty + * instance of {@code FailableOptional}. + */ public static FailableOptional ofNullable(Supplier supplier) { return ofNullable(supplier.get()); } + /** + * Creates a new {@code FailableOptional} object. + * This method converts {@code null} into an empty instance of {@code FailableOptional}. + * + * @param supplier Produces an object of type {@code T}, which can also be {@code null}. + * This {@code ThrowableSupplier} can throw Exceptions and will be automatically + * converted into a failed instance of {@code ThrowaableSupplier}. + * @param Generic type {@code T}. + * @param Generic type {@code E} bounded to {@code Exception}. + * @return {@code FailableOptional} object wrapping an object of type {@code T} or an empty + * instance of {@code FailableOptional}. + */ public static FailableOptional ofNullable(ThrowableSupplier supplier) { try { return ofNullable(supplier.produce()); @@ -36,45 +102,210 @@ public static FailableOptional ofNullable(ThrowableS } } - public static FailableOptional of(T item) { - return new Present<>(item); - } - - public static FailableOptional ofNullable(T item) { - return item == null ? ofAbsent() : of(item); - } - + /** + * Creates an empty instance of {@code FailableOptional}. + * + * @param Generic Type {@code T}. + * @return Empty instance of {@code FailableOptional}. + */ public static FailableOptional ofAbsent() { return new Absent<>(); } + /** + * Creates a failed instance of {@code FailableOptional}. + * + * @param Generic Type {@code T}. + * @return Failed instance of {@code FailableOptional}. + */ public static FailableOptional ofFailure(Exception e) { return new Fail<>(e); } + /** + * Executes the provided {@code Runner} if this current instance of + * {@code FailableOptional} contains a value. + * + * @param runner {@code Runner} instance that executes if this {@code FailableOptional} + * contains a value + * @return This {@code FailableOptional} object + */ public abstract FailableOptional ifPresent(Runnable runner); + + /** + * Executes the provided {@code ThrowableConsumer} if this current instance of + * {@code FailableOptional} contains a value. + * + * @param consumer {@code ThrowableConsumer} instance that consumes the stored + * value if present. + * @param Generic Type {@code E} bounded by Exception. + * @return This {@code ThrowableConsumer} instance. + */ public abstract FailableOptional ifPresent(ThrowableConsumer consumer); + + /** + * Executes the provided {@code Runner} if this current instance of + * {@code FailableOptional} does not contains a value. + * + * @param runner {@code Runner} instance that executes if this {@code FailableOptional} + * does not contains a value. + * @return This {@code FailableOptional} object. + */ public abstract FailableOptional ifAbsent(Runnable runner); + + /** + * Executes the provided {@code ThrowableConsumer} if this current instance of + * {@code FailableOptional} does not contains a value. + * + * @param consumer {@code ThrowableConsumer} instance that attempts to consume + * an object of type {@code T}. + * @param Generic Type {@code E} bounded by Exception. + * @return This {@code ThrowableConsumer} instance. + */ public abstract FailableOptional ifAbsent(ThrowableConsumer consumer); + + /** + * Executes the provided {@code Runner} if this current instance of + * {@code FailableOptional} has failed. + * + * @param runner {@code Runner} instance that executes if this {@code FailableOptional} + * has failed. + * @return This {@code FailableOptional} object. + */ public abstract FailableOptional ifFail(Runnable runner); + + /** + * Executes the provided {@code ThrowableConsumer} if this current instance of + * {@code FailableOptional} has failed. + * + * @param consumer {@code ThrowableConsumer} instance that attempts to consume + * an object of type {@code T}. + * @param Generic Type {@code E} bounded by Exception. + * @return This {@code ThrowableConsumer} instance. + */ public abstract FailableOptional ifFail( ThrowableConsumer consumer); + /** + * Maps the stored value in this {@code FailableOptional} into another + * {@code FailableOptional} containing items of Type {@code U}. + * If this {@code FailableOptional} contains nothing or has failed, + * this instance is returned as is. + * + * @param function {@code ThrowableFunction} that takes an object of Type {@code T} + * and returns Type {@code U} and might throw + * Exception of Type {@code E}. + * @param Generic Type {@code U}, representing the return type of the new {@code FailableOptional}. + * @param Generic Type {@code E}, representing the Type of the Exception that might be thrown. + * @return This instance, if this instance is empty or has failed, otherwise, a new mapped instance + * of {@code FailableOptional}. + */ public abstract FailableOptional map(ThrowableFunction function); + + /** + * Maps the stored value into another new instance of {@code FailableOptional}. Unlike {@code map}, + * this method requires that functions itself return the new instance of {@code FailableOptional}. + * + * @param function {@code ThrowableFunction} that takes an object of Type {@code T} + * and returns Type {@code FailableOptional} and + * might throw Exception of Type {@code E}. + * @param Generic Type {@code U}, representing the return type of the new {@code FailableOptional}. + * @param Generic Type {@code E}, representing the Type of the Exception that might be thrown. + * @return This instance, if this instance is empty or has failed, otherwise, a new mapped instance + * of {@code FailableOptional}. + */ public abstract FailableOptional flatMap( ThrowableFunction, E> function); + + /** + * Checks if the stored item fulfills the predicate, and if so, return this instance, and if not, + * return an empty instance of {@code FailableOptional}. + * + * @param predicate {@code Predicate} that tests an item of Type {@code T}. + * @return This instance if the predicate evaluates to true, else an empty instance of + * {@code FailableOptional}. + */ public abstract FailableOptional filter(Predicate predicate); + + /** + * Returns the item stored in this {@code FailableOptional}. + * + * @return Stored item of Type {@code T} + * @throws NoSuchElementException if this {@code FailableOptional} does not contain any values + * or has failed. + */ public abstract T get() throws NoSuchElementException; + + /** + * Returns the item stored in this {@code FailableOptional}, and if + * there is no such value, return the input parameter {@code item}. + * + * @param item The value to return if this {@code FailableOptional} is empty or has failed. + * @return The stored item or the input item. + */ public abstract T orElse(T item); + + /** + * Returns the item stored in this {@code FailableOptional}, and if + * there is no such value, return the input parameter {@code item}. + * + * @param e The Exception to throw if this {@code FailableOptional} is empty or has failed. + * @return The stored item or throws an Exception. + * @throws Exception if there are no items stored in this {@code FailableOptional} instance. + */ public abstract T orElseThrow(Exception e) throws Exception; + + /** + * Checks if this {@code FailableOptional} instance contains a value. + * + * @return true if this instance of {@code FailableOptional} is not empty, false otherwise. + */ public abstract boolean isPresent(); + + /** + * Checks if this {@code FailableOptional} instance does not contains a value. + * + * @return true if this instance of {@code FailableOptional} is empty, false otherwise. + */ public abstract boolean isAbsent(); + + /** + * Checks if this {@code FailableOptional} instance has failed. + * + * @return true if this instance of {@code FailableOptional} has failed, false otherwise. + */ public abstract boolean isFail(); + + /** + * Verifies that a failed instance of {@code FailableOptional} has failed due to the + * input list of Exceptions to check. + * + * @param exList List of Exception Classes to verify the failure Exception cause. + * @return This instance if this instance has failed and is due to any one of the reasons specified + * in the {@code exList} argument, or an empty {@code FailableOptional} instance otherwise. + */ public abstract FailableOptional ifFailOfType(List> exList); + + /** + * Attempts to recover a failed instance by providing an item of Type {@code U}, which will be + * wrapped up in another {@code FailableOptional} object. + * + * @param supplier A {@code ThrowableSupplier} instance that provides an item of Type {@code U}, + * which may throw an Exception of Type {@code E}. + * @param Generic Type {@code U} represents the Type of the object returned by the + * {@code ThrowableSupplier}. + * @param Generic Type {@code E} bounded by Exception. + * @return A new {@code FailableOptional} object. + */ public abstract FailableOptional recover(ThrowableSupplier supplier); - private static class Present extends FailableOptional { + /** + * Represents a {@code ThrowableSupplier} that contains a value. + * + * @param Generic Type {@code T}. + */ + private static final class Present extends FailableOptional { private final T item; private Present(T item) { @@ -128,7 +359,8 @@ public FailableOptional map(ThrowableFunction FailableOptional flatMap(ThrowableFunction, E> function) { + public FailableOptional flatMap( + ThrowableFunction, E> function) { try { return function.apply(this.item); } catch (Exception e) { @@ -186,7 +418,12 @@ public FailableOptional recover(ThrowableSupplier extends FailableOptional { + /** + * Represents a {@code ThrowableSupplier} that does not contain any value. + * + * @param Generic Type {@code T}. + */ + private static final class Absent extends FailableOptional { @Override public FailableOptional ifPresent(Runnable runner) { @@ -227,7 +464,8 @@ public FailableOptional map(ThrowableFunction FailableOptional flatMap(ThrowableFunction, E> function) { + public FailableOptional flatMap( + ThrowableFunction, E> function) { @SuppressWarnings("unchecked") FailableOptional failed = (FailableOptional) this; return failed; @@ -279,6 +517,11 @@ public FailableOptional recover(ThrowableSupplier Generic Type {@code T}. + */ private static class Fail extends FailableOptional { private final Exception exception; @@ -312,7 +555,9 @@ public FailableOptional ifFail(Runnable runner) { return this; } - public FailableOptional ifFail(ThrowableConsumer consumer) { + @Override + public FailableOptional ifFail( + ThrowableConsumer consumer) { try { @SuppressWarnings("unchecked") E except = (E) this.exception; @@ -332,7 +577,8 @@ public FailableOptional map(ThrowableFunction FailableOptional flatMap(ThrowableFunction, E> function) { + public FailableOptional flatMap( + ThrowableFunction, E> function) { @SuppressWarnings("unchecked") FailableOptional failed = (FailableOptional) this; return failed; diff --git a/src/main/java/reposense/util/function/ThrowableConsumer.java b/src/main/java/reposense/util/function/ThrowableConsumer.java index 245497570a..6bf53dd4a5 100644 --- a/src/main/java/reposense/util/function/ThrowableConsumer.java +++ b/src/main/java/reposense/util/function/ThrowableConsumer.java @@ -1,5 +1,14 @@ package reposense.util.function; +/** + * Functional interface that defines a Consumer that can throw + * an Exception on execution. + * + * @param The Type of the item that this {@code ThrowableConsumer} can + * consume. + * @param The Type of the Exception that this {@code ThrowableConsumer} + * can throw. + */ @FunctionalInterface public interface ThrowableConsumer { void consume(T t) throws E; diff --git a/src/main/java/reposense/util/function/ThrowableFunction.java b/src/main/java/reposense/util/function/ThrowableFunction.java index 53279e0d30..5ef493373e 100644 --- a/src/main/java/reposense/util/function/ThrowableFunction.java +++ b/src/main/java/reposense/util/function/ThrowableFunction.java @@ -1,5 +1,14 @@ package reposense.util.function; +/** + * Functional interface that defines a Supplier that can throw + * an Exception on execution. + * + * @param The Input Type of the item that this {@code ThrowableFunction}. + * @param The Return Type of this {@code ThrowableFunction}. + * @param The Type of the Exception that this {@code ThrowableFunction}. + * can throw. + */ @FunctionalInterface public interface ThrowableFunction { U apply(T t) throws E; diff --git a/src/main/java/reposense/util/function/ThrowableSupplier.java b/src/main/java/reposense/util/function/ThrowableSupplier.java index d1419092fb..04d67baf15 100644 --- a/src/main/java/reposense/util/function/ThrowableSupplier.java +++ b/src/main/java/reposense/util/function/ThrowableSupplier.java @@ -1,5 +1,14 @@ package reposense.util.function; +/** + * Functional interface that defines a Supplier that can throw + * an Exception on execution. + * + * @param The Type of the item that this {@code ThrowableSupplier} can + * supply. + * @param The Type of the Exception that this {@code ThrowableSupplier} + * can throw. + */ @FunctionalInterface public interface ThrowableSupplier { T produce() throws E;