Module org.microbean.loader

Package org.microbean.loader.spi

Class AbstractProvider

java.lang.Object

org.microbean.loader.spi.AbstractProvider

All Implemented Interfaces:

Provider

Direct Known Subclasses:

AbstractTreeBasedProvider, EnvironmentVariableProvider, ProxyingProvider, SystemPropertyProvider

public abstract class AbstractProvider
extends Object
implements Provider

A skeletal Provider implementation.

Author:

Laird Nelson

See Also:

• lowerBound()
• Provider

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractProvider()	Creates a new AbstractProvider with null as its lower type bound.
protected	AbstractProvider(Type lowerBound)	Creates a new AbstractProvider.

Method Summary

Modifier and Type	Method	Description
protected abstract Supplier<?>	find(Loader<?> requestor, Path<? extends Type> absolutePath)	Returns a Supplier suitable for the supplied Loader and Path, or null if there is no such Supplier now and if there never will be such a Supplier for the supplied arguments.
final Value<?>	get(Loader<?> requestor, Path<? extends Type> absolutePath)	Implements the Provider.get(Loader, Path) method to first call the find(Loader, Path) method, and, if necessary, the path(Loader, Path) method, and to then return a Value made up of the relevant return values.
final Type	lowerBound()	Returns a Type representing the lower bound of all possible values supplied by this AbstractProvider.
protected <T extends Type> Path<T>	path(Loader<?> requestor, Path<T> absolutePath)	Returns a Path that will be used to build a Value to be returned by the get(Loader, Path) method.

Methods inherited from class java.lang.Object

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

Constructor Details

AbstractProvider

protected AbstractProvider()

Creates a new AbstractProvider with null as its lower type bound.

See Also:

• AbstractProvider(Type)
• lowerBound()

AbstractProvider

protected AbstractProvider(Type lowerBound)

Creates a new AbstractProvider.

Parameters:

lowerBound - the lower type bound of this AbstractProvider; may be, and often is, null

See Also:

• lowerBound()

Method Details

lowerBound

public final Type lowerBound()

Returns a Type representing the lower bound of all possible values supplied by this AbstractProvider.

Specified by:

lowerBound in interface Provider

Returns:

the lower type bound of this AbstractProvider implementation, or null if its lower bound is the lowest possible bound

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method may return null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

get

public final Value<?> get(Loader<?> requestor,
 Path<? extends Type> absolutePath)

Implements the Provider.get(Loader, Path) method to first call the find(Loader, Path) method, and, if necessary, the path(Loader, Path) method, and to then return a Value made up of the relevant return values.

Specified by:

get in interface Provider

Parameters:

requestor - the Loader seeking a Value; must not be null

absolutePath - an absolute Path for which the supplied Loader is seeking a value; must not be null

Returns:

a Value more or less suitable for the combination of the supplied Loader and Path, or null if there is no such Value now and if there never will be such a Value for the supplied arguments

Throws:

NullPointerException - if either requestor or absolutePath is null

IllegalArgumentException - if absolutePath is not absolute, or if !absolutePath.startsWith(requestor.absolutePath()), or if absolutePath.equals(requestor.absolutePath())

See Also:

• Provider.get(Loader, Path)
• find(Loader, Path)
• path(Loader, Path)

Idempotency:

This method is idempotent, but not necessarily deterministic.

Nullability:

This method may return null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

find

protected abstract Supplier<?> find(Loader<?> requestor,
 Path<? extends Type> absolutePath)

Returns a Supplier suitable for the supplied Loader and Path, or null if there is no such Supplier now and if there never will be such a Supplier for the supplied arguments.

Overrides of this method must not call the get(Loader, Path) method or undefined behavior (such as an infinite loop) may result.

Parameters:

requestor - the Loader seeking a Value (as originally passed to the get(Loader, Path) method); must not be null

absolutePath - an absolute Path for which the supplied Loader is seeking a value (as originally passed to the get(Loader, Path) method); must not be null

Returns:

a Supplier more or less suitable for the combination of the supplied Loader and Path, or null if there is no such Supplier now and if there never will be such a Supplier for the supplied arguments

Throws:

NullPointerException - if either requestor or absolutePath is null

IllegalArgumentException - if absolutePath is not absolute, or if !absolutePath.startsWith(requestor.absolutePath()), or if absolutePath.equals(requestor.absolutePath())

See Also:

• get(Loader, Path)

Idempotency:

Overrides of this method must be idempotent but are not assumed to be deterministic.

Nullability:

Overrides of this method may return null, in which case the get(Loader, Path) method will return null as well.

Thread Safety:

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

path

@OverridingEncouraged
protected <T extends Type> Path<T> path(Loader<?> requestor,
 Path<T> absolutePath)

Returns a Path that will be used to build a Value to be returned by the get(Loader, Path) method.

This method does not, and its overrides must not, call the get(Loader, Path) method or undefined behavior (such as an infinite loop) may result.

The default implementation of this method returns the supplied absolutePath.

This method is called by the get(Loader, Path) method only when a call to the find(Loader, Path) method returns a non-null value.

Type Parameters:

T - the type of both the supplied and returned Paths

Parameters:

requestor - requestor the Loader seeking a Value (as originally passed to the get(Loader, Path) method); must not be null

absolutePath - an absolute Path for which the supplied Loader is seeking a value (as originally passed to the get(Loader, Path) method); must not be null

Returns:

a Path that will be used to build a Value to be returned by the get(Loader, Path) method; if null, then the get(Loader, Path) method will return null as well

Throws:

NullPointerException - if either requestor or absolutePath is null

IllegalArgumentException - if absolutePath is not absolute, or if !absolutePath.startsWith(requestor.absolutePath()), or if absolutePath.equals(requestor.absolutePath())

See Also:

• get(Loader, Path)

Idempotency:

This method is, and its overrides must be, idempotent and deterministic.

Nullability:

This method does not, but its overrides may, return null.

Thread Safety:

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