Module org.microbean.loader

Package org.microbean.loader.spi

Class Value<T>

java.lang.Object

org.microbean.loader.spi.Value<T>

Type Parameters:

T - the type of value this Value returns

All Implemented Interfaces:

Supplier<T>, OptionalSupplier<T>

public final class Value<T>
extends Object
implements OptionalSupplier<T>

An OptionalSupplier of a value that is additionally qualified by a Path partially identifying the kinds of Qualifiers and Paths for which it might be suitable.

Values are typically returned by Provider implementations.

A Value once received retains no reference to whatever produced it and can be regarded as an authoritative source for (possibly ever-changing) values going forward. Notably, it can be cached.

Author:

Laird Nelson

See Also:

• OptionalSupplier
• Provider

Nested Class Summary

Nested classes/interfaces inherited from interface org.microbean.invoke.OptionalSupplier

OptionalSupplier.Determinism

Constructor Summary

Constructors

Constructor	Description
Value(Supplier<? extends T> supplier, Path<? extends Type> path)	Creates a new Value.
Value(Value<? extends T> source, Supplier<? extends T> defaults)	Creates a new Value.
Value(Path<? extends Type> path)	Creates a new Value that returns a valid null value from its get() method.
Value(T value, Path<? extends Type> path)	Creates a new Value that will forever and always return the supplied value from its get() method.

Method Summary

Modifier and Type	Method	Description
final OptionalSupplier.Determinism	determinism()	Returns an appropriate OptionalSupplier.Determinism for this Value.
final boolean	equals(Object other)	Returns true if this Value is equal to the supplied Object.
final T	get()	Invokes the get() method of the Supplier supplied at construction time and returns its value, which may be null.
final int	hashCode()	Returns a hashcode for this Value calculated from its Path, and whether it is deterministic.
final Path<? extends Type>	path()	Returns the Path with which this Value is associated.
final Qualifiers<? extends String,?>	qualifiers()	Returns the Qualifiers with which this Value is associated.
final Type	type()	Returns the result of invoking Path.qualified() on the return value of this Value's path() method.
final Class<T>	typeErasure()	Returns the type erasure of the return value of the type() method.
final Value<T>	with(Path<? extends Type> path)	Returns a Value with this Value's supplier and the supplied Path.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.microbean.invoke.OptionalSupplier

exceptionally, handle, ifPresent, ifPresentOrElse, optional, optional, optional, orElse, orElseGet, orElseThrow, orElseThrow, stream

Constructor Details

Value

public Value(Path<? extends Type> path)

Creates a new Value that returns a valid null value from its get() method.

Parameters:

path - the Path, possibly relative, for which this Value is suitable; must not be null

Throws:

NullPointerException - if path is null

See Also:

• get()
• FixedValueSupplier.of(Object)

Value

public Value(T value,
 Path<? extends Type> path)

Creates a new Value that will forever and always return the supplied value from its get() method.

Parameters:

path - the Path, possibly relative, for which this Value is suitable; must not be null

value - a fixed value to be returned by the get() method whenever it is invoked; may be null

Throws:

NullPointerException - if path is null

See Also:

• get()
• FixedValueSupplier.of(Object)

Value

public Value(Value<? extends T> source,
 Supplier<? extends T> defaults)

Creates a new Value.

Parameters:

source - the Value to use as the primary supplier; must not be null

defaults - the Supplier to use as the fallback; may be null

Throws:

NullPointerException - if source is null

Value

public Value(Supplier<? extends T> supplier,
 Path<? extends Type> path)

Creates a new Value.

Parameters:

supplier - the actual Supplier that will return values; may be null

path - the Path, possibly relative, for which this Value is suitable; must not be null

Throws:

NullPointerException - if path is null

Method Details

with

public final Value<T> with(Path<? extends Type> path)

Returns a Value with this Value's supplier and the supplied Path.

Parameters:

path - the new Path; must not be null

Returns:

a Value with this Value's supplier and the supplied Path

Throws:

NullPointerException - if path is null

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.

qualifiers

@Convenience
public final Qualifiers<? extends String,?> qualifiers()

Returns the Qualifiers with which this Value is associated.

Returns:

the Qualifiers with which this Value is associated

See Also:

• Path.qualifiers()

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.

path

public final Path<? extends Type> path()

Returns the Path with which this Value is associated.

Returns:

the Path with which this Value is associated

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.

get

public final T get()

Invokes the get() method of the Supplier supplied at construction time and returns its value, which may be null.

Specified by:

get in interface OptionalSupplier<T>

Specified by:

get in interface Supplier<T>

Returns:

tbe return value of an invocation of the get() method of the Supplier supplied at construction time, which may be null

Throws:

NoSuchElementException - if this method should no longer be invoked because there is no chance it will ever produce a suitable value again

UnsupportedOperationException - if this method should no longer be invoked because there is no chance it will ever produce a suitable value again

See Also:

• Value(Supplier, Path)

Idempotency:

This method is as idempotent and deterministic as the Supplier supplied at construction time.

Nullability:

This method may return null.

Thread Safety:

This method is safe for concurrent use by multiple threads, provided that the Supplier supplied at construction time is also safe for concurrent use by multiple threads.

determinism

public final OptionalSupplier.Determinism determinism()

Returns an appropriate OptionalSupplier.Determinism for this Value.

Specified by:

determinism in interface OptionalSupplier<T>

Returns:

an appropriate OptionalSupplier.Determinism for this Value

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.

type

@Convenience
public final Type type()

Returns the result of invoking Path.qualified() on the return value of this Value's path() method.

This method never returns null.

Returns:

the result of invoking Path.qualified() on the return value of this Value's path() method; never null

See Also:

• path()
• Path.qualified()

Idempotency:

This method is idempotent and and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

typeErasure

public final Class<T> typeErasure()

Returns the type erasure of the return value of the type() method.

This method never returns null.

Returns:

the result of invoking JavaTypes.erase(Type) on the return value of this Value's type() method; never null

Throws:

IllegalStateException - if somehow the return value of type() could not be erased

See Also:

• path()
• JavaTypes.erase(Type)

Idempotency:

This method is idempotent and and deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

hashCode

public final int hashCode()

Returns a hashcode for this Value calculated from its Path, and whether it is deterministic.

Overrides:

hashCode in class Object

Returns:

a hashcode for this Value

See Also:

• equals(Object)
• path()
• determinism()

Idempotency:

This method is idempotent and and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.

equals

public final boolean equals(Object other)

Returns true if this Value is equal to the supplied Object.

This method will return true if and only if the following conditions hold:

• The supplied Object is not null
• The supplied Object's Object.getClass() method returns Value.class
• Objects.equals(this.path(), otherValue.path()) returns true
• Objects.equals(this.determinism(), otherValue.determinism()) returns true

Overrides:

equals in class Object

Parameters:

other - the Object to test; may be null in which case false will be returned

Returns:

true if this Value is equal to the supplied Object; false otherwise

See Also:

• path()
• determinism()

Idempotency:

This method is idempotent and and deterministic.

Thread Safety:

This method is safe for concurrent use by multiple threads.