Module org.microbean.invoke

Package org.microbean.invoke

Interface OptionalSupplier<T>

Type Parameters:

T - the type of value implementations of this interface supply

All Superinterfaces:

Supplier<T>

All Known Implementing Classes:

Absence, CachingSupplier, FixedValueSupplier

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface OptionalSupplier<T>
extends Supplier<T>

A Supplier with additional contractual requirements.

An OptionalSupplier does not behave like an Optional or a CompletableFuture, despite the deliberate similarities of some method names.

An implementation of this interface is not a value-based class.

Author:

Laird Nelson

See Also:

• determinism()
• get()
• optional()

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	OptionalSupplier.Determinism	A token indicating transitory or permanent presence or absence.

Method Summary

Modifier and Type	Method	Description
default OptionalSupplier.Determinism	determinism()	Returns an OptionalSupplier.Determinism denoting the presence of values returned by this OptionalSupplier's get() method.
default T	exceptionally(Function<? super RuntimeException,? extends T> handler)	Returns either the result of invoking the get() method, if a RuntimeException does not occur, or the result of invoking the apply(Object) method on the supplied handler with any RuntimeException that does occur, including NoSuchElementException and UnsupportedOperationException instances that are used to indicate value absence.
T	get()	Returns a value, which may be null.
default <U> U	handle(BiFunction<? super T,? super RuntimeException,? extends U> handler)	Returns the result of invoking the apply(Object, Object) method on the supplied handler, supplying it with the result of an invocation of the get() method, which may be null, or any RuntimeException that an invocation of the get() method throws, including NoSuchElementException and UnsupportedOperationException instances that are used to indicate value absence.
default void	ifPresent(Consumer<? super T> action)	Invokes the accept(Object) method on the supplied action with the return value of an invocation of the get() method, which may be null, unless the get() method throws either a NoSuchElementException or an UnsupportedOperationException, indicating value absence, in which case no action is taken.
default void	ifPresentOrElse(Consumer<? super T> presentAction, Runnable absentAction)	Invokes the accept(Object) method on the supplied presentAction with the return value of an invocation of the get() method, which may be null, or, if the get() method indicates value absence by throwing either a NoSuchElementException or an UnsupportedOperationException, invokes the run() method of the supplied absentAction instead.
static <T> OptionalSupplier<T>	of()	Invokes Absence.instance() and returns the result.
static <T> OptionalSupplier<T>	of(Supplier<? extends T> supplier)	Returns an OptionalSupplier representing the supplied Supplier.
static <T> OptionalSupplier<T>	of(Supplier<? extends T> supplier, Supplier<? extends T> defaults)	Returns an OptionalSupplier that will, loosely speaking, try the supplied supplier first, and, if it throws a NoSuchElementException or an UnsupportedOperationException from its Supplier.get() method, will then try the supplied defaults.
static <T> OptionalSupplier<T>	of(OptionalSupplier.Determinism determinism, Supplier<? extends T> supplier)	Returns a new OptionalSupplier whose determinism() method will return the supplied OptionalSupplier.Determinism and whose get() method will return the result of invoking the Supplier.get() method on the supplied supplier.
static <T> OptionalSupplier<T>	of(T value)	Returns a new OptionalSupplier whose determinism() method will return OptionalSupplier.Determinism.PRESENT and whose get() method will return the supplied value.
default Optional<T>	optional()	Returns a non-null but possibly empty Optional representing this OptionalSupplier's value.
default <U> Optional<U>	optional(BiFunction<? super T,? super RuntimeException,? extends U> handler)	Invokes the handle(BiFunction) method, supplying it with the supplied handler, supplies its return value to the Optional.ofNullable(Object) method, and returns the result.
default Optional<T>	optional(Function<? super RuntimeException,? extends T> handler)	Invokes the exceptionally(Function) method, supplying it with the supplied handler, supplies its return value to the Optional.ofNullable(Object) method, and returns the result.
default T	orElse(T other)	Returns the result of invoking the get() method, which may be null, or, if the get() method indicates value absence by throwing either a NoSuchElementException or an UnsupportedOperationException, returns the supplied alternate value, which may be null.
default T	orElseGet(Supplier<? extends T> supplier)	Returns the result of invoking the get() method, which may be null, or, if the get() method indicates value absence by throwing either a NoSuchElementException or an UnsupportedOperationException, returns the result of invoking the get() method on the supplied Supplier, which may be null.
default T	orElseThrow()	Returns the result of invoking the get() method, which may be null.
default <X extends Throwable> T	orElseThrow(Supplier<? extends X> throwableSupplier)	Returns the result of invoking the get() method, which may be null, or, if the get() method indicates value absence by throwing either a NoSuchElementException or an UnsupportedOperationException, throws the return value of an invocation of the supplied Supplier's get() method.
default Stream<T>	stream()	Returns the result of invoking the Stream.of(Object) method on the return value of an invocation of the get() method, which may be null, or, if the get() method indicates value absence by throwing either a NoSuchElementException or an UnsupportedOperationException, returns the result of invoking the Stream.empty() method.

