Package net.groboclown.retval

Interface RetNullable<T>

Type Parameters:

T - type of the contained value

All Superinterfaces:

ProblemContainer, ValuedProblemContainer<T>

All Known Implementing Classes:

MonitoredReturnProblem, MonitoredReturnValue, SimpleReturnProblem, SimpleReturnValue

public interface RetNullable<T>
extends ValuedProblemContainer<T>, ProblemContainer

A problem container that contains a nullable value or problems, but not both.

Method Summary

Modifier and Type	Method	Description
java.util.Optional<T>	asOptional()	Convert the value into an optional typed value.
RetVoid	consume(java.util.function.Consumer<T> consumer)	Pass the value of this instance to the consumer, only if there are no problems.
default RetVoid	consumeIfNonnull(NonnullConsumer<T> consumer)	If this value has a problem, then it is returned as a RetVoid.
default RetVal<T>	defaultAs(T defaultValue)	Returns this object as a RetVal if it is not null, otherwise a value with the returned value.
default <R> RetVal<R>	defaultOrMap(R defaultValue, NonnullFunction<T,R> func)	If this value has a problem, then it is returned.
default <R> RetVal<R>	defaultOrThen(R defaultValue, NonnullFunction<T,RetVal<R>> func)	If this value has a problem, then it is returned.
<V> RetNullable<V>	forwardNullableProblems()	Forward this instance as a nullable with a different value type, but only if it has problems.
<V> RetVal<V>	forwardProblems()	Forward this object to RetVal instance, possibly as a different value type.
RetVoid	forwardVoidProblems()	Forward this instance as a value-less object, but only if it has problems.
static <T> RetNullable<T>	fromProblem(java.util.Collection<Problem> problem, java.util.Collection<Problem>... problems)	Create a nullable return object from collections of problems.
static <T> RetNullable<T>	fromProblem(Problem problem, Problem... problems)	Create a nullable return object with at least one problem.
static <T> RetNullable<T>	fromProblems(java.util.Collection<ProblemContainer> problem, java.util.Collection<ProblemContainer>... problems)
static <T> RetNullable<T>	fromProblems(ProblemContainer problem, ProblemContainer... problems)
T	getValue()	Get the value stored in this object, even if it has problems.
<R> RetVal<R>	map(NonnullReturnFunction<T,R> func)	Return a non-null RetVal value, using a function that returns a non-null value, taking the current non-null value as an argument.
<R> RetNullable<R>	mapNullable(java.util.function.Function<T,R> func)	If this instance has no problems, then it runs the parameter with the current value.
default <R> RetNullable<R>	nullOrMap(NonnullParamFunction<T,R> func)	If this value has a problem, then it is returned.
default <R> RetNullable<R>	nullOrThenNullable(NonnullFunction<T,RetNullable<R>> func)	If this value has a problem, then it is returned.
static <T> RetNullable<T>	ok(T value)	Create a return object with a possibly null value and no problems.
RetVoid	produceVoid(NonnullReturnFunction<T,RetVoid> func)	Pass the value of this instance to the consumer, only if there are no problems.
default RetVoid	produceVoidIfNonnull(NonnullFunction<T,RetVoid> func)	If this value has a problem, then it is returned as a RetVoid.
default RetVal<T>	requireNonNull(Problem problem, Problem... problems)	Require that this value contains a non-null value, otherwise produce a value with the problem arguments.
java.util.Optional<T>	requireOptional()	Convert the value into an optional typed value only if there are no problems.
T	result()	Get the result.
default T	result(T defaultValue)	Get the stored value, or, if the stored value is null, return the non-null argument.
<R> RetVal<R>	then(NonnullReturnFunction<T,RetVal<R>> func)	Return a non-null RetVal value using a function that itself returns a RetVal, taking the current non-nullable value as an argument.
<R> RetNullable<R>	thenNullable(NonnullReturnFunction<T,RetNullable<R>> func)	Return a non-null RetNullable value using a function that itself returns a RetNullable, taking the current non-null value as an argument.
RetNullable<T>	thenRunNullable(java.lang.Runnable runner)	Run the parameter, only if this instance has no problems.
RetNullable<T>	thenRunNullable(java.util.function.Consumer<T> consumer)	Run the consumer with the current value, only if this instance has no problems.
RetNullable<T>	thenValidate(java.util.function.Function<T,ProblemContainer> checker)	Validate the value in the checker.
RetVoid	thenVoid(java.util.function.Consumer<T> consumer)	Pass the value of this instance to the consumer, only if there are no problems.
RetVoid	thenVoid(NonnullReturnFunction<T,RetVoid> func)	Pass the value of this instance to the consumer, only if there are no problems.

Methods inherited from interface net.groboclown.retval.ProblemContainer

anyProblems, debugProblems, hasProblems, isOk, isProblem, joinProblemsWith, validProblems

