no.digipost.util

Interface AtMostOne<T>

Type Parameters:

T - The type of the contained object.

All Superinterfaces:

ViewableAsOptional<T>

public interface AtMostOne<T>
extends ViewableAsOptional<T>

This class offers a subtle functionality which is not available in the Collection API of Java: to retrieve the only element that is expected to be present, and, importantly, throw an exception if there are elements that will be discarded if assuming that there is at most one element present.

If this funcitonality is needed for streams, use the using DiggCollectors.allowAtMostOne() collector instead with Stream.collect(..).

Nested Class Summary

Nested classes/interfaces inherited from interface no.digipost.util.ViewableAsOptional

ViewableAsOptional.Single<V>, ViewableAsOptional.TooManyElements

Method Summary

Modifier and Type	Method and Description
default Optional<T>	discardRemaining() This allows to just pick out the first element, and basically offers the same functionality as Stream.findFirst().
static <T> AtMostOne<T>	from(Iterable<T> iterable)
<X extends Throwable> Optional<T>	orElse(ThrowingRunnable<X> handleUnexpectedMultipleElements) How to handle if there actually are multiple elements available when only at most one is expected.
default <X extends Throwable> Optional<T>	orIfExcessiveThrow(Supplier<X> exceptionSupplier) Pick out the single contained element, or throw the given exception if there are excessive (more than one) elements available.
default Optional<T>	toOptional() Get the at most single contained element, or throw a TooManyElements exception if there are excessive elements available.

Method Detail

from

static <T> AtMostOne<T> from(Iterable<T> iterable)

discardRemaining

default Optional<T> discardRemaining()

This allows to just pick out the first element, and basically offers the same functionality as Stream.findFirst().

Returns:

The first element if it exists, or Optional.empty() if no elements exist.

toOptional

default Optional<T> toOptional()

Get the at most single contained element, or throw a TooManyElements exception if there are excessive elements available. If you need control over the thrown exception, use orIfExcessiveThrow(Supplier).

Specified by:

toOptional in interface ViewableAsOptional<T>

Returns:

The single element if it exists, or else Optional.empty() if no elements exist or the single element is null.

orIfExcessiveThrow

default <X extends Throwable> Optional<T> orIfExcessiveThrow(Supplier<X> exceptionSupplier)
                                                      throws X extends Throwable

Pick out the single contained element, or throw the given exception if there are excessive (more than one) elements available.

Parameters:

exceptionSupplier - the exception to throw if there are excessive elements available.

Returns:

The single element if it exists, or Optional.empty() if no elements exist.

Throws:

X - if there are excessive elements available.

X extends Throwable

orElse

<X extends Throwable> Optional<T> orElse(ThrowingRunnable<X> handleUnexpectedMultipleElements)
                                  throws X extends Throwable

How to handle if there actually are multiple elements available when only at most one is expected.

Parameters:

handleUnexpectedMultipleElements - the handling of the unexpected multiple elements.

Returns:

The first element if it exists, or Optional.empty() if no elements exist.

Throws:

X - if the function to handle more than one elements throws an exception.

X extends Throwable