Method Details

exceptionally

default T exceptionally(Function<? super RuntimeException,? extends T> handler)

Returns either the result of invoking the get() method, if a RuntimeException does not occur, or the result of invoking the apply(Object) method on the supplied handler with any RuntimeException that does occur, including NoSuchElementException and UnsupportedOperationException instances that are used to indicate value absence.

Parameters:

handler - the exception handler; must not be null

Returns:

either the result of invoking the get() method, if a RuntimeException does not occur, or the result of invoking the apply(Object) method on the supplied handler with any RuntimeException that does occur

Throws:

NullPointerException - if handler is null

See Also:

• get()

Idempotency:

No guarantees are made about idempotency or determinism.

Nullability:

This method and its (discouraged) overrides may return null

Thread Safety:

This method itself is, and its (discouraged) overrides must be, safe for concurrent use by multiple threads, but the apply(Object) method of the supplied handler may not be.

get

T get()

Returns a value, which may be null.

This method's contract extends Supplier.get()'s contract with the following additional requirements:

• It is deliberately and explicitly permitted for implementations of this method to return null for any reason. Callers of this method must be appropriately prepared.
• If an invocation of the determinism() method, on any thread, returns any of OptionalSupplier.Determinism.ABSENT, OptionalSupplier.Determinism.DETERMINISTIC or OptionalSupplier.Determinism.PRESENT, then additional requirements apply to the implementation of this method; see the determinism() method documentation for details.
• An implementation of this method need not be deterministic if an invocation of the determinism() method returns OptionalSupplier.Determinism.NON_DETERMINISTIC.
• An implementation of this method may indicate the (possibly transitory) absence of a value by any of the following means:
  • Throwing a NoSuchElementException.
  • Throwing an UnsupportedOperationException.

Specified by:

get in interface Supplier<T>

Returns:

a value, which may be null

Throws:

NoSuchElementException - to indicate (usually transitory) absence

UnsupportedOperationException - to indicate (usually permanent) absence

See Also:

• determinism()

Idempotency:

No guarantees are made about idempotency or determinism. An ideal implementation should be idempotent. If the determinism() method returns a OptionalSupplier.Determinism that is not OptionalSupplier.Determinism.NON_DETERMINISTIC, then any implementation of this method must be deterministic.

Nullability:

Implementations of this method may, and often will, return null, even in the normal course of events.

Thread Safety:

Implementations of this method must be safe for concurrent use by multiple threads.

handle

default <U> U handle(BiFunction<? super T,? super RuntimeException,? extends U> handler)

Returns the result of invoking the apply(Object, Object) method on the supplied handler, supplying it with the result of an invocation of the get() method, which may be null, or any RuntimeException that an invocation of the get() method throws, including NoSuchElementException and UnsupportedOperationException instances that are used to indicate value absence.

The first argument to the handler will be the return value of the get() method, which may be null. The second argument to the handler will be any RuntimeException that was thrown during the invocation of the get() method, including NoSuchElementException and UnsupportedOperationException instances that are used to indicate value absence.

Type Parameters:

U - the type of the value returned

Parameters:

handler - the handler; must not be null

Returns:

the result of invoking the apply(Object, Object) method on the supplied handler, supplying it with the result of an invocation of the get() method, which may be null, or any RuntimeException that an invocation of the get() method throws, including NoSuchElementException and UnsupportedOperationException instances that are used to indicate value absence

Throws:

NullPointerException - if handler is null

See Also:

• get()

Idempotency:

No guarantees are made about idempotency or determinism.

Nullability:

This method and its (discouraged) overrides may return null.

Thread Safety:

This method is, and its (discouraged) overrides must be, safe for concurrent use by multiple threads.

