Module jakarta.config.api

Package jakarta.config

Interface Loader

public interface Loader

A loader of configuration-related objects.

The loader resolves configuration data of the provided configuration interface with a portion of application's persistent configuration identified by configuration path. The portion of the persistent configuration is identified by configuration path.

The loader must support persistent configuration stored in META-INF/jakarta-config.properties file found on the classpath that follows a format that is recognized by the class Properties.

In the following example the MyConfigurationRelatedObject is the configuration interface to be resolved. An instance of the configuration interface is created by the Loader:

 Loader loader = Loader.bootstrap();
MyConfigurationRelatedObject object = null;
try {
  object = loader
             .path("my.configuration")
             .load(MyConfigurationRelatedObject.class);
} catch (NoSuchObjectException noSuchObjectException) {
  // object is absent
} catch (ConfigException configException) {
  // a loading-related error occurred
}

Implementations of the methods in this class must be:

• idempotent
• safe for concurrent use by multiple threads
• must not return null.

See Also:

• bootstrap()
• bootstrap(ClassLoader)
• load(Class)
• load(TypeToken)
• path(String)
• Terminology

Method Summary

Modifier and Type	Method	Description
static Loader	bootstrap()	Bootstraps a Loader instance for subsequent usage using the context classloader.
static Loader	bootstrap(ClassLoader classLoader)	Bootstraps a Loader instance for subsequent usage.
<T> T	load(TypeToken<T> type)	Loads a configuration-related object of the supplied type and returns it.
<T> T	load(Class<T> type)	Loads a configuration-related object of the supplied type and returns it.
Loader	path(String path)	Return a new instance of a Loader with the configuration path set.

Method Details

load

<T> T load(Class<T> type)

Loads a configuration-related object of the supplied type and returns it.

Note: The rules governing how it is determined whether any given configuration-related object is "of the supplied type" are currently wholly undefined.

Implementations of this method may or may not return a determinate value.

Type Parameters:

T - the type of object to load

Parameters:

type - the type of object to load; must not be null

Returns:

the loaded object; never null

Throws:

NoSuchObjectException - if the invocation was sound but the requested object was absent

ConfigException - if the invocation was sound but the object could not be loaded for any reason not related to absence

IllegalArgumentException - if the suplied type was invalid for any reason

NullPointerException - if the supplied type was null

load

<T> T load(TypeToken<T> type)

Loads a configuration-related object of the supplied type and returns it.

Note: The rules governing how it is determined whether any given configuration-related object is "of the supplied type" are currently wholly undefined.

Implementations of this method may or may not return a determinate value.

Type Parameters:

T - the type of object to load

Parameters:

type - the type of object to load; must not be null

Returns:

the loaded object; never null

Throws:

NoSuchObjectException - if the invocation was sound but the requested object was absent

ConfigException - if the invocation was sound but the object could not be loaded for any reason not related to absence

IllegalArgumentException - if the suplied type was invalid for any reason

NullPointerException - if the supplied type was null

path

Loader path(String path)

Return a new instance of a Loader with the configuration path set. The configuration path identifies where the configuration relevant for the annotated configuration class is found in a given application's persistent configuration.

The configuration path uses the dot symbol as a separator.

For instance, if the persistent configuration contains

  my.configuration.user=tester

the configuration path for the configuration portion user=tester would be my.configuration.

Parameters:

path - a configuration path.

Returns:

a new instance of the Loader class with a configured path.

See Also:

• Configuration#path

bootstrap

static Loader bootstrap()

Bootstraps a Loader instance for subsequent usage using the context classloader.

This method never returns null.

This method is idempotent.

This method is safe for concurrent use by multiple threads.

This method may or may not return a determinate value. See bootstrap(ClassLoader) for details.

Except as possibly noted above, the observable behavior of this method is specified to be identical to that of the bootstrap(ClassLoader) method.

Returns:

a Loader; never null

Throws:

ServiceConfigurationError - if bootstrapping failed because of a ServiceLoader.load(Class, ClassLoader) or ServiceLoader.findFirst() problem

ConfigException - if bootstrapping failed because of a load(Class) problem

See Also:

• bootstrap(ClassLoader)

bootstrap

static Loader bootstrap(ClassLoader classLoader)

Bootstraps a Loader instance for subsequent usage.

The bootstrap process proceeds as follows:

1. A primordial Loader is located with observable effects equal to those resulting from executing the following code:

   Loader loader = ServiceLoader.load(Loader.class, classLoader)
     .findFirst()
     .orElseThrow(NoSuchObjectException::new);

2. The load(Class) method is invoked on the resulting Loader with Loader.class as its sole argument.
   • If the invocation throws a NoSuchObjectException, the primordial Loader is returned.
   • If the invocation returns a Loader, that Loader is returned.

This method may or may not return a determinate value depending on the implementation of the Loader loaded in step 2 above.

Note: The implementation of this method may change without notice between any two versions of this specification. The requirements described above, however, will be honored in any minor version of this specification within a given major version.

Parameters:

classLoader - the ClassLoader used to locate service provider files; may be null to indicate the system classloader (or bootstrap class loader) in accordance with the contract of the ServiceLoader.load(Class, ClassLoader) method; often is the return value of an invocation of Thread.currentThread().getContextClassLoader()

Returns:

a Loader; never null

Throws:

ServiceConfigurationError - if bootstrapping failed because of a ServiceLoader.load(Class, ClassLoader) or ServiceLoader.findFirst() problem

ConfigException - if bootstrapping failed because of a load(Class) problem