Module org.tquadrat.foundation.base

Package org.tquadrat.foundation.lang

Interface Lazy<T>

Type Parameters:

T - The type of the value for this instance of Lazy.

All Known Implementing Classes:

LazyImpl

@ClassVersion(sourceVersion="$Id: Lazy.java 1041 2022-12-18 22:14:52Z tquadrat $")
@API(status=STABLE,
     since="0.0.5")
public sealed interface Lazy<T>
permits LazyImpl<T>

A holder for a lazy initialised object instance.

An instance of an implementation of this interface holds a value that will be initialised by a call to the supplier (provided with the method use(Supplier)) on a first call to get().

The methods getAsString() and getAsString(Stringer) do call get() internally.

For special purposes, the method of(Object) creates an already initialised instance of Lazy.

Use isPresent() to avoid unnecessary initialisation.

As a lazy initialisation makes the value unpredictable, it is necessary that the implementations of equals(Object) and hashCode() do force the initialisation.

toString() will not force the initialisation.

This interface is not feasible for the lazy initialisation of connections to resources of any kind, as these will usually throw (checked) exceptions when problems arise, and usually these should be handled on one central location.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: Lazy.java 1041 2022-12-18 22:14:52Z tquadrat $

Since:

0.0.5

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.lang.Lazy"

⁠

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object obj)
T	get()	Returns the value for this instance of Lazy.
default String	getAsString()	Returns the value for this instance of Lazy as its String representation.
default String	getAsString(Stringer<? super T> stringer)	Returns the value for this instance of Lazy as a String that is generated by the provided Stringer.
int	hashCode()
default void	ifPresent(Consumer<? super T> consumer)	If this Lazy instance has been initialised already, the provided Consumer will be executed; otherwise nothing happens.
boolean	isPresent()	Checks whether this Lazy instance has been initialised already.
default <R> Optional<R>	map(Function<? super T,? extends R> mapper)	If this instance of Lazy is initialised, the provided mapper function will be executed on the value.
static <T> Lazy<T>	of(T value)	Creates a new Lazy instance that is already initialised.
<X extends Throwable> T	orElseThrow(Supplier<? extends X> exceptionSupplier)	Returns the value or throws the exception that is created by the given Supplier when not yet initialised.
String	toString()
static <T> Lazy<T>	use(Supplier<T> supplier)	Creates a new Lazy instance that uses the given supplier to initialise.

Method Details

equals

boolean equals(Object obj)

Overrides:

equals in class Object

get

T get()

Returns the value for this instance of Lazy.

Returns:

The value.

getAsString

default String getAsString()

Returns the value for this instance of Lazy as its String representation.

Basically it will call the value's toString() method.

Returns:

The value as String.

getAsString

default String getAsString(Stringer<? super T> stringer)

Returns the value for this instance of Lazy as a String that is generated by the provided Stringer.

Note:

• As the value is allowed to be null, it is necessary that the provided instance of Function can handle null as a valid argument.

Parameters:

stringer - The function that creates the String from the value.

Returns:

The value as String.

hashCode

int hashCode()

Overrides:

hashCode in class Object

ifPresent

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

If this Lazy instance has been initialised already, the provided Consumer will be executed; otherwise nothing happens.

Parameters:

consumer - The consumer.

isPresent

boolean isPresent()

Checks whether this Lazy instance has been initialised already. But even it was initialised, get() may still return null.

Returns:

true if the instance was initialised, false otherwise.

map

default <R> Optional<R> map(Function<? super T,? extends R> mapper)

If this instance of Lazy is initialised, the provided mapper function will be executed on the value.

Type Parameters:

R - The result type for the mapper function.

Parameters:

mapper - The mapper function.

Returns:

An instance of Optional that holds the result for the mapping.

of

@API(status=STABLE,
     since="0.0.5")
static <T> Lazy<T> of(T value)

Creates a new Lazy instance that is already initialised.

This allows to use Lazy instances also for cloneable objects, given that T is either cloneable itself or immutable.

Type Parameters:

T - The type of the value for the new instance of Lazy.

Parameters:

value - The value; can be null.

Returns:

The new instance.

See Also:

• Object.clone()

orElseThrow

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

Returns the value or throws the exception that is created by the given Supplier when not yet initialised.

Type Parameters:

X - The type of the implementation of Throwable.

Parameters:

exceptionSupplier - The supplier for the exception to throw when the instance was not yet initialised.

Returns:

The value.

Throws:

X - When not initialised, the exception created by the given supplier will be thrown.

toString

String toString()

Overrides:

toString in class Object

use

@API(status=STABLE,
     since="0.0.5")
static <T> Lazy<T> use(Supplier<T> supplier)

Creates a new Lazy instance that uses the given supplier to initialise.

Type Parameters:

T - The type of the value for the new instance of Lazy.

Parameters:

supplier - The supplier that initialises the value for this instance on the first call to get().

Returns:

The new instance.