ifPresent

default void ifPresent(Consumer<? super T> action)

Invokes the accept(Object) method on the supplied action with the return value of an invocation of the get() method, which may be null, unless the get() method throws either a NoSuchElementException or an UnsupportedOperationException, indicating value absence, in which case no action is taken.

Parameters:

action - the Consumer representing the action to take; must not be null

Throws:

NullPointerException - if action is null

See Also:

• get()

Idempotency:

No guarantees are made about idempotency or determinism.

Thread Safety:

This method is, and its (discouraged) overrides must be, safe for concurrent use by multiple threads, but the supplied Consumer's accept(Object) method may not be

ifPresentOrElse

default void ifPresentOrElse(Consumer<? super T> presentAction,
 Runnable absentAction)

Invokes the accept(Object) method on the supplied presentAction with the return value of an invocation of the get() method, which may be null, or, if the get() method indicates value absence by throwing either a NoSuchElementException or an UnsupportedOperationException, invokes the run() method of the supplied absentAction instead.

Parameters:

presentAction - the Consumer representing the action to take if a value is present; must not be null

absentAction - the Runnable representing the action to take if a value is absent; must not be null

Throws:

NullPointerException - if action or absentAction is null

See Also:

• get()

Idempotency:

No guarantees are made about idempotency or determinism.

Thread Safety:

This method is, and its (discouraged) overrides must be, safe for concurrent use by multiple threads, but the supplied Consumer's accept(Object) method may not be and the supplied Runnable's run() method may not be

optional

default Optional<T> optional()

Returns a non-null but possibly empty Optional representing this OptionalSupplier's value.

The default implementation of this method does not and its overrides must not return null.

The default implementation of this method catches all NoSuchElementExceptions and UnsupportedOperationExceptions and returns an empty Optional in these cases, which may not be valid for some use cases. To detect permanent versus transitory absence, potential callers should use the get() method directly or either the optional(Function) or optional(BiFunction) methods.

Returns:

a non-null but possibly empty Optional representing this OptionalSupplier's value

See Also:

• optional(BiFunction)
• get()

Idempotency:

No guarantees are made about idempotency or determinism.

Nullability:

The default implementation of this method does not, and its (discouraged) overrides must not, return null.

Thread Safety:

The default implementation of this method is, and its (discouraged) overrides must be, safe for concurrent use by multiple threads.

optional

default <U> Optional<U> optional(BiFunction<? super T,? super RuntimeException,? extends U> handler)

Invokes the handle(BiFunction) method, supplying it with the supplied handler, supplies its return value to the Optional.ofNullable(Object) method, and returns the result.

Type Parameters:

U - the type of the returned Optional

Parameters:

handler - the handler; must not be null

Returns:

the result of invoking the Optional.ofNullable(Object) method supplied with the return value of invoking the handle(BiFunction) method with the supplied handler

Throws:

NullPointerException - if handler is null

See Also:

• handle(BiFunction)
• Optional.ofNullable(Object)

Idempotency:

No guarantees are made about idempotency or determinism.

Nullability:

This method does not, and its (discouraged) overrides must not, return null.

Thread Safety:

This method is, and its (discouraged) overrides must be, safe for concurrent use by multiple threads.

optional

default Optional<T> optional(Function<? super RuntimeException,? extends T> handler)

Invokes the exceptionally(Function) method, supplying it with the supplied handler, supplies its return value to the Optional.ofNullable(Object) method, and returns the result.

Parameters:

handler - the handler; must not be null

Returns:

the result of invoking the Optional.ofNullable(Object) method supplied with the return value of invoking the exceptionally(Function) method with the supplied handler

Throws:

NullPointerException - if handler is null

See Also:

• exceptionally(Function)
• Optional.ofNullable(Object)

Idempotency:

No guarantees are made about idempotency or determinism.

Nullability:

This method does not, and its (discouraged) overrides must not, return null.

Thread Safety:

This method is, and its (discouraged) overrides must be, safe for concurrent use by multiple threads.

orElse

default T orElse(T other)

Returns the result of invoking the get() method, which may be null, or, if the get() method indicates value absence by throwing either a NoSuchElementException or an UnsupportedOperationException, returns the supplied alternate value, which may be null.

Parameters:

other - the alternate value; may be null

Returns:

