Module org.microbean.loader

Package org.microbean.loader

Class DefaultLoader<T>

java.lang.Object

org.microbean.loader.DefaultLoader<T>

Type Parameters:

T - the type of configured objects this DefaultLoader supplies

All Implemented Interfaces:

AutoCloseable, Supplier<T>, OptionalSupplier<T>, Loader<T>

public class DefaultLoader<T>
extends Object
implements AutoCloseable, Loader<T>

A subclassable default Loader implementation that delegates its work to Providers and an AmbiguityHandler.

Author:

Laird Nelson

See Also:

• Loader
• Provider

Nested Class Summary

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

OptionalSupplier.Determinism

Constructor Summary

Constructors

Constructor	Description
DefaultLoader()	Creates a new DefaultLoader.
DefaultLoader(Collection<? extends Provider> providers)	Creates a new DefaultLoader that will use the supplied Providers and an AmbiguityHandler disovered via the ServiceLoader mechanism.
DefaultLoader(Collection<? extends Provider> providers, AmbiguityHandler ambiguityHandler)	Creates a new DefaultLoader that will use the supplied Providers and AmbiguityHandler.

Method Summary

Modifier and Type	Method	Description
final Path<? extends Type>	absolutePath()	Returns the absolute Path representing the Path with which this DefaultLoader was created.
final AmbiguityHandler	ambiguityHandler()	Returns the AmbiguityHandler associated with this DefaultLoader.
final void	close()	Clears any caches used by this DefaultLoader.
final OptionalSupplier.Determinism	determinism()	Returns a OptionalSupplier.Determinism suitable for this DefaultLoader.
final T	get()
final <U> DefaultLoader<U>	load(Path<? extends Type> path)	Returns a DefaultLoader that can supply environmental objects that are suitable for the supplied path.
final Loader<?>	parent()	Returns the Loader serving as the parent of this DefaultLoader.
final Path<? extends Type>	path()	Returns the Path with which this DefaultLoader was created.
final DefaultLoader<T>	plus(Collection<? extends Provider> providers)	Returns a DefaultLoader that uses the additional Providers.
final DefaultLoader<T>	plus(Provider provider)	Returns a DefaultLoader that uses the additional Provider.
final Collection<Provider>	providers()	Returns an unmodifiable Collection of Providers that this DefaultLoader will use to supply objects.
final DefaultLoader<T>	with(Collection<? extends Provider> providers)	Returns a DefaultLoader that uses only the supplied Providers.
final DefaultLoader<T>	with(AmbiguityHandler ambiguityHandler)	Returns a DefaultLoader that uses the supplied AmbiguityHandler.
final DefaultLoader<T>	with(Provider provider)	Returns a DefaultLoader that uses only the supplied Provider.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.microbean.loader.api.Loader

absolutePath, as, isRoot, load, load, load, load, load, load, load, load, load, load, load, load, load, load, load, loaderFor, root, transliterate

Methods inherited from interface org.microbean.invoke.OptionalSupplier

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

Constructor Details

DefaultLoader

public DefaultLoader()

Creates a new DefaultLoader.

The new DefaultLoader will return this from its parent() method.

See Also:

• Loader.loader()

DefaultLoader

public DefaultLoader(Collection<? extends Provider> providers)

Creates a new DefaultLoader that will use the supplied Providers and an AmbiguityHandler disovered via the ServiceLoader mechanism.

The new DefaultLoader will return this from its parent() method.

Parameters:

providers - the Providers to use; may be null in which case Providers will be discovered using the ServiceLoader mechanism; may be empty in which case the new DefaultLoader may be useless

DefaultLoader

public DefaultLoader(Collection<? extends Provider> providers,
 AmbiguityHandler ambiguityHandler)

Creates a new DefaultLoader that will use the supplied Providers and AmbiguityHandler.

The new DefaultLoader will return this from its parent() method.

Parameters:

providers - the Providers to use; may be null in which case Providers will be discovered using the ServiceLoader mechanism; may be empty in which case the new DefaultLoader may be useless

ambiguityHandler - the AmbiguityHandler to use; may be null in which case an AmbiguityHandler will be discovered using the ServiceLoader mechanism

Method Details

close

@Experimental
public final void close()

Clears any caches used by this DefaultLoader.

This DefaultLoader remains valid to use.

Specified by:

close in interface AutoCloseable

Idempotency:

This method is deterministic but not idempotent unless the caches are already cleared.

Thread Safety:

This method is safe for concurrent use by multiple threads.

plus

public final DefaultLoader<T> plus(Provider provider)

Returns a DefaultLoader that uses the additional Provider.

Parameters:

provider - the additional Provider; may be null in which case this will be returned

Returns:

a DefaultLoader that uses the additional Provider

Idempotency:

This method is not idempotent (it usually creates a new DefaultLoader to return) but is deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

plus

public final DefaultLoader<T> plus(Collection<? extends Provider> providers)

Returns a DefaultLoader that uses the additional Providers.

Parameters:

providers - the additional Providers; may be null or empty in which case this will be returned

