javax0.jamal.tools.Throwing Maven / Gradle / Ivy
Show all versions of jamal-tools Show documentation
package javax0.jamal.tools;
import javax0.jamal.api.BadSyntax;
import java.util.function.Predicate;
// JavaDoc was generated by GPT 2023-06-23T10:27:00+02:00
/**
* {@code Throwing} is a utility class that allows handling and throwing exceptions in a fluent and concise manner.
*
* Here's a breakdown of the class:
*
* The class provides static factory methods for creating instances of {@code Throwing}.
*
* The {@code of()} methods are used to create a new {@code Throwing} instance by invoking a supplier,
* and providing an optional message supplier (java.util.function.Supplier).
* If an exception occurs during the supplier's execution, a {@code BadSyntax} exception is thrown with the
* corresponding message.
* The of methods with a String parameter allow formatting the hurlMessage by using String.format.
* The of method without a message supplier defaults to an empty message.
*
* The class provides methods to chain operations and handle exceptions in a fluent manner:
*
The {@code hurl()} methods are used to set a custom message supplier for the current instance of {@code Throwing}.
* The {@code when()} methods are used to conditionally throw a {@code BadSyntax} exception based on a boolean
* condition or a predicate. If the condition is true, the exception is thrown with the current message.
* The {@code when()} methods with a consumer parameter allow executing a consumer function on the object if the
* condition is true. If an exception occurs during the consumer's execution, a {@code BadSyntax} exception is thrown
* with the current message.
* The {@code when()} method with a Class parameter allows casting the object to the specified class and executing
* a consumer on it if the condition is met. If an exception occurs during the consumer's execution, a {@code BadSyntax}
* exception is thrown with the current message.
* The {@code map()} methods are used to transform the object using a provided function and return a new
* {@code Throwing} instance containing the transformed object. If an exception occurs during the function's execution,
* a {@code BadSyntax} exception is thrown with the current message.
* The {@code cast()} method allows casting the object to the specified class and returning a new {@code Throwing}
* instance containing the cast object. If an exception occurs during the cast operation, a {@code BadSyntax} exception
* is thrown with the current message.
* The {@code get()} method simply returns the object held by the {@code Throwing} instance.
*
* In summary, the {@code Throwing} class provides a way to handle exceptions within a fluent API, allowing you to chain
* operations and control the flow based on conditions while providing meaningful error messages through the {@code BadSyntax} exception.
*/
public class Throwing implements ThrowingAPI.HasMessage, ThrowingAPI.NoMessage {
/**
* Functional interface for a supplier that may throw an exception.
*
* @param the type of the supplied value
*/
public interface Supplier {
Z get() throws Exception;
}
/**
* Functional interface for a function that may throw an exception.
*
* @param the type of the input to the function
* @param the type of function's result
*/
public interface Function {
R apply(Z z) throws Exception;
}
/**
* Functional interface for a consumer that may throw an exception.
*
* @param the type of the input to the consumer
*/
public interface Consumer {
void accept(Z z) throws Exception;
}
T object;
java.util.function.Supplier message;
private String getMessage(){
return message == null ? "RTE": message.get();
}
private Throwing(T object) {
this.object = object;
}
/**
* Creates a new {@code Throwing} instance by invoking a supplier and providing an optional message supplier.
* If an exception occurs during the supplier's execution,
* a {@code BadSyntax} exception is thrown with the corresponding message.
*
* @param object the supplier that provides the object
* @param message the message supplier for exception handling
* @param the type of the object
* @return a new {@code Throwing} instance
* @throws BadSyntax if an exception occurs during the supplier's execution
*/
public static ThrowingAPI.NoMessage of(Supplier object, java.util.function.Supplier message) throws BadSyntax {
try {
return new Throwing<>(object.get());
} catch (Exception e) {
throw new BadSyntax(e.getMessage(), e);
}
}
/**
* Creates a new {@code Throwing} instance by invoking a supplier and providing a formatted message.
* If an exception occurs during the supplier's execution, a {@code BadSyntax} exception is thrown with the formatted message.
*
* @param object the supplier that provides the object
* @param hurlMessage the message format string for exception handling
* @param parameters the parameters to be formatted in the message
* @param the type of the object
* @return a new {@code Throwing} instance
* @throws BadSyntax if an exception occurs during the supplier's execution
*/
public static ThrowingAPI.NoMessage of(Supplier object, String hurlMessage, Object... parameters) throws BadSyntax {
return of(object, () -> String.format(hurlMessage, parameters));
}
/**
* Creates a new {@code Throwing} instance by invoking a supplier with an empty message.
* If an exception occurs during the supplier's execution, a {@code BadSyntax} exception is thrown with an empty message.
*
* @param object the supplier that provides the object
* @param the type of the object
* @return a new {@code Throwing} instance
* @throws BadSyntax if an exception occurs during the supplier's execution
*/
public static ThrowingAPI.NoMessage of(Supplier object) throws BadSyntax {
return of(object, () -> "");
}
/**
* Sets a custom message supplier for the current {@code Throwing} instance.
*
* @param message the message supplier
* @return the current {@code Throwing} instance with the updated message supplier
*/
public ThrowingAPI.HasMessage hurl(java.util.function.Supplier message) {
final var it = new Throwing<>(object);
it.message = message;
return it;
}
/**
* Sets a formatted message using the given format string and parameters as the custom message supplier for the current {@code Throwing} instance.
*
* @param format the format string for the message
* @param parameters the parameters to be formatted in the message
* @return the current {@code Throwing} instance with the updated message supplier
*/
public ThrowingAPI.HasMessage hurl(String format, Object... parameters) {
return hurl(() -> String.format(format, parameters));
}
/**
* Throws a {@code BadSyntax} exception if the given condition is {@code true}.
* The exception message is obtained from the current message supplier.
*
* @param condition the boolean condition
* @return the current {@code Throwing} instance
* @throws BadSyntax if the condition is {@code true}
*/
public ThrowingAPI.NoMessage when(boolean condition) throws BadSyntax {
if (condition) {
throw new BadSyntax(getMessage());
}
return of(() -> object);
}
/**
* Throws a {@code BadSyntax} exception if the given predicate evaluates to {@code true} for the object held by this {@code Throwing} instance.
* The exception message is obtained from the current message supplier.
*
* @param condition the predicate condition
* @return the current {@code Throwing} instance
* @throws BadSyntax if the condition is {@code true}
*/
public ThrowingAPI.NoMessage when(Predicate condition) throws BadSyntax {
return when(condition.test(object));
}
/**
* Throws a {@code BadSyntax} exception if the given condition is {@code true}.
* The consumer is executed on the object held by this {@code Throwing} instance if the condition is {@code true}.
* If an exception occurs during the consumer's execution, a {@code BadSyntax} exception is thrown with the current message.
*
* @param condition the boolean condition
* @param consumer the consumer to execute on the object
* @return the current {@code Throwing} instance
* @throws BadSyntax if the condition is {@code true} or an exception occurs during the consumer's execution
*/
public ThrowingAPI.NoMessage when(boolean condition, Consumer consumer) throws BadSyntax {
if (condition) {
try {
consumer.accept(object);
} catch (Exception e) {
throw new BadSyntax( getMessage(), e);
}
}
return of(() -> object);
}
public ThrowingAPI.NoMessage when(boolean condition, java.util.function.Consumer consumer) throws BadSyntax {
return when(condition, (Consumer) consumer::accept);
}
/**
* Throws a {@code BadSyntax} exception if the given predicate evaluates to {@code true} for the object held by this {@code Throwing} instance.
* The consumer is executed on the object if the condition is {@code true}.
* If an exception occurs during the consumer's execution, a {@code BadSyntax} exception is thrown with the current message.
*
* @param condition the predicate condition
* @param consumer the consumer to execute on the object
* @return the current {@code Throwing} instance
* @throws BadSyntax if the condition is {@code true} or an exception occurs during the consumer's execution
*/
public ThrowingAPI.NoMessage when(Predicate condition, Consumer consumer) throws BadSyntax {
return when(condition.test(object), consumer);
}
public ThrowingAPI.NoMessage when(Predicate condition, java.util.function.Consumer consumer) throws BadSyntax {
return when(condition, (Consumer) consumer::accept);
}
/**
* Throws a {@code BadSyntax} exception if the object held by this {@code Throwing} instance is an instance of the given class.
* The consumer is executed on the object if the condition is met.
* If an exception occurs during the consumer's execution, a {@code BadSyntax} exception is thrown with the current message.
*
* @param condition the class condition
* @param consumer the consumer to execute on the object
* @param the type of the class
* @return the current {@code Throwing} instance
* @throws BadSyntax if the condition is met or an exception occurs during the consumer's execution
*/
public ThrowingAPI.NoMessage when(Class condition, Consumer consumer) throws BadSyntax {
if (condition.isAssignableFrom(object.getClass())) {
try {
consumer.accept(condition.cast(object));
} catch (Exception e) {
throw new BadSyntax(getMessage(), e);
}
}
return of(() -> object);
}
public ThrowingAPI.NoMessage when(Class condition, java.util.function.Consumer consumer) throws BadSyntax {
return when(condition, (Consumer) consumer::accept);
}
/**
* Applies a mapping function to the object held by this {@code Throwing} instance and returns a new {@code Throwing} instance with the transformed object.
* If an exception occurs during the function's execution, a {@code BadSyntax} exception is thrown with the current message.
*
* @param function the mapping function
* @param the type of the resulting object
* @return a new {@code Throwing} instance with the transformed object
* @throws BadSyntax if an exception occurs during the function's execution
*/
public ThrowingAPI.NoMessage map(Function function) throws BadSyntax {
return of(() -> function.apply(object), message);
}
public ThrowingAPI.NoMessage map(java.util.function.Function function) throws BadSyntax {
return map((Function) function::apply);
}
/**
* Applies a mapping function to the object held by this {@code Throwing} instance and returns a new {@code Throwing} instance with the transformed object.
* If an exception occurs during the function's execution, a {@code BadSyntax} exception is thrown with the provided message.
*
* @param function the mapping function
* @param message the message supplier for exception handling
* @param the type of the resulting object
* @return a new {@code Throwing} instance with the transformed object
* @throws BadSyntax if an exception occurs during the function's execution
*/
public ThrowingAPI.NoMessage map(Function function, java.util.function.Supplier message) throws BadSyntax {
return of(() -> function.apply(object), message);
}
/**
* Applies a mapping function to the object held by this {@code Throwing} instance and returns a new {@code Throwing} instance with the transformed object.
* If an exception occurs during the function's execution, a {@code BadSyntax} exception is thrown with the formatted message.
*
* @param function the mapping function
* @param hurlMessage the message format string for exception handling
* @param parameters the parameters to be formatted in the message
* @param the type of the resulting object
* @return a new {@code Throwing} instance with the transformed object
* @throws BadSyntax if an exception occurs during the function's execution
*/
public ThrowingAPI.NoMessage map(Function function, String hurlMessage, Object... parameters) throws BadSyntax {
return of(() -> function.apply(object), () -> String.format(hurlMessage, parameters));
}
/**
* Casts the object held by this {@code Throwing} instance to the specified class type and returns a new {@code Throwing} instance with the casted object.
* If an exception occurs during the casting, a {@code BadSyntax} exception is thrown with the current message.
*
* @param klass the class to cast the object to
* @param the type of the resulting object
* @return a new {@code Throwing} instance with the cast object
* @throws BadSyntax if an exception occurs during the casting
*/
public ThrowingAPI.NoMessage cast(Class klass) throws BadSyntax {
if( klass == String.class ) {
return of(() -> (K)String.valueOf(object), message);
}
return of(() -> klass.cast(object), message);
}
/**
* Retrieves the object held by this {@code Throwing} instance.
*
* @return the object
*/
public T get() {
return object;
}
}