the result of invoking the get() method, which may be null, or, if the get() method indicates value absence by throwing either a NoSuchElementException or an UnsupportedOperationException, returns the supplied alternate value, which may be null

See Also:

• get()

Idempotency:

No guarantees are made about idempotency or determinism.

Nullability:

This method and its (discouraged) overrides may return null.

Thread Safety:

This method is, and its (discouraged) overrides must be, safe for concurrent use by multiple threads.

orElseGet

default T orElseGet(Supplier<? extends T> supplier)

Returns the result of invoking the get() method, which may be null, or, if the get() method indicates value absence by throwing either a NoSuchElementException or an UnsupportedOperationException, returns the result of invoking the get() method on the supplied Supplier, which may be null.

Parameters:

supplier - the alternate value Supplier; must not be null

Returns:

the result of invoking the get() method, which may be null, or, if the get() method indicates value absence by throwing either a NoSuchElementException or an UnsupportedOperationException, returns the result of invoking the get() method on the supplied Supplier, which may be null

Throws:

NullPointerException - if supplier is null

See Also:

• get()

Idempotency:

No guarantees are made about idempotency or determinism.

Nullability:

This method and its (discouraged) overrides may return null.

Thread Safety:

This method is, and its (discouraged) overrides msut be, safe for concurrent use by multiple threads, but the get() method of the supplied supplier may not be

orElseThrow

default T orElseThrow()

Returns the result of invoking the get() method, which may be null.

Returns:

the result of invoking the get() method, which may be null

Throws:

NoSuchElementException - if value absence was indicated by the get() method

See Also:

• orElseThrow(Supplier)

Idempotency:

No guarantees are made about idempotency or determinism.

Nullability:

This method and its (discouraged) overrides may return null.

Thread Safety:

This method is, and its (discouraged) overrides must be, safe for concurrent use by multiple threads.

orElseThrow

default <X extends Throwable> T orElseThrow(Supplier<? extends X> throwableSupplier)
                                     throws X

Returns the result of invoking the get() method, which may be null, or, if the get() method indicates value absence by throwing either a NoSuchElementException or an UnsupportedOperationException, throws the return value of an invocation of the supplied Supplier's get() method.

Type Parameters:

X - the type of Throwable the supplied throwableSupplier supplies

Parameters:

throwableSupplier - the Throwable Supplier; must not be null

Returns:

the result of invoking the get() method, which may be null, or, if the get() method indicates value absence by throwing either a NoSuchElementException or an UnsupportedOperationException, throws the return value of an invocation of the supplied Supplier's get() method

Throws:

NullPointerException - if supplier is null

X - (actually <X>) if the get() method throws either a NoSuchElementException or an UnsupportedOperationException

See Also:

• get()

Idempotency:

No guarantees are made about idempotency or determinism.

Nullability:

This method and its (discouraged) overrides may return null.

Thread Safety:

This method itself is, and its (discouraged) overrides must be, safe for concurrent use by multiple threads.

determinism

default OptionalSupplier.Determinism determinism()

Returns an OptionalSupplier.Determinism denoting the presence of values returned by this OptionalSupplier's get() method.

Overrides of this method must be compatible with the implementation of the get() method. Specifically:

• If an override of this method returns OptionalSupplier.Determinism.PRESENT, then the implementation of the get() method must never throw either a NoSuchElementException or an UnsupportedOperationException, and, for any two invocations, on any thread, must return either the same object, or objects that are indistinguishable from one another and that can be substituted for each other interchangeably.
• If an override of this method returns OptionalSupplier.Determinism.ABSENT, then it is expected that any two invocations of the get() method, on any thread, will each throw either a NoSuchElementException or an UnsupportedOperationException. If an implementation of the get() method instead returns a value, contrary to these requirements, then the value must be treated as irrelevant or undefined.
• If an override of this method returns OptionalSupplier.Determinism.DETERMINISTIC, then any two invocations of the get() method implementation, on any thread, must either throw either a NoSuchElementException or an UnsupportedOperationException, or must return either the same object, or objects that are indistinguishable from one another and that can be substituted for each other interchangeably.
• If an override of this method returns OptionalSupplier.Determinism.NON_DETERMINISTIC, then there are no additional requirements placed upon the implementation of the get() method besides those defined in its existing contract.

Additionally, once an override of this method returns a OptionalSupplier.Determinism whose deterministic() method returns true, then it must forever afterwards, for all invocations, on all possible threads, return the same OptionalSupplier.Determinism.