Method Detail

ok

@Nonnull
static <T> RetNullable<T> ok(@Nullable
                             T value)

Create a return object with a possibly null value and no problems.

Type Parameters:

T - type of the return object.

Parameters:

value - value to set in the return object.

Returns:

the return object, containing the value passed as argument and no problems.

fromProblem

@Nonnull
static <T> RetNullable<T> fromProblem(@Nonnull
                                      Problem problem,
                                      @Nonnull
                                      Problem... problems)

Create a nullable return object with at least one problem.

By taking the argument form of (Problem, Problem...), this method allows for taking 1 or more problem values as variable length arguments (e.g. RetNullable.fromProblem(a, b, c)), while forcing the list of problems to be non-empty.

Type Parameters:

T - type of the return object; not directly used, because the object will have no value associated with it.

Parameters:

problem - the first problem to add to the return object.

problems - optional list of additional problems

Returns:

the return object with problems.

fromProblem

@SafeVarargs
@Nonnull
static <T> RetNullable<T> fromProblem(@Nonnull
                                      java.util.Collection<Problem> problem,
                                      @Nonnull
                                      java.util.Collection<Problem>... problems)

Create a nullable return object from collections of problems.

Type Parameters:

T - type of the return object; not directly used, because the object will have no value associated with it.

Parameters:

problem - the first problem collection to add to the return object.

problems - optional list of additional problem collections.

Returns:

the return object with problems.

Throws:

java.lang.IllegalArgumentException - if the collection arguments contain no problems.

fromProblems

@Nonnull
static <T> RetNullable<T> fromProblems(@Nonnull
                                       ProblemContainer problem,
                                       @Nonnull
                                       ProblemContainer... problems)

fromProblems

@SafeVarargs
@Nonnull
static <T> RetNullable<T> fromProblems(@Nonnull
                                       java.util.Collection<ProblemContainer> problem,
                                       @Nonnull
                                       java.util.Collection<ProblemContainer>... problems)

getValue

@Nullable
T getValue()

Get the value stored in this object, even if it has problems. Note that this will return null if the value is null or if it has problems.

This is usually helpful for log messages where a correctness check would impose extra runtime overhead that logging doesn't care about. This can also be used to return a simple value to other parts of a program that use null to indicate an invalid setup but that are separate from user notifications.

Specified by:

getValue in interface ValuedProblemContainer<T>

Returns:

the stored value

asOptional

@Nonnull
java.util.Optional<T> asOptional()

Convert the value into an optional typed value. Note that doing this will lose any problem state, so checking for problems should be done before calling this.

This function has limited use. It's provided here to allow support for systems that use Optional values.

Returns:

the value as an optional type. No checks are made against the problem state.

result

@Nullable
T result()

Get the result. If this instance has problems, then a runtime exception is thrown. Therefore, it's necessary to perform a validity check before calling.

Returns:

the stored value, possibly null.

Throws:

java.lang.IllegalStateException - if there are problems

result

@Nonnull
default T result(@Nonnull
                 T defaultValue)

Get the stored value, or, if the stored value is null, return the non-null argument. If this value is a problem, then an exception is raised.

Parameters:

defaultValue - value to return if the stored value is null.

Returns:

the stored value, or the defaultValue if the stored value is null.

Throws:

java.lang.IllegalStateException - if there are problems

requireOptional

@Nonnull
java.util.Optional<T> requireOptional()

Convert the value into an optional typed value only if there are no problems.

Returns:

the value as an optional type.

Throws:

java.lang.IllegalStateException - if there are problems

forwardProblems

@Nonnull
<V> RetVal<V> forwardProblems()

Forward this object to RetVal instance, possibly as a different value type. This will only work when the instance has problems.

The most common use case is when a value construction requires multiple steps, and an early step requires early exit from the function. This allows a memory efficient type casting of the problems to the construction function's type.

Type Parameters:

V - altered type.

Returns:

the type-altered version

Throws:

java.lang.IllegalStateException - if this instance does not have problems.

forwardNullableProblems

@Nonnull
<V> RetNullable<V> forwardNullableProblems()

Forward this instance as a nullable with a different value type, but only if it has problems. If it does not have problems, then a runtime exception is thrown.

The most common use case is when a value construction requires multiple steps, and an early step requires early exit from the function. This allows a memory efficient type casting of the problems to the construction function's type.

Type Parameters:

V - destination type

Returns:

the value, only if this instance has problems.

forwardVoidProblems

@Nonnull
RetVoid forwardVoidProblems()

Forward this instance as a value-less object, but only if it has problems. If it does not have problems, then a runtime exception is thrown.

The most common use case is when a value construction requires multiple steps, and an early step requires early exit from the function. This allows a memory efficient type casting of the problems to the construction function's type.

Returns:

the value, only if this instance has problems.

