An implementation of the {@code ConfigurationBuilder} interface which is ableto create different concrete {@code Configuration} implementations based onreflection.
When constructing an instance of this class the concrete {@code Configuration} implementation class has to be provided. Thenproperties for the new {@code Configuration} instance can be set. The firstcall to {@code getConfiguration()} creates and initializes the new{@code Configuration} object. It is cached and returned by subsequent calls.This cache - and also the initialization properties set so far - can be flushed by calling one of the {@code reset()} methods. That way other{@code Configuration} instances with different properties can be created.
If the newly created {@code Configuration} object implements the{@code Initializable} interface, its {@code initialize()} method is calledafter all initialization properties have been set. This way a concrete implementation class can perform arbitrary initialization steps.
There are multiple options for setting up a {@code BasicConfigurationBuilder}instance:
- All initialization properties can be set in one or multiple calls of the {@code configure()} method. In each call an arbitrary number of{@link BuilderParameters} objects can be passed. The API allows methodchaining and is intended to be used from Java code.
- If builder instances are created by other means - e.g. using a dependency injection framework -, the fluent API approach may not be suitable. For those use cases it is also possible to pass in all initialization parameters as a map. The keys of the map have to match initialization properties of the {@code Configuration} object to be created, the values are the correspondingproperty values. For instance, the key throwExceptionOnMissing in the map will cause the method {@code setThrowExceptionOnMissing()} on the{@code Configuration} object to be called with the corresponding value asparameter.
A builder instance can be constructed with an allowFailOnInit flag. If set to true, exceptions during initialization of the configuration are ignored; in such a case an empty configuration object is returned. A use case for this flag is a scenario in which a configuration is optional and created on demand the first time configuration data is to be stored. Consider an application that stores user-specific configuration data in the user's home directory: When started for the first time by a new user there is no configuration file; so it makes sense to start with an empty configuration object. On application exit, settings can be stored in this object and written to the associated file. Then they are available on next application start.
This class is thread-safe. Multiple threads can modify initialization properties and call {@code getConfiguration()}. However, the intended use case is that the builder is configured by a single thread first. Then {@code getConfiguration()} can be called concurrently, and it is guaranteedthat always the same {@code Configuration} instance is returned until thebuilder is reset.
@version $Id: BasicConfigurationBuilder.java 1624601 2014-09-12 18:04:36Z oheger $
@since 2.0
@param < T> the concrete type of {@code Configuration} objects created by thisbuilder