FResult is a powerful and expressive counterpart to java.util.Optional used for
neatly handling errors. You can suppress all errors and immediately get a value:
final String s = Result.suppress(() -> readFile("myFile.txt"))
.expect("That didn't work!");Or, be extremely specific:
final String s = Result
.define(FileNotFoundException.class, e -> log.warn("Missing file: {}", e))
.define(IllegalArgumentException.class, Result::THROW)
.define(IOException.class, Result::WARN)
.suppressNullable(() -> readFile("myFile.txt"))
.ifEmpty(() -> log.warn("File was empty!"))
.ifErr(e -> log.warn("Couldn't read file!"))
.ifOk(t -> log.info("Good job!"))
.defaultIfEmpty(() -> "Didn't want a book")
.resolve(e -> "Couldn't read the book")
.expose();This interface is capable of completely replacing the standard try-catch and try-with-resources notations in Java. It has two essential modes of use:
- A better return type for functions that use standard error handling procedures
- A wrapper around functions that do not.
FResult is available on Maven Central! To use it in your project, add the following dependency in your build.gradle or pom.xml:
implementation group: 'com.personthecat', name: 'fresult', version: '3.0'Let's take a look at some examples of methods that use this new return type and then examine how they would be applied.
// Return the product of each block.
public static Result<String, IOException> betterReturn() {
final File f = getFile();
try {
return Result.ok(getContents(f));
} catch (final IOException e) {
return Result.err(e);
}
}
// Create and return a new error directly.
public static Result<String, IOException> betterReturnAlt() {
final File f = getFile();
return testConditions(f)
? Result.ok(getContents(f))
: Result.err(new IOException());
}Each of these methods returns a complete result. This means that any error present inside of the wrapper is effectively reifiable. In other words, it contains a knowable type and thus can be safely interacted with.
FResult provides a full suite of functional utilities for interacting with the underlying values and errors in this type.
Here, you can see a few of those methods in action:
// Handle all outcome scenarios.
final Result<String, IOException> r1 = betterReturn()
.ifErr(Result::WARN) // Output a warning message
.ifOk(ContentConsumer::apply); // Consume the text output
// Transform the data into a common type.
final int numLines = r1
.fold(t -> t.lines().size(), e -> 0);
// Immediately supply an alternate value.
final String output = betterReturnAlt()
.orElseGet(String::new);
// Map the underlying data to a new type.
final int hashCode = betterReturnAlt()
.map(Object::hashCode)
.orElse(0);Now let's look at the second use case in which we're wrapping a standard, throwing method.
// Standard conventions to be wrapped.
public static String toWrap() throws IOException {
final File f = getFile();
return getContents(f);
}FResult provides a series of factory methods for wrapping standard error-prone
conventions, including #of, #suppress, #nullable, #with, #define,
#resolve, and more.
Let's start with the first (and most important) option: Result#of. The first
thing you'll notice is that the return type is not assignable to Result<T, E>.
// Generate instructions for wrapping this method.
final PartialResult<String, IOException> r1 = Result.of(Name::toWrap);
// Consume these instructions and get a Result<T, E>.
final Result<String, IOException> r2 = r1.ifErr(e -> log.warn("Oops!"));The output of Result#of is a type of Result$Pending, which implements
PartialResult<T, E>. This name has two very important implications:
- The result is lazily-evaluated and does not exist yet.
- The wrapper does not provide a complete set of utilities. In other words, it is an incomplete result.
The reason for this type of design is the product of type erasure, which will
be discussed at the end of this article. In short, when a method
returns a PartialResult, you must acknowledge the error.
Alternatively, if you would like to simply ignore the specific type of error
being returned, you can employ Pending#isAnyErr, or Pending#expectAnyErr.
Also see Result#suppress for returning a complete Result<T, Throwable> which
may contain any kind of error. Here's how that would look:
// No need to acknowledge the error, as it can be any type.
final Result<String, Throwable> r1 = Result.suppress(Name::toWrap);
// Optionally discard the error and directly expose the contents.
final String r2 = Result.suppress(Name::toWrap)
.resolve(e -> "") // Type must now be a Result$Value
.expose(); // The data can safely be exposedFResult is also capable of wrapping methods that may return null. This functionality
if provided via OptionalResult and PartialOptionalResult. Below are a few of the
factory methods provided for handling nullable types.
Result#nullable(T)->OptionalResultResult#nullable(ThrowingSupplier<T, E>)->PartialOptionalResultResult#nullable(Optional<T>)->OptionalResultResult#nullable(ThrowingOptionalSupplier<T, E>)->PartialOptionalResult
Let's see what it looks like to use these wrappers:
// Known types (OptionalResult)
final Object r1 = Result.nullable(potentiallyNullValue)
.orElseGet(Object::new); // Alternate value if null
// Unknown types (PartialOptionalResult)
final Object r2 = Result.nullable(Name::mayReturnNullOrFail)
.ifErr(e -> log.warn("Error on output: {}", e))
.orElseGet(Object::new);Methods that wish to return nullable Result types must return an instance of
OptionalResult. Here's how that would look:
// Output may still be null even if no exception is thrown.
public OptionalResult<String, SQLException> getBook() {
try {
return Result.nullable(this.dao.getBook());
} catch (final SQLSyntaxException e) {
return Result.err(e);
}
}FResult also provides a couple of companion utilities, WithResource<R, E> and
WithResources<R1, R2, E>, which provide support for AutoCloseable resources.
Here's how you can use these methods:
// Use a single resource via method chainging
final String book = Result
.with(() -> new FileReader("book.txt")) // Get the resource
.suppress(reader -> { /* read file */ }) // Use the resource
.orElseGet(e -> ""); // Handle errors
// Use a single resource in one method
final String book = Result.with(() -> new FileReader("book.txt"), reader -> {
// read file
}).orElseGet(e -> "");
// Use multiple resources
final String book = Result
.with(() -> new FileReader("book.txt"))
.with(SecondResource::new) // Either a supplier or a function
.suppress((reader, second) -> { /* read file */ })
.orElseGet(e -> "");FResult provides a couple of companion utilities designed for handled multiple different types of exceptions individually. Let's explore these utilities and see how they can enable you to be very specific in handling errors.
We'll start by defining a Protocol, which contains a set of procedures for
handling different errors.
final Protocol p = Result
.define(FileNotFoundException.class, Result::THROW) // Crash if not found
.define(SecurityException.class, Result::THROW) // Or if the program lacks permission.
.define(IOException.class, Result::WARN); // All other IO issues can be ignored.This object can be used to spawn a new Result or can be stored somewhere and be
passed into multiple Result#orElseTry handlers and be reused.
final Result<String, Throwable> r = Result
.define(FileNotFound.class, e -> log.warn("Error founnd: {}", e))
.define(RuntimeException.class, Result::THROW) // Exit thread.
.suppress(() -> readFile("myFile.txt"));FResult also provides a Resolver<T>, which contains a set of procedures for
resolving different exceptions to explicit values. Its use is very similar to that
of Protocol.
final String status s = Result
.resolve(FileNotFound.class, e -> "Couldn't find it!")
.resolve(RuntimeException.class, e -> "Something else went wrong!")
.suppress(() -> readFile("myFile.txt")) // A definite value is provided
.expose(); // Because this is Result$value, it may be exposed safely.FResult provides a complete set of concrete implementations representing different outcomes. If you prefer to use this type imperatively, you may check its type and cast it, allowing the underlying value or error to be exposed.
final Result<String, IOException> r = getResult();
if (r.isOk()) {
final String v = ((Value<String, IOException>) r).expose();
}Note that casting PartialResult types is especially unsafe, as the result may not
have been computed yet, and thus you should only rely on the output of #ifErr.
final Result<String, IOException> r = getPartialResult()
.ifErr(e -> log.warn("Error found: {}", e));
if (r.isErr()) {
final IOException e = ((Error<String, IOException>) r).expose();
}A good rule of thumb: if you can't assign it to Result or OptionalResult, don't
use it.
Finally, FResult also provides a couple of static factory methods for interacting with multiple known and partial results.
// Get a single Result<Void, E>
final Result<Void, Throwable> r1 = getFirstResult();
final Result<Void, Throwable> r2 = getSecondResult();
final Result<Void, Throwable> join = Result.join(r1, r2);
// Get a single Result<List<T>, E>
final Result<String, Throwable> r3 = getThirdResult();
final Result<String, Throwable> r4 = getFourthResult();
final Result<List<String>, Throwable> list = Result.collect(r3, r4);If you're unfamiliar, type erasure is the process by which generified types lose their generic parameters at runtime in Java, depending on the context in which they're used.
For this reason, it is impossible to catch an exception based on a generic type, as the exact type cannot be known at runtime. To work around this, FResult exploits Java's generic type coercion mechanics to achieve a type-safe guarantee.
Let's take a closer look:
// Output cannot contain a different exception.
final Result<String, IOException> r1 = Result.of(Name::toWrap)
.ifErr(e -> { /* handle error */ }); // Type is implicitly cast
// Acknowledge and immediately discard the exception.
final Optional<String> r2 = Result.of(Name::toWrap)
.get(e -> { /* handle error */ }); // Also resolves the typeYou should notice two things from this example:
- The use of
eimplicitly casts the underlying error to its expected type. - The output is now assignable to a standard
Result<T, E>.
FResult uses this mechanism to guarantee that an unexpected type of error can
never be caught by the wrapper. If one is, it will be rethrown as a
WrongErrorException. This is only possible because e is returned to the
call site while still being within the scope of the wrapper.
If we apply this knowledge, we can see that it becomes safe to use the output
of Result#of as a standard Result<T, E> after applying ifErr.
The following methods are considered safe and are ideal candidates for the
majority of use cases immediately after calling Result#of:
Pending#ifErr(Consumer<E>)Pending#get(Consumer<E>)Pending#fold(Function<T, U>, Function<E, U>)Pending#orElseGet(Function<E, T>)Pending#orElseTry(ThrowingFunction<E, T, E>)Pending#expectandPending#expectF
Note that if you would like to continue using the wrapper as a type of
Result<T, E>, you must always call ifErr.
Wrapping error-prone procedures in a functional interface is a lot more expressive and can be much easier to maintain. It gives callers a more convenient interface for supplying alternate values and reporting errors to the end-user.
However, this comes at a cost.
It is certainly less safe and less specific than vanilla error handling in Java, as it sometimes requires a bit of runtime reflection and only accepts one error parameter by default. It also requires a bit of memory overhead which likely has at least a minor impact on performance. For some, functional error handling may be a lot more readable than imperative error handling, but this may not apply for most Java developers, as it strays from the standard conventions they're used to.
As a result, this project is ideal for frameworks and new projects seeking to explore novel design strategies.