no.digipost.util

Interface AtMostOne<T>

Type Parameters:

T - The type of the contained object.

public interface AtMostOne<T>

This class offers a subtle functionality which is not available in the Collection/Stream 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.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	AtMostOne.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(Collection<T> list)
static <T> AtMostOne<T>	from(Iterable<T> iterable)
static <T> AtMostOne<T>	from(Stream<T> stream)
default Optional<T>	get() Get the at most single contained element, or throw a AtMostOne.TooManyElements exception if there are excessive elements available.
<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.

Method Detail

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.

get

default Optional<T> get()

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

Returns:

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

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. The stream passed to this function will always contain at least two elements (the expected first element, and the excess ones).

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

from

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

from

static <T> AtMostOne<T> from(Collection<T> list)

from

static <T> AtMostOne<T> from(Stream<T> stream)