thenValidate

@Nonnull
RetNullable<T> thenValidate(@Nonnull
                            java.util.function.Function<T,ProblemContainer> checker)

Validate the value in the checker. The checker can perform any amount of validation against the value as necessary, and returns an optional container of problems. If no problem is found, the checker can return null.

Be careful with over-using this method. ValueBuilder and ProblemCollector provide better solutions for constructing validation problems within a method. This particular method finds practical use when a builder method returns an initially valid value, then another method performs cross-value validation.

Parameters:

checker - function that checks the validity of the value.

Returns:

a retval with additional problems, or this value if no problem is found.

then

@Nonnull
<R> RetVal<R> then(@Nonnull
                   NonnullReturnFunction<T,RetVal<R>> func)

Return a non-null RetVal value using a function that itself returns a RetVal, taking the current non-nullable value as an argument. The function is called only if this object has no problem. If it has a problem, then the current list of problems is returned as the new type.

This is similar to map(NonnullReturnFunction), but logically different. This method implies the functional argument will use the value and perform new processing to create a different value.

Type Parameters:

R - type of the returned value.

Parameters:

func - functional object that returns a RetVal and takes the current value as argument.

Returns:

the problems of the current value, or the object returned by the function if there are no problems (but the returned value may have its own set of problems).

map

@Nonnull
<R> RetVal<R> map(@Nonnull
                  NonnullReturnFunction<T,R> func)

Return a non-null RetVal value, using a function that returns a non-null value, taking the current non-null value as an argument. The function is called only if this object has no problem. If it has a problem, then the current list of problems is returned as the new type.

This is similar to then(NonnullReturnFunction), but logically different. This method implies the functional argument performs a transformation of the data type into another one without validation checks.

Type Parameters:

R - type of the returned value.

Parameters:

func - functional object that takes the current value as argument, and returns a transformed value.

Returns:

the problem of the current value, if it is a problem, or the object returned by the function.

thenNullable

@Nonnull
<R> RetNullable<R> thenNullable(@Nonnull
                                NonnullReturnFunction<T,RetNullable<R>> func)

Return a non-null RetNullable value using a function that itself returns a RetNullable, taking the current non-null value as an argument. The function is called only if this object has no problem.

This is similar to mapNullable(Function), but logically different. This method implies the functional argument will use the value and perform new processing to create a different value.

Type Parameters:

R - type of the returned value.

Parameters:

func - functional object that returns a RetNullable and takes the current value as argument.

Returns:

the problem of the current value, if it is a problem, or the object returned by the supplier.

mapNullable

@Nonnull
<R> RetNullable<R> mapNullable(@Nonnull
                               java.util.function.Function<T,R> func)

If this instance has no problems, then it runs the parameter with the current value. The returned value, which may be null, is wrapped in a nullable value. If this instance has problems, then the problem list is returned and the parameter is not run.

This is similar to thenNullable(NonnullReturnFunction), but logically different. This method implies the functional argument performs a transformation of the data type into another one without validation checks.

Type Parameters:

R - return value type

Parameters:

func - the function to run.

Returns:

a transformed version of this object.

thenRunNullable

@Nonnull
RetNullable<T> thenRunNullable(@Nonnull
                               java.lang.Runnable runner)

Run the parameter, only if this instance has no problems.

Parameters:

runner - the runnable to execute if no problems exist

Returns:

this instance

thenRunNullable

@Nonnull
RetNullable<T> thenRunNullable(@Nonnull
                               java.util.function.Consumer<T> consumer)

Run the consumer with the current value, only if this instance has no problems.

Parameters:

consumer - the consumer of this value to run if no problems exist

Returns:

this instance.

thenVoid

@Nonnull
RetVoid thenVoid(@Nonnull
                 java.util.function.Consumer<T> consumer)

Pass the value of this instance to the consumer, only if there are no problems. Return a void version of this instance.

A note about usage: if the argument is a lambda that ignores the argument, then the compiler will fail due to an ambiguous call. There exist some use cases where the argument value is no longer needed and can be safely ignored; for those scenarios, use consume(Consumer).

This call will lose the contained value on return, so it's used to pass on the value to another object.

Parameters:

consumer - consumer of this value.

Returns:

a response that contains the problem state of the current value.

thenVoid

@Nonnull
RetVoid thenVoid(@Nonnull
                 NonnullReturnFunction<T,RetVoid> func)

Pass the value of this instance to the consumer, only if there are no problems. Return the function's value.

A note about usage: if the argument is a lambda that ignores the argument, then the compiler will fail due to an ambiguous call. There exist some use cases where the argument value is no longer needed and can be safely ignored; for those scenarios, use produceVoid(NonnullReturnFunction).

This call will lose the contained value on return, so it's used to pass on the value to another object.

Parameters:

func - consumer of this value.

