Module org.microbean.loader.api

Package org.microbean.loader.api

Interface Loader<T>

Type Parameters:

T - the type of environmental objects this Loader supplies

All Superinterfaces:

OptionalSupplier<T>, Supplier<T>

public interface Loader<T>
extends OptionalSupplier<T>

An OptionalSupplier that supplies an environmental object, and can load others.

Note: Loader implementations are expected to be immutable with respect to the methods exposed by this interface. All methods in this interface that have a Loader-typed return type require their implementations to return a new Loader.

The presence of the @OverridingDiscouraged annotation on a method means that undefined behavior may result if an implementation of this interface provides an alternate implementation of the method in question.

Author:

Laird Nelson

See Also:

• loader()
• OptionalSupplier.get()
• load(Path)

Nested Class Summary

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

OptionalSupplier.Determinism

Method Summary

Modifier and Type	Method	Description
default @Experimental Path<? extends Type>	absolutePath()	Experimental; do not use.
default <P> @Experimental Path<P>	absolutePath(Path<P> path)	Returns an absolute Path representing the
default <L extends Loader<?>> L	as(Class<L> loaderSubclass)	Casts this Loader appropriately and returns it, usually so that an implementation's implementation-specific methods can be accessed.
default boolean	isRoot()	Returns true if and only if this Loader is the root Loader, which occurs only when the return value of this.parent() == this.
default <U> Loader<U>	load(Class<U> type)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
default <U> Loader<U>	load(Class<U> type, String name)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
default <U> Loader<U>	load(Class<U> type, String... names)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
default <U> Loader<U>	load(Class<U> type, List<? extends String> names)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
default <U> Loader<U>	load(Type type)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
default <U> Loader<U>	load(Type type, String name)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
default <U> Loader<U>	load(Type type, String... names)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
default <U> Loader<U>	load(Type type, List<? extends String> names)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
<U> Loader<U>	load(Path<? extends Type> path)	Uses the addressing information encoded in the supplied Path to load and return the Loader logically found at that location, following additional contractual requirements defined below.
default <U> Loader<U>	load(Qualifiers<? extends String,?> qualifiers, Class<U> type)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
default <U> Loader<U>	load(Qualifiers<? extends String,?> qualifiers, Type type)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
default <U> Loader<U>	load(Qualifiers<? extends String,?> qualifiers, org.microbean.type.JavaType.Token<U> type)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
default <U> Loader<U>	load(org.microbean.type.JavaType.Token<U> type)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
default <U> Loader<U>	load(org.microbean.type.JavaType.Token<U> type, String name)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
default <U> Loader<U>	load(org.microbean.type.JavaType.Token<U> type, String... names)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
default <U> Loader<U>	load(org.microbean.type.JavaType.Token<U> type, List<? extends String> names)	Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.
static Loader<?>	loader()	Bootstraps and returns a Loader.
default Loader<?>	loaderFor(Path<? extends Type> path)	Returns an ancestral Loader, derived from and possibly identical to this Loader, that is suitable for a transliterated and absolute version of the supplied path, particularly for cases where, during the execution of the load(Path) method, a Loader must be supplied to some other class.
Loader<?>	parent()	Returns the Loader that is the parent of this Loader.
Path<? extends Type>	path()	Returns the Path with which this Loader was created.
default Loader<?>	root()	Returns the root Loader, which is the Loader whose parent() method returns iteself.
default <U extends Type> Path<U>	transliterate(Path<U> path)	Transliterates the supplied absolute Path into some other Path, whose meaning is the same, but whose representation may be different, that will be used instead.

Methods inherited from interface org.microbean.invoke.OptionalSupplier

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

Method Details

parent

Loader<?> parent()

Returns the Loader that is the parent of this Loader.

The root Loader is defined to be the only one whose parent() method returns itself. It follows that in general a Loader implementation should not return this. See isRoot() for details.

Returns:

the Loader that is the parent of this Loader; not this in almost all circumstances

See Also:

• root()
• isRoot()
• loader()

Idempotency:

Implementations of this method must be idempotent and deterministic.

Nullability:

Implementations of this method must not return null.

Thread Safety:

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

path

Path<? extends Type> path()

Returns the Path with which this Loader was created.

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

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

Returns:

the non-null Path with which this Loader was created

See Also:

• parent()
• load(Path)
• absolutePath()
• absolutePath(Path)

Idempotency:

Implementations of this method must be idempotent and deterministic.

Nullability:

Implementations of this method must not return null.

Thread Safety:

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

absolutePath

@Experimental
default @Experimental Path<? extends Type> absolutePath()

Experimental; do not use.

Returns:

an absolute Path

Throws:

NullPointerException - if path() or parent() is implemented incorrectly

See Also:

• absolutePath(Path)

Idempotency:

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

Nullability:

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

Thread Safety:

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

absolutePath

@Experimental
@OverridingDiscouraged
default <P> @Experimental Path<P> absolutePath(Path<P> path)

Returns an absolute Path representing the

Type Parameters:

P - the type of the path

Parameters:

path - a Path; must not be null

Returns:

an absolute Path

Throws:

NullPointerException - if path is null or if #parent()} is implemented incorrectly

Idempotency:

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

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.

load

@EntryPoint
<U> Loader<U> load(Path<? extends Type> path)

Uses the addressing information encoded in the supplied Path to load and return the Loader logically found at that location, following additional contractual requirements defined below.

Any Loader returned by an implementation of this method:

• must not be null
• must implement its get() method and its determinism() method to indicate the transitory or permanent presence or absence of any value it might supply

The default implementations of all other methods in this interface named load call this method.

Type Parameters:

U - the type of the environmental object the returned Loader can supply

Parameters:

path - the Path (perhaps only partially) identifying the Loader to load; must not be null; may be absolute or relative (in which case it will be appended to this Loader's Path)

Returns:

a Loader for the supplied Path; must not be null, but may implement its get() method and its determinism() method to indicate the transitory or permanent presence or absence of any value it might supply

Throws:

NullPointerException - if path is null

ClassCastException - if the implementation is implemented improperly

See Also:

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

load

@OverridingDiscouraged
default <U> Loader<U> load(Qualifiers<? extends String,?> qualifiers,
 Type type)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

qualifiers - the path's Qualifiers; must not be null

type - the path's Type; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• Path.of(Qualifiers, Element)
• Path.Element.of(Object, String)
• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

load

@OverridingDiscouraged
default <U> Loader<U> load(Type type)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

type - the path's Type; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• Path.of(Object)
• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

load

@OverridingDiscouraged
default <U> Loader<U> load(Type type,
 String name)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

type - the path's Type; must not be null

name - the name of the last Path.Element in the Path; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

load

@OverridingDiscouraged
default <U> Loader<U> load(Type type,
 String... names)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

type - the path's Type; must not be null

names - the sequence of names forming the Path; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

load

@OverridingDiscouraged
default <U> Loader<U> load(Type type,
 List<? extends String> names)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

type - the path's Type; must not be null

names - the sequence of names forming the Path; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

load

@OverridingDiscouraged
default <U> Loader<U> load(Qualifiers<? extends String,?> qualifiers,
 org.microbean.type.JavaType.Token<U> type)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

qualifiers - the path's Qualifiers; must not be null

type - a JavaType.Token representing the path's Type; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

load

@OverridingDiscouraged
default <U> Loader<U> load(org.microbean.type.JavaType.Token<U> type)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

type - a JavaType.Token representing the path's Type; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

load

@OverridingDiscouraged
default <U> Loader<U> load(org.microbean.type.JavaType.Token<U> type,
 String name)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

type - a JavaType.Token representing the path's Type; must not be null

name - the name of the last Path.Element in the Path; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

load

@OverridingDiscouraged
default <U> Loader<U> load(org.microbean.type.JavaType.Token<U> type,
 String... names)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

type - a JavaType.Token representing the path's Type; must not be null

names - the sequence of names forming the Path; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

load

@OverridingDiscouraged
default <U> Loader<U> load(org.microbean.type.JavaType.Token<U> type,
 List<? extends String> names)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

type - a JavaType.Token representing the path's Type; must not be null

names - the sequence of names forming the Path; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

load

@OverridingDiscouraged
default <U> Loader<U> load(Qualifiers<? extends String,?> qualifiers,
 Class<U> type)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

qualifiers - the path's Qualifiers; must not be null

type - a Class serving as the path's Type; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

load

@OverridingDiscouraged
default <U> Loader<U> load(Class<U> type)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

type - a Class serving as the path's Type; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

load

@OverridingDiscouraged
default <U> Loader<U> load(Class<U> type,
 String name)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

type - a Class serving as the path's Type; must not be null

name - the name of the last Path.Element in the Path; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

load

@OverridingDiscouraged
default <U> Loader<U> load(Class<U> type,
 String... names)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

type - a Class serving as the path's Type; must not be null

names - the sequence of names forming the Path; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

load

@OverridingDiscouraged
default <U> Loader<U> load(Class<U> type,
 List<? extends String> names)

Builds a Path from the supplied arguments, calls the load(Path) method and returns its result.

Type Parameters:

U - the type of environmental objects the returned Loader will supply

Parameters:

type - a Class serving as the path's Type; must not be null

names - the sequence of names forming the Path; must not be null

Returns:

a Loader

Throws:

NullPointerException - if any argument is null

See Also:

• load(Path)

Idempotency:

No guarantees are made about idempotency or determinism with respect to this method or its (discouraged) overrides.

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.

loaderFor

@OverridingDiscouraged
default Loader<?> loaderFor(Path<? extends Type> path)

Returns an ancestral Loader, derived from and possibly identical to this Loader, that is suitable for a transliterated and absolute version of the supplied path, particularly for cases where, during the execution of the load(Path) method, a Loader must be supplied to some other class.

The returned Loader must be one whose path() method returns the longest Path that is a parent of an absolute version of the (transliterated) supplied path. In many cases this will be returned.

Typically only classes implementing this interface will need to call this method. Most users will have no need to call this method directly.

Overriding of this method is very strongly discouraged.

Parameters:

path - the Path in question; must not be null

Returns:

an ancestral Loader, derived from and possibly identical to this Loader, that is suitable for a transliterated and absolute version of the supplied path, particularly for cases where, during the execution of the load(Path) method, a Loader must be supplied to some other class; never null

Throws:

NullPointerException - if path is null

See Also:

• transliterate(Path)
• root()

Idempotency:

The default implementation of this method is, and its (discouraged) overrides must be, idempotent and deterministic.

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.

transliterate

@OverridingDiscouraged
default <U extends Type> Path<U> transliterate(Path<U> path)

Transliterates the supplied absolute Path into some other Path, whose meaning is the same, but whose representation may be different, that will be used instead.

The Path that is returned may be the Path that was supplied. This may happen, for example, if the path has already been transliterated, or if the path identifies a transliteration request.

Path transliteration is needed because the name() components of Path.Elements may unintentionally clash when two components are combined into a single application.

Path transliteration must occur during the execution of any implementation of the load(Path) method, such that the Path supplied to that method, once it has been verified to be absolute, is supplied to an implementation of this method. The Path returned by an implementation of this method must then be used during the rest of the invocation of the load(Path) method, as if it had been supplied in the first place.

Behavior resulting from any other usage of an implementation of this method is undefined.

The default implementation of this method uses the configuration system itself to find a transliterated Path corresponding to the supplied Path, returning the supplied path itself if no transliteration can take place. Infinite loops are avoided except as noted below.

Overrides of this method must not call loaderFor(Path) or an infinite loop may result.

Overrides of this method must not call load(Path) with the supplied path or an infinite loop may result.

An implementation of Loader will find Path.transliterate(java.util.function.BiFunction) particularly useful in implementing this method.

Most users will have no need to call this method directly.

Type Parameters:

U - the type of the supplied and returned Paths

Parameters:

path - an absolute Path; must not be null

Returns:

the transliterated Path; never null; possibly the supplied path itself

Throws:

NullPointerException - if path is null

IllegalArgumentException - if path returns false from its absolute() method

See Also:

• Path.absolute()
• Path.transliterate(java.util.function.BiFunction)
• loaderFor(Path)
• load(Path)

Idempotency:

The default implementation of this method is, and its (discouraged) overrides must be, idempotent and deterministic.

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.

isRoot

@OverridingDiscouraged
default boolean isRoot()

Returns true if and only if this Loader is the root Loader, which occurs only when the return value of this.parent() == this.

Overrides of this method are strongly discouraged.

Most users will have no need to call this method directly.

Returns:

true if and only if this Loader is the root Loader

See Also:

• parent()

Idempotency:

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

Thread Safety:

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

root

@OverridingDiscouraged
default Loader<?> root()

Returns the root Loader, which is the Loader whose parent() method returns iteself.

Overrides of this method are strongly discouraged.

Most users will have no need to call this method directly.

Returns:

the root Loader

See Also:

• isRoot()
• parent()
• Path.root()

Idempotency:

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

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.

as

@OverridingDiscouraged
default <L extends Loader<?>> L as(Class<L> loaderSubclass)

Casts this Loader appropriately and returns it, usually so that an implementation's implementation-specific methods can be accessed.

Type Parameters:

L - the Loader subclass

Parameters:

loaderSubclass - a Class representing a subclass of Loader; must not be null

Returns:

this Loader

Throws:

NullPointerException - if loaderSubclass is null

ClassCastException - if the cast could not be performed

Idempotency:

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

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.

loader

@EntryPoint
static Loader<?> loader()

Bootstraps and returns a Loader.

If this method has been called before, its prior result is returned.

Otherwise, first, the root Loader is located using Java's built-in ServiceLoader. The first of the Loader instances it discovers is used and all others are ignored. Note that the ServiceLoader discovery process is non-deterministic. Normally there is only one such Loader provided by an implementation of this API.

The root Loader that is loaded via this mechanism is subject to the following restrictions:

• It must return a Path from its path() implementation that is equal to Path.root().
• It must return a Path from its absolutePath() implementation that is equal to Path.root().
• It must return itself (this) from its parent() implementation.
• It must return true from its isRoot() implementation.
• It must return itself (this) from its root() method.
• It must return OptionalSupplier.Determinism.PRESENT from its determinism() method.
• It must return itself (this) from its get() method.

Next, this root Loader is used to find the Loader of record, which in most cases is simply itself.

The Loader of record is subject to the following restrictions (which are compatible with the overwhelmingly common case of its also being the root Loader):

• It must return a Path from its path() implementation that is equal to Path.root() (same as above).
• It must return a Path from its absolutePath() implementation that is equal to Path.root() (same as above).
• It must return OptionalSupplier.Determinism.PRESENT from its determinism() method (same as above).
• It must return the root Loader from its parent() implementation (which may be itself ( this)).
• It must return a Loader implementation, often itself (this), from its get() method.

An IllegalStateException will be thrown if an implementation of the Loader interface does not honor the requirements above.

This method is the primary entry point for end users of this framework.

Returns:

a non-null Loader that can be used to acquire environmental objects that abides by the requirements and restrictions above

Throws:

IllegalStateException - if any of the requirements and restrictions above is violated

ServiceConfigurationError - if the root Loader could not be loaded for any reason

NoClassDefFoundError - if the root Loader could not be loaded for any reason