Package ch.codexs.util

Class Result<T,I>

java.lang.Object

ch.codexs.util.Result<T,I>

Type Parameters:

T - the type of the content.

I - the type of the issues.

public class Result<T,I>
extends java.lang.Object

Result enables to handle errors as values instead of exceptions. This basically a couple of references, one is the regular content, the other is a list of issues. The invariants are: - at least a content or one issue. - if there is a content with issues, it's considered successful anyway. - it's impossible to access the content without having gone through the potential issues.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	Result.BiCombiner<U>	Fluent combiner for two results.
static class	Result.Catcher<E extends java.lang.Throwable>
class	Result.ContentTransformer<R>	Transformer for the content.
class	Result.ElseValueProcessor	Fluent accessor to the content.
static class	Result.IssueTransformer<T,I>	Fluent transformer for the content and the issues.
class	Result.ThenValueProcessor	Fluent accessor to the content.
static interface	Result.ThrowingMapper<T,U,E extends java.lang.Throwable>	A mapper which transforms a content into another but can throw exceptions.
static interface	Result.ThrowingSupplier<T,E extends java.lang.Throwable>	A supplier for result content which can throw exceptions.
class	Result.ValueProcessor	Class to fluently access the content.

Field Summary

Fields

Modifier and Type	Field	Description
protected T	content	The actual content of the result.

Constructor Summary

Constructors

Constructor	Description
Result(T content, java.util.List<I> issues)	Construct a Result in a simple way.

Method Summary

Modifier and Type	Method	Description
static <E extends java.lang.Throwable> Result.Catcher<E>	catching(java.lang.Class<E> throwableClass)
static <T,I> Result<java.util.List<T>,I>	combineAllSuccessful(java.util.Collection<Result<T,I>> results)	Combines the provided results into one single Result<List<T>, I>.
<U> Result.BiCombiner<U>	combineWith(Result<U,I> other)	Combines this result with another one
boolean	equals(java.lang.Object o)
static <U,I> Result<U,I>	failed(I firstIssue, I... issues)	Builds a result without a content (failed).
static <U,I> Result<U,I>	failed(java.util.List<I> issues)	Builds a result without a content (failed).
<U> Result<U,I>	flatMap(java.util.function.Function<T,Result<U,I>> mapper)	Map the content (if any) to another Result.
boolean	hasFailed()	Indicates if the result has failed, in other words, is there a content in it.
int	hashCode()
Result.ElseValueProcessor	ifFailedDo(java.util.function.Consumer<java.util.List<I>> issueConsumer)	Give conditional access to the issues.
<U> Result.ContentTransformer<U>	ifFailedTransform(java.util.function.Function<java.util.List<I>,U> issueTransformer)	Transforms the issues into an output in case of missing content, using the given function.
Result.ThenValueProcessor	ifIssuesExistDo(java.util.function.Consumer<java.util.List<I>> issueConsumer)	Give conditional access to the issues.
<U> Result.IssueTransformer<U,I>	ifSucceededTransform(java.util.function.BiFunction<T,java.util.List<I>,U> mapper)	Give access to both the content and the issues in order to build an output.
java.util.List<I>	issues()	Get the issues.
<U> Result<U,I>	map(java.util.function.Function<T,U> mapper)	Map the content (if any).
<U,J> Result<U,J>	mapBoth(java.util.function.Function<T,U> contentMapper, java.util.function.Function<I,J> issueMapper)	Map both the content and the issues to build a new Result with them.
<U,E extends java.lang.Throwable> Result<U,I>	mapCatching(java.lang.Class<E> throwableClass, Result.ThrowingMapper<T,U,E> mapper, java.util.function.Function<E,I> exceptionMapper)	Maps the content but catching the potential exception that could be thrown by the mapper.
<J> Result<T,J>	mapIssues(java.util.function.Function<I,J> mapper)	Map the issues to transform them.
static <U,I> Result<U,I>	succeeded(U content)	Builds a result with a content.
static <U,I> Result<U,I>	succeeded(U content, I firstIssue, I... issues)	Builds a result with a content and issues.
static <K,T,I> Result<java.util.Map<K,T>,I>	traverse(java.util.Map<K,Result<T,I>> mapOfResults)	Group the issues and unwrap the contained map into one map of contents.
<U> U	unwrap(java.util.function.BiFunction<java.util.Optional<T>,java.util.List<I>,U> transformer)	Give access to content through an optional.
<U> U	unwrap(java.util.function.BiFunction<T,java.util.List<I>,U> ifSucceededTransformer, java.util.function.Function<java.util.List<I>,U> ifFailedTransformer)	Give conditional access to content and issues, depending on success.
Result<T,I>	withAddedIssues(I... issues)	Creates a new Result, copy of this one, but with added issues at the end.
Result<T,I>	withAddedIssues(java.lang.Iterable<I>... issueLists)	Creates a new Result, copy of this one, but with added issues at the end.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

content

protected final T content

The actual content of the result. When null, the result is considered having failed.

Constructor Detail

Result

public Result(T content,
              java.util.List<I> issues)

Construct a Result in a simple way. If the content is null, then the result is considered as failed.

Parameters:

content - An object being the content of the result.

issues - List of issues, non null.

Method Detail

succeeded

public static <U,I> Result<U,I> succeeded(U content)

Builds a result with a content.

Type Parameters:

U - The type of the content.

I - The type of the issues (empty).

Parameters:

content - non-null reference to the content to hold the returned Result.

Returns:

Result wrapping the provided content.

succeeded

@SafeVarargs
public static <U,I> Result<U,I> succeeded(U content,
                                                      I firstIssue,
                                                      I... issues)

Builds a result with a content and issues.

Type Parameters:

U - The type of the content.

I - The type of the issues.

Parameters:

content - non-null reference to the content to hold the returned Result.

firstIssue - Issue to include.

issues - Array of additional issues to include.

Returns:

Result wrapping the provided content and issues.

failed

public static <U,I> Result<U,I> failed(java.util.List<I> issues)

Builds a result without a content (failed).

Type Parameters:

U - The type of the content.

I - The type of the issues.

Parameters:

issues - The issues.

Returns:

A new Result

failed

@SafeVarargs
public static <U,I> Result<U,I> failed(I firstIssue,
                                                   I... issues)

Builds a result without a content (failed).

Type Parameters:

U - The type of the content.

I - The type of the issues.

Parameters:

firstIssue - The first issue.

issues - The following issues.

Returns:

A new Result

catching

public static <E extends java.lang.Throwable> Result.Catcher<E> catching(java.lang.Class<E> throwableClass)

Type Parameters:

E - The type of throwable to catch.

Parameters:

throwableClass - Class of the expected throwable to catch.

Returns:

Catcher to run the following supplier in a exception safe manner.

hasFailed

public boolean hasFailed()

Indicates if the result has failed, in other words, is there a content in it.

Returns:

true if the content is missing.

issues

public java.util.List<I> issues()

Get the issues.

Returns:

the issues.

map

public <U> Result<U,I> map(java.util.function.Function<T,U> mapper)

Map the content (if any).

Type Parameters:

U - The type of the mapped content.

Parameters:

mapper - Function

Returns:

A new Result with mapped content.

flatMap

public <U> Result<U,I> flatMap(java.util.function.Function<T,Result<U,I>> mapper)

Map the content (if any) to another Result.

Type Parameters:

U - The type of the mapped content.

Parameters:

mapper - Function to transform the content (if any).

Returns:

A new Result with mapped content.

mapCatching

public <U,E extends java.lang.Throwable> Result<U,I> mapCatching(java.lang.Class<E> throwableClass,
                                                                             Result.ThrowingMapper<T,U,E> mapper,
                                                                             java.util.function.Function<E,I> exceptionMapper)

Maps the content but catching the potential exception that could be thrown by the mapper.

Type Parameters:

U - Type of the content

E - Type of the expected exceptions to map to issues

Parameters:

throwableClass - The class or the superclass of the thrown exceptions.

mapper - The function mapping the content, can throw exceptions handled by the exception mapper if any

exceptionMapper - Function to map exceptions to issues

Returns:

A result in which the catch

mapIssues

public <J> Result<T,J> mapIssues(java.util.function.Function<I,J> mapper)

Map the issues to transform them.

Type Parameters:

J - The type of the mapped issues.

Parameters:

mapper - Function to transform the issues (if any).

Returns:

A new Result with mapped issues.

mapBoth

public <U,J> Result<U,J> mapBoth(java.util.function.Function<T,U> contentMapper,
                                             java.util.function.Function<I,J> issueMapper)

Map both the content and the issues to build a new Result with them.

Type Parameters:

U - The type of the mapped content.

J - The type of the mapped issues.

Parameters:

contentMapper - Function to transform the content. Will only be called if the content is present.

issueMapper - Function to transform the issues. Will only be called if the issues are present.

Returns:

Result - a new result with the mapped content and issues.

withAddedIssues

@SafeVarargs
public final Result<T,I> withAddedIssues(java.lang.Iterable<I>... issueLists)

Creates a new Result, copy of this one, but with added issues at the end.

Parameters:

issueLists - the issues to add.

Returns:

The new Result including new issues.

withAddedIssues

@SafeVarargs
public final Result<T,I> withAddedIssues(I... issues)

Creates a new Result, copy of this one, but with added issues at the end.

Parameters:

issues - the issues to add.

Returns:

The new Result including new issues.

ifIssuesExistDo

public Result.ThenValueProcessor ifIssuesExistDo(java.util.function.Consumer<java.util.List<I>> issueConsumer)

Give conditional access to the issues. The consumer is called only if there are contained issues. Can be followed by the call to a getter returning the content, null if the result has no content.

Parameters:

issueConsumer - the consumer to process issues

Returns:

ThenValueProcessor - to get the content

ifFailedDo

public Result.ElseValueProcessor ifFailedDo(java.util.function.Consumer<java.util.List<I>> issueConsumer)

Give conditional access to the issues. The consumer is called only if there is no content in the result. Can be followed by the call to a getter returning the content, null if the result has no content.

Parameters:

issueConsumer - Consumer to process issues

Returns:

ElseValueProcessor - to get the content

unwrap

public <U> U unwrap(java.util.function.BiFunction<T,java.util.List<I>,U> ifSucceededTransformer,
                    java.util.function.Function<java.util.List<I>,U> ifFailedTransformer)

Give conditional access to content and issues, depending on success.

Type Parameters:

U - The type of the output of the transformation.

Parameters:

ifSucceededTransformer - BiFunction to transform the content and the issues.

ifFailedTransformer - Function to transform the issues.

Returns:

The result of the transformation.

unwrap

public <U> U unwrap(java.util.function.BiFunction<java.util.Optional<T>,java.util.List<I>,U> transformer)

Give access to content through an optional.

Type Parameters:

U - The type of the output of the transformation.

Parameters:

transformer - BiFunction to transform the content and the issues

Returns:

The result of the transformation.

ifFailedTransform

public <U> Result.ContentTransformer<U> ifFailedTransform(java.util.function.Function<java.util.List<I>,U> issueTransformer)

Transforms the issues into an output in case of missing content, using the given function. The output is not accessible straight away but is transmitted to the returned ValueTransformer.

Type Parameters:

U - The type of the output resulting from the transformation provided

Parameters:

issueTransformer - A function to transform the issues into a value that will be returned if there was no success.

Returns:

ValueTransformer - allowing to unwrap the content and transform it into a another value in case of success

ifSucceededTransform

public <U> Result.IssueTransformer<U,I> ifSucceededTransform(java.util.function.BiFunction<T,java.util.List<I>,U> mapper)

Give access to both the content and the issues in order to build an output. If the content is absent (hasFailed() returns true) the chained issue transformation is applied.

Type Parameters:

U - The type of the mapped content.

Parameters:

mapper - The function to map both the content and the issues.

Returns:

IssueTransformer<U, I> enabling the transformation of the issues.

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

combineWith

public <U> Result.BiCombiner<U> combineWith(Result<U,I> other)

Combines this result with another one

Type Parameters:

U - the type of the mapped content.

Parameters:

other - Result to combine with.

Returns:

BiCombiner to decide how to actually combine values.

combineAllSuccessful

public static <T,I> Result<java.util.List<T>,I> combineAllSuccessful(java.util.Collection<Result<T,I>> results)

Combines the provided results into one single Result<List<T>, I>. As provided results may not be all successful, they are filtered and the resulting list may be smaller than the provided result list. On the other hand, all the issues are collected, including the one of the failed provided results.

Type Parameters:

T - The type of the content.

I - The type of the issues.

Parameters:

results - Collection of results to combine.

Returns:

Result containing the contents of the provided collection of results.

traverse

public static <K,T,I> Result<java.util.Map<K,T>,I> traverse(java.util.Map<K,Result<T,I>> mapOfResults)

Group the issues and unwrap the contained map into one map of contents. Beware that failures will disappear in the process. Then the resulting key set may be smaller than the original one. Be also aware that the grouped issues may not be easily associated with the initial keys and refer to keys no longer existing.

Type Parameters:

K - the type of the key

T - the type of the contents

I - the type of the issues

Returns:

A successful result with all the contents for successful results in one map and all the issues merged into one list.