Returns:

a response that contains the problem state of the current value.

consume

@Nonnull
RetVoid consume(@Nonnull
                java.util.function.Consumer<T> consumer)

Pass the value of this instance to the consumer, only if there are no problems. Return a void version of this instance.

This call will lose the contained value on return, so it's used to pass on the value to another object.

Parameters:

consumer - consumer of this value.

Returns:

a response that contains the problem state of the current value.

produceVoid

@Nonnull
RetVoid produceVoid(@Nonnull
                    NonnullReturnFunction<T,RetVoid> func)

Pass the value of this instance to the consumer, only if there are no problems. Return the function's value.

This call will lose the contained value on return, so it's used to pass on the value to another object.

Parameters:

func - consumer of this value.

Returns:

a response that contains the problem state of the current value.

requireNonNull

@Nonnull
default RetVal<T> requireNonNull(@Nonnull
                                 Problem problem,
                                 @Nonnull
                                 Problem... problems)

Require that this value contains a non-null value, otherwise produce a value with the problem arguments. If this value already has a problem, the arguments are ignored.

Parameters:

problem - problem to report if the value is null.

problems - optional other problems to report if the value is null.

Returns:

if non-null, return this value, otherwise the problem arguments.

Since:

2.2.0

defaultAs

@Nonnull
default RetVal<T> defaultAs(@Nonnull
                            T defaultValue)

Returns this object as a RetVal if it is not null, otherwise a value with the returned value. If this value has a problem, that is still returned.

Parameters:

defaultValue - value to use if this object contains a null value.

Returns:

the value with a non-null result, using the parameter if this object contains a null value.

Since:

2.2.0

consumeIfNonnull

@Nonnull
default RetVoid consumeIfNonnull(@Nonnull
                                 NonnullConsumer<T> consumer)

If this value has a problem, then it is returned as a RetVoid. If it contains a null value, then the equivalent of RetVoid.ok() is returned. Otherwise, the consumer is called with the value, and RetVoid.ok() is returned.

Parameters:

consumer - consumer called with the value if there are no problems and the value is non-null.

Returns:

the problems or a problem-free void value.

Since:

2.2.0

produceVoidIfNonnull

@Nonnull
default RetVoid produceVoidIfNonnull(@Nonnull
                                     NonnullFunction<T,RetVoid> func)

If this value has a problem, then it is returned as a RetVoid. If it contains a null value, then the equivalent of RetVoid.ok() is returned. Otherwise, the consumer is called with the value, and RetVoid.ok() is returned.

Parameters:

func - called with the value if there are no problems and the value is non-null, and the return value is returned by this call.

Returns:

the problems or a problem-free void value.

Since:

2.3.0

defaultOrMap

@Nonnull
default <R> RetVal<R> defaultOrMap(@Nonnull
                                   R defaultValue,
                                   @Nonnull
                                   NonnullFunction<T,R> func)

If this value has a problem, then it is returned. If the stored value is null, then defaultValue is returned. If the stored value is non-null, then it is passed to the function and returned.

Type Parameters:

R - mapped-to value type

Parameters:

defaultValue - value to return if the stored value is null.

func - function to process the stored value if it is non-null.

Returns:

this value's problems, or the mapped-to value, or the default value.

Since:

2.2.0

defaultOrThen

@Nonnull
default <R> RetVal<R> defaultOrThen(@Nonnull
                                    R defaultValue,
                                    @Nonnull
                                    NonnullFunction<T,RetVal<R>> func)

If this value has a problem, then it is returned. If the stored value is null, then defaultValue is returned. If the stored value is non-null, then it is passed to the function and returned.

Type Parameters:

R - mapped-to value type

Parameters:

defaultValue - value to return if the stored value is null.

func - function to process the stored value if it is non-null.

Returns:

this value's problems, or the mapped-to value, or the default value.

Since:

2.2.0

nullOrMap

@Nonnull
default <R> RetNullable<R> nullOrMap(@Nonnull
                                     NonnullParamFunction<T,R> func)

If this value has a problem, then it is returned. If the stored value is null, then null is returned. If the stored value is non-null, then it is passed to the function and returned.

Type Parameters:

R - mapped-to value type

Parameters:

func - function to process the stored value if it is non-null.

Returns:

this value's problems, or the mapped-to value, or the default value.

Since:

2.2.0

nullOrThenNullable

@Nonnull
default <R> RetNullable<R> nullOrThenNullable(@Nonnull
                                              NonnullFunction<T,RetNullable<R>> func)

If this value has a problem, then it is returned. If the stored value is null, then null is returned. If the stored value is non-null, then it is passed to the function and returned.

Type Parameters:

R - mapped-to value type

Parameters:

func - function to process the stored value if it is non-null.

Returns:

this value's problems, or the mapped-to value, or the default value.

Since:

2.2.0