If any of the requirements above is not met, undefined behavior may result.

The default implementation of this method returns OptionalSupplier.Determinism.NON_DETERMINISTIC. Overrides are strongly encouraged.

Returns:

an OptionalSupplier.Determinism denoting the presence of values returned by this OptionalSupplier's get() method

Idempotency:

This method is idempotent and deterministic. Its (encouraged) overrides must be idempotent. They may not be deterministic (see above).

Nullability:

This method does not, and its (encouraged) overrides must not, return null.

Thread Safety:

This method is, and its (encouraged) overrides must be, safe for concurrent use by multiple threads.

stream

default Stream<T> stream()

Returns the result of invoking the Stream.of(Object) method on the return value of an invocation of the get() method, which may be null, or, if the get() method indicates value absence by throwing either a NoSuchElementException or an UnsupportedOperationException, returns the result of invoking the Stream.empty() method.

Note that this means the sole element of the Stream that is returned may be null. If this is undesirable, consider invoking stream() on the return value of the optional() method instead.

Returns:

the result of invoking the Stream.of(Object) method on the return value of an invocation of the get() method, which may be null, or, if the get() method indicates value absence by throwing either a NoSuchElementException or an UnsupportedOperationException, returns the result of invoking the Stream.empty() method

See Also:

• get()

Idempotency:

No guarantees are made about idempotency or determinism.

Nullability:

This method does not, and its (discouraged) overrides must not, return null.

Thread Safety:

This method is, and its (discouraged) overrides must be, safe for concurrent use by multiple threads.

of

static <T> OptionalSupplier<T> of(OptionalSupplier.Determinism determinism,
 Supplier<? extends T> supplier)

Returns a new OptionalSupplier whose determinism() method will return the supplied OptionalSupplier.Determinism and whose get() method will return the result of invoking the Supplier.get() method on the supplied supplier.

Type Parameters:

T - the type of value the returned OptionalSupplier will supply

Parameters:

determinism - the OptionalSupplier.Determinism to use; must not be null

supplier - the Supplier whose get() method will be called; must not be null

Returns:

a new OptionalSupplier whose determinism() method will return the supplied OptionalSupplier.Determinism and whose get() method will return the result of invoking the Supplier.get() method on the supplied supplier

Throws:

NullPointerException - if determinism or supplier is null

Idempotency:

This method is not idempotent but is deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

of

static <T> OptionalSupplier<T> of()

Invokes Absence.instance() and returns the result.

Type Parameters:

T - the type of the nonexistent value the returned OptionalSupplier will never supply

Returns:

the result of invoking Absence.instance()

See Also:

• Absence.instance()

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

of

static <T> OptionalSupplier<T> of(Supplier<? extends T> supplier)

Returns an OptionalSupplier representing the supplied Supplier.

Type Parameters:

T - the type of value the returned OptionalSupplier will supply

Parameters:

supplier - the Supplier; may be null in which case the return value of an invocation of Absence.instance() will be returned

Returns:

an OptionalSupplier representing the supplied Supplier

Idempotency:

This method is not idempotent but is deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

of

static <T> OptionalSupplier<T> of(Supplier<? extends T> supplier,
 Supplier<? extends T> defaults)

Returns an OptionalSupplier that will, loosely speaking, try the supplied supplier first, and, if it throws a NoSuchElementException or an UnsupportedOperationException from its Supplier.get() method, will then try the supplied defaults.

The supplied Supplier instances can, themselves, be OptionalSuppliers, and, if so, the resulting OptionalSupplier will have its determinism() method appropriately implemented.

Type Parameters:

T - the type of object the returned OptionalSupplier will supply

Parameters:

supplier - the first Supplier to try; may be null

defaults - the fallback Supplier to try; may be null

Returns:

a DefaultingOptionalSupplier

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

of

static <T> OptionalSupplier<T> of(T value)

Returns a new OptionalSupplier whose determinism() method will return OptionalSupplier.Determinism.PRESENT and whose get() method will return the supplied value.

Type Parameters:

T - the type of value the returned OptionalSupplier will supply

Parameters:

value - the value the new OptionalSupplier will return from its get() method; may be null

Returns:

a new OptionalSupplier whose determinism() method will return OptionalSupplier.Determinism.PRESENT and whose get() method will return the supplied value

Idempotency:

This method is not idempotent but is deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.