ar.com.kfgodel.nary.api.arity

Interface MonoElement<T>

Type Parameters:

T - Type of contained element

All Superinterfaces:

Supplier<T>

All Known Subinterfaces:

Unary<T>

All Known Implementing Classes:

EmptyNary, OneElementNary

public interface MonoElement<T>
extends Supplier<T>

This type defines the protocol that Unary offers as a replacement for Optional.
Operations defined in this type makes sense when we know there's only 1 element on this instance.
It's based on Optional to be as compatible and intuitive as possible but it departs from its concepts adding own variants to simplify o complete use cases. Also makes explicit differences when there are similar methods between Stream and Optional but they have different semantics.

Because a MonoElement can contain an element, it can be used as Supplier.
Depending on its content it supply the element, or fail if its empty. Date: 12/10/19 - 21:21

Method Summary

Modifier and Type	Method and Description
Optional<T>	asOptional() Returns a native Optional instance to be used with Nary unaware code
T	get() If only one value is present in this Nary, returns the value, otherwise throws NoSuchElementException, or MoreThanOneElementException.
Unary<T>	ifAbsent(Runnable runnable) If the only value is absent invoke the given lambda, or else do nothing This Nary as Stream is consumed.
Unary<T>	ifPresent(Consumer<? super T> consumer) If the only value is present, invoke the specified consumer with the value, otherwise do nothing.
default boolean	isAbsent() Negation of isPresent().
boolean	isPresent() Return true if there is only a value present, otherwise false.
T	orElse(T other) Return the only value if present, otherwise return other.
T	orElseGet(Supplier<? extends T> other) Return the only value if present, otherwise invoke other and return the result of that invocation.
<X extends Throwable> T	orElseThrow(Supplier<? extends X> exceptionSupplier) Return the only contained value, if present, otherwise throw an exception created by the provided supplier.
Unary<T>	orElseUse(Supplier<? extends T> mapper) Returns a Nary element that is populated with the given supplier only if this Nary is empty. This method allows defining a mapping function for nary that can be empty and keep chaining other mapping definitions after that. This stream is consumed and it's assumed to have at most 1 element.

Method Detail

get

T get()
throws NoSuchElementException,
      MoreThanOneElementException

If only one value is present in this Nary, returns the value, otherwise throws NoSuchElementException, or MoreThanOneElementException. This Nary as Stream is consumed to return the value so any attempt to use it as stream will fail after this method call

Specified by:

get in interface Supplier<T>

Returns:

the non-null value held by this Nary

Throws:

NoSuchElementException - if there is no value present

MoreThanOneElementException - if there are more than one values

See Also:

Optional.get()

isPresent

boolean isPresent()
           throws MoreThanOneElementException

Return true if there is only a value present, otherwise false. This Nary as Stream is consumed.

Returns:

true if there is a value present, otherwise false

Throws:

MoreThanOneElementException - if there are more than one

See Also:

Optional.isPresent()

isAbsent

default boolean isAbsent()
                  throws MoreThanOneElementException

Negation of isPresent(). Facility method to check for missing element without having to negate

Returns:

true if there's no value to get

Throws:

MoreThanOneElementException - If there's more than one value to get as Optional

ifPresent

Unary<T> ifPresent(Consumer<? super T> consumer)
            throws MoreThanOneElementException

If the only value is present, invoke the specified consumer with the value, otherwise do nothing. This Nary as Stream is consumed.

Parameters:

consumer - block to be executed if a value is present

Returns:

this for easy method chaining

Throws:

NullPointerException - if value is present and consumer is null

MoreThanOneElementException - if there are more than one

See Also:

Optional.ifPresent(Consumer)

ifAbsent

Unary<T> ifAbsent(Runnable runnable)
           throws MoreThanOneElementException

If the only value is absent invoke the given lambda, or else do nothing This Nary as Stream is consumed.

Parameters:

runnable - The code to execute if this optional is empty

Returns:

this for easy method chaining

Throws:

MoreThanOneElementException - if there are more than one

orElse

T orElse(T other)
  throws MoreThanOneElementException

Return the only value if present, otherwise return other. This Nary as Stream is consumed.

Parameters:

other - the value to be returned if there is no value present, may be null

Returns:

the value, if present, otherwise other

Throws:

MoreThanOneElementException - if there are more than one

orElseGet

T orElseGet(Supplier<? extends T> other)
     throws MoreThanOneElementException

Return the only value if present, otherwise invoke other and return the result of that invocation. This Nary as Stream is consumed.

Parameters:

other - a Supplier whose result is returned if no value is present

Returns:

the value if present otherwise the result of other.asUni().get()

Throws:

MoreThanOneElementException - if there are more than one

orElseUse

Unary<T> orElseUse(Supplier<? extends T> mapper)
            throws MoreThanOneElementException

Returns a Nary element that is populated with the given supplier only if this Nary is empty.
This method allows defining a mapping function for nary that can be empty and keep chaining other mapping definitions after that.
This stream is consumed and it's assumed to have at most 1 element. It fails otherwise

Parameters:

mapper - The function that supplies a value if missing

Returns:

A non empty nary with this instance element or the one given by the supplier

Throws:

MoreThanOneElementException - If this instance has more than 1 element

orElseThrow

<X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier)
                             throws X extends Throwable,
                                    MoreThanOneElementException

Return the only contained value, if present, otherwise throw an exception created by the provided supplier. This Nary as Stream is consumed.

Type Parameters:

X - Type of the exception to be thrown

Parameters:

exceptionSupplier - The supplier which will return the exception to be thrown

Returns:

the present value

Throws:

X - if there is no value present

NullPointerException - if no value is present and exceptionSupplier is null

MoreThanOneElementException - if there are more than one

X extends Throwable

asOptional

Optional<T> asOptional()
                throws MoreThanOneElementException

Returns a native Optional instance to be used with Nary unaware code

Returns:

The native instance that represents this Nary content

Throws:

MoreThanOneElementException - if there are more than one elements in this instance