Returns:

a DefaultLoader that uses the additional Providers

Idempotency:

This method is not idempotent (it usually creates a new DefaultLoader to return) but is deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

with

public final DefaultLoader<T> with(Provider provider)

Returns a DefaultLoader that uses only the supplied Provider.

Parameters:

provider - the Provider; may be null in which case Providers will be loaded using the ServiceLoader class

Returns:

a DefaultLoader that uses only the supplied Provider

Idempotency:

This method is not idempotent (it usually creates a new DefaultLoader to return) but is deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

with

public final DefaultLoader<T> with(Collection<? extends Provider> providers)

Returns a DefaultLoader that uses only the supplied Providers.

Parameters:

providers - the Providers; may be null or empty in which case Providers will be loaded using the ServiceLoader class

Returns:

a DefaultLoader that uses only the supplied Providers

Idempotency:

This method is not idempotent (it usually creates a new DefaultLoader to return) but is deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

with

public final DefaultLoader<T> with(AmbiguityHandler ambiguityHandler)

Returns a DefaultLoader that uses the supplied AmbiguityHandler.

Parameters:

ambiguityHandler - the AmbiguityHandler; must not be null

Returns:

a DefaultLoader that uses the supplied AmbiguityHandler

Throws:

NullPointerException - if ambiguityHandler is null

Idempotency:

This method is not idempotent (it usually creates a new DefaultLoader to return) but is deterministic.

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

providers

public final Collection<Provider> providers()

Returns an unmodifiable Collection of Providers that this DefaultLoader will use to supply objects.

This method never returns null.

Returns:

an unmodifiable Collection of Providers that this DefaultLoader will use to supply objects; never 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.

ambiguityHandler

public final AmbiguityHandler ambiguityHandler()

Returns the AmbiguityHandler associated with this DefaultLoader.

This method never returns null.

Returns:

the AmbiguityHandler associated with this DefaultLoader; never null

See Also:

• AmbiguityHandler

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.

parent

public final Loader<?> parent()

Returns the Loader serving as the parent of this DefaultLoader.

The "root" DefaultLoader returns itself from its parent() implementation.

This method never returns null.

Specified by:

parent in interface Loader<T>

Returns:

the non-null Loader serving as the parent of this DefaultLoader; may be this DefaultLoader itself

See Also:

• Loader.root()
• Loader.isRoot()
• Loader.loader()

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 DefaultLoader was created.

The Path that is returned by this method is not guaranteed to be absolute.

The Path that is returned by this method will be equal to a transliterated version of the Path that was supplied to the load(Path) method of this DefaultLoader's parent that resulted in this DefaultLoader's creation.

Specified by:

path in interface Loader<T>

Returns:

the non-null Path with which this DefaultLoader was created

See Also:

• parent()
• load(Path)
• absolutePath()
• Loader.absolutePath(Path)

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null., Implementations of this method must not return null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

absolutePath

public final Path<? extends Type> absolutePath()

Returns the absolute Path representing the Path with which this DefaultLoader was created.

The Path that is returned by this method is guaranteed to be absolute.

The Path that is returned by this method will be equal to a transliterated and absolute version of the Path that was supplied to the load(Path) method of this DefaultLoader's parent that resulted in this DefaultLoader's creation.

Specified by:

absolutePath in interface Loader<T>

Returns:

the non-null absolute Path representing the Path with which this DefaultLoader was created

See Also:

• parent()
• load(Path)
• path()
• Loader.absolutePath(Path)

Idempotency:

This method is idempotent and deterministic.

Nullability:

This method never returns null., Implementations of this method must not return null.

Thread Safety:

This method is safe for concurrent use by multiple threads.

determinism

public final OptionalSupplier.Determinism determinism()

Returns a OptionalSupplier.Determinism suitable for this DefaultLoader.

Specified by:

determinism in interface OptionalSupplier<T>

Returns:

a OptionalSupplier.Determinism suitable for this DefaultLoader

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()

Specified by:

get in interface OptionalSupplier<T>

Specified by:

get in interface Supplier<T>

load

public final <U> DefaultLoader<U> load(Path<? extends Type> path)

Returns a DefaultLoader that can supply environmental objects that are suitable for the supplied path.

This method never returns null.

The DefaultLoader that is returned may return null from its get() method. Additionally, the DefaultLoader that is returned may throw NoSuchElementException or UnsupportedOperationException from its get() method.

Specified by:

load in interface Loader<T>

Type Parameters:

U - the type of the supplied Path and the type of the returned DefaultLoader

Parameters:

path - the Path for which a DefaultLoader should be returned; must not be null

Returns:

a DefaultLoader capable of supplying environmental objects suitable for the supplied path; never null

Throws:

NullPointerException - if path is null

IllegalArgumentException - if the path, after normalization, is the root Path

See Also:

• OptionalSupplier.get()
• OptionalSupplier.determinism()

Nullability:

This method never returns null.

Thread Safety:

This method is safe for concurrent use by multiple threads., This method is idempotent and deterministic.