Class BasicBuilderParameters
java.lang.Object
org.apache.commons.configuration2.builder.BasicBuilderParameters
- All Implemented Interfaces:
Cloneable
,BasicBuilderProperties<BasicBuilderParameters>
,BuilderParameters
- Direct Known Subclasses:
CombinedBuilderParametersImpl
,DatabaseBuilderParametersImpl
,FileBasedBuilderParametersImpl
,JndiBuilderParametersImpl
,MultiFileBuilderParametersImpl
public class BasicBuilderParameters
extends Object
implements Cloneable, BuilderParameters, BasicBuilderProperties<BasicBuilderParameters>
An implementation of BuilderParameters
which handles the parameters of a ConfigurationBuilder
common
to all concrete Configuration
implementations.
This class provides methods for setting standard properties supported by the AbstractConfiguration
base
class. A fluent interface can be used to set property values.
This class is not thread-safe. It is intended that an instance is constructed and initialized by a single thread
during configuration of a ConfigurationBuilder
.
- Since:
- 2.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final String
The key for theBeanHelper
.private static final String
The key for the configurationDecoder property.private static final String
The key for the conversionHandler property.private static final String
The key for the defaultLookups property.private static final String
The key for the interpolator property.private static final String
The key of the listDelimiterHandler property.private static final String
The key of the logger property.private static final String
The key for the parentInterpolator property.private static final String
The key for the prefixLookups property.private static final String
The key for the synchronizer property.private static final String
The key of the throwExceptionOnMissing property.The map for storing the current property values.Fields inherited from interface org.apache.commons.configuration2.builder.BuilderParameters
RESERVED_PARAMETER_PREFIX
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate static void
checkParameters
(Map<String, Object> params) Checks whether a map with parameters is present.clone()
Clones this object.protected void
copyPropertiesFrom
(Map<String, ?> source, String... keys) Copies a number of properties from the given map into this object.private static void
createDefensiveCopies
(HashMap<String, Object> params) Creates defensive copies for collection structures when constructing the map with parameters.private static Collection
<? extends Lookup> fetchAndCheckDefaultLookups
(Map<String, Object> params) Tests whether the passed in map with parameters contains a valid collection with default lookups.fetchAndCheckPrefixLookups
(Map<String, Object> params) Tests whether the passed in map with parameters contains a map with prefix lookups.static BeanHelper
fetchBeanHelper
(Map<String, Object> params) Obtains theBeanHelper
object from the specified map with parameters.private static Collection
<? extends Lookup> fetchDefaultLookups
(Map<String, Object> params) Obtains the collection with default lookups from the parameters map.static InterpolatorSpecification
fetchInterpolatorSpecification
(Map<String, Object> params) Obtains a specification for aConfigurationInterpolator
from the specified map with parameters.private static <T> T
Obtains a parameter from a map and performs a type check.fetchPrefixLookups
(Map<String, Object> params) Obtains the map with prefix lookups from the parameters map.protected Object
fetchProperty
(String key) Obtains the value of the specified property from the internal map.Gets a map with all parameters defined by this objects.void
inheritFrom
(Map<String, ?> source) Inherits properties from the specified map.void
Merges this object with the given parameters object.setBeanHelper
(BeanHelper beanHelper) Sets aBeanHelper
object to be used by the configuration builder.Sets theConfigurationDecoder
object for this configuration.setConversionHandler
(ConversionHandler handler) Sets theConversionHandler
object for this configuration.setDefaultLookups
(Collection<? extends Lookup> lookups) Adds additional defaultLookup
objects (i.e.Sets theConfigurationInterpolator
to be used for this configuration.Sets the value of the listDelimiterHandler property.Sets the logger property.Sets the parentConfigurationInterpolator
for this configuration'sConfigurationInterpolator
.setPrefixLookups
(Map<String, ? extends Lookup> lookups) Sets additionalLookup
objects for specific prefixes for this configuration object.private BasicBuilderParameters
setProperty
(String key, Object value) Helper method for setting a property value.setSynchronizer
(Synchronizer sync) Sets theSynchronizer
object for this configuration.setThrowExceptionOnMissing
(boolean b) Sets the value of the throwExceptionOnMissing property.protected void
storeProperty
(String key, Object value) Sets a property for this parameters object.
-
Field Details
-
PROP_THROW_EXCEPTION_ON_MISSING
The key of the throwExceptionOnMissing property.- See Also:
-
PROP_LIST_DELIMITER_HANDLER
The key of the listDelimiterHandler property.- See Also:
-
PROP_LOGGER
The key of the logger property.- See Also:
-
PROP_INTERPOLATOR
The key for the interpolator property.- See Also:
-
PROP_PREFIX_LOOKUPS
The key for the prefixLookups property.- See Also:
-
PROP_DEFAULT_LOOKUPS
The key for the defaultLookups property.- See Also:
-
PROP_PARENT_INTERPOLATOR
The key for the parentInterpolator property.- See Also:
-
PROP_SYNCHRONIZER
The key for the synchronizer property.- See Also:
-
PROP_CONVERSION_HANDLER
The key for the conversionHandler property.- See Also:
-
PROP_CONFIGURATION_DECODER
The key for the configurationDecoder property.- See Also:
-
PROP_BEAN_HELPER
The key for theBeanHelper
.- See Also:
-
properties
The map for storing the current property values.
-
-
Constructor Details
-
BasicBuilderParameters
public BasicBuilderParameters()Creates a new instance ofBasicBuilderParameters
.
-
-
Method Details
-
checkParameters
Checks whether a map with parameters is present. Throws an exception if not.- Parameters:
params
- the map with parameters to check- Throws:
IllegalArgumentException
- if the map is null
-
createDefensiveCopies
Creates defensive copies for collection structures when constructing the map with parameters. It should not be possible to modify this object's internal state when having access to the parameters map.- Parameters:
params
- the map with parameters to be passed to the caller
-
fetchAndCheckDefaultLookups
Tests whether the passed in map with parameters contains a valid collection with default lookups. This method works likefetchAndCheckPrefixLookups(Map)
, but tests the default lookups collection.- Parameters:
params
- the map with parameters- Returns:
- the collection with default lookups (may be null)
- Throws:
IllegalArgumentException
- if invalid data is found
-
fetchAndCheckPrefixLookups
Tests whether the passed in map with parameters contains a map with prefix lookups. This method is used if the parameters map is from an insecure source and we cannot be sure that it contains valid data. Therefore, we have to map that the key for the prefix lookups actually points to a map containing keys and values of expected data types.- Parameters:
params
- the parameters map- Returns:
- the obtained map with prefix lookups
- Throws:
IllegalArgumentException
- if the map contains invalid data
-
fetchBeanHelper
Obtains theBeanHelper
object from the specified map with parameters. This method can be used to obtain an instance from a parameters map that has been set via thesetBeanHelper()
method. If no such instance is found, result is null.- Parameters:
params
- the map with parameters (must not be null)- Returns:
- the
BeanHelper
stored in this map or null - Throws:
IllegalArgumentException
- if the map is null
-
fetchDefaultLookups
Obtains the collection with default lookups from the parameters map.- Parameters:
params
- the map with parameters- Returns:
- the collection with default lookups (may be null)
-
fetchInterpolatorSpecification
Obtains a specification for aConfigurationInterpolator
from the specified map with parameters. All properties related to interpolation are evaluated and added to the specification object.- Parameters:
params
- the map with parameters (must not be null)- Returns:
- an
InterpolatorSpecification
object constructed with data from the map - Throws:
IllegalArgumentException
- if the map is null or contains invalid data
-
fetchParameter
Obtains a parameter from a map and performs a type check.- Type Parameters:
T
- the parameter type- Parameters:
params
- the map with parameterskey
- the key of the parameterexpClass
- the expected class of the parameter value- Returns:
- the value of the parameter in the correct data type
- Throws:
IllegalArgumentException
- if the parameter is not of the expected type
-
fetchPrefixLookups
Obtains the map with prefix lookups from the parameters map.- Parameters:
params
- the map with parameters- Returns:
- the map with prefix lookups (may be null)
-
clone
Clones this object. This is useful because multiple builder instances may use a similar set of parameters. However, single instances of parameter objects must not assigned to multiple builders. Therefore, cloning a parameters object provides a solution for this use case. This method creates a new parameters object with the same content as this one. The internal map storing the parameter values is cloned, too, also collection structures contained in this map. However, no a full deep clone operation is performed. Objects like aConfigurationInterpolator
orLookup
s are shared between this and the newly created instance. -
copyPropertiesFrom
Copies a number of properties from the given map into this object. Properties are only copied if they are defined in the source map.- Parameters:
source
- the source mapkeys
- the keys to be copied
-
fetchProperty
Obtains the value of the specified property from the internal map. This method can be used by derived classes if a specific property is to be accessed. If the given key is not found, result is null.- Parameters:
key
- the key of the property in question- Returns:
- the value of the property with this key or null
-
getParameters
Gets a map with all parameters defined by this objects. The keys of the map correspond to concrete properties supported by theConfiguration
implementation class the builder produces. The values are the corresponding property values. The return value must not be null. This implementation returns a copy of the internal parameters map with the values set so far. Collection structures (e.g. for lookup objects) are stored as defensive copies, so the original data cannot be modified.- Specified by:
getParameters
in interfaceBuilderParameters
- Returns:
- a map with builder parameters
-
inheritFrom
Inherits properties from the specified map. This can be used for instance to reuse parameters from one builder in another builder - also in parent-child relations in which a parent builder creates child builders. The purpose of this method is to let a concrete implementation decide which properties can be inherited. Because parameters are basically organized as a map it would be possible to simply copy over all properties from the source object. However, this is not appropriate in all cases. For instance, some properties - like aConfigurationInterpolator
- are tightly connected to a configuration and cannot be reused in a different context. For other properties, e.g. a file name, it does not make sense to copy it. Therefore, an implementation has to be explicit in the properties it wants to take over.- Parameters:
source
- the source properties to inherit from- Throws:
IllegalArgumentException
- if the source map is null
-
merge
Merges this object with the given parameters object. This method adds all property values defined by the passed in parameters object to the internal storage which are not already in. So properties already defined in this object take precedence. Property names starting with the reserved parameter prefix are ignored.- Parameters:
p
- the object whose properties should be merged (must not be null)- Throws:
IllegalArgumentException
- if the passed in object is null
-
setBeanHelper
Sets aBeanHelper
object to be used by the configuration builder. TheBeanHelper
is used to create the managed configuration instance dynamically. It is not a property of the configuration as most other properties defined by this interface. By setting an alternativeBeanHelper
the process of creating configuration instances via reflection can be adapted. (Some specialized configuration builder implementations also use aBeanHelper
to create complex helper objects during construction of their result object.CombinedConfigurationBuilder
for instance supports a complex configuration definition format which may contain several specialized bean declarations.) If no specificBeanHelper
is set, the builder uses the default instance. This implementation stores the passed inBeanHelper
object in the internal parameters map, but uses a reserved key, so that it is not used for the initialization of properties of the managed configuration object. ThefetchBeanHelper()
method can be used to obtain theBeanHelper
instance from a parameters map.- Specified by:
setBeanHelper
in interfaceBasicBuilderProperties<BasicBuilderParameters>
- Parameters:
beanHelper
- theBeanHelper
to be used by the builder- Returns:
- a reference to this object for method chaining
-
setConfigurationDecoder
Sets theConfigurationDecoder
object for this configuration. This object is called when encoded properties are queried using thegetEncodedString()
method. This implementation stores the passed inConfigurationDecoder
object in the internal parameters map.- Specified by:
setConfigurationDecoder
in interfaceBasicBuilderProperties<BasicBuilderParameters>
- Parameters:
decoder
- theConfigurationDecoder
to be used- Returns:
- a reference to this object for method chaining
-
setConversionHandler
Sets theConversionHandler
object for this configuration. This object is responsible for all data type conversions required for accessing configuration properties in a specific target type. If this property is not set, a defaultConversionHandler
is used. This implementation stores the passed inConversionHandler
object in the internal parameters map.- Specified by:
setConversionHandler
in interfaceBasicBuilderProperties<BasicBuilderParameters>
- Parameters:
handler
- theConversionHandler
to be used- Returns:
- a reference to this object for method chaining
-
setDefaultLookups
Adds additional defaultLookup
objects (i.e. lookups which are not associated with a specific prefix) to this configuration object. Note: This method only takes effect if noConfigurationInterpolator
is set using theBasicBuilderProperties.setInterpolator(ConfigurationInterpolator)
method. A defensive copy of the passed in collection is created. A null argument causes all default lookups to be removed from the internal parameters map.- Specified by:
setDefaultLookups
in interfaceBasicBuilderProperties<BasicBuilderParameters>
- Parameters:
lookups
- a collection withLookup
objects to be added as default lookups at the configuration'sConfigurationInterpolator
- Returns:
- a reference to this object for method chaining
- See Also:
-
setInterpolator
Sets theConfigurationInterpolator
to be used for this configuration. Using this method a customConfigurationInterpolator
can be set which can be freely configured. Alternatively, it is possible to add customLookup
objects using other methods provided by this interface. The passed inConfigurationInterpolator
is set without modifications.- Specified by:
setInterpolator
in interfaceBasicBuilderProperties<BasicBuilderParameters>
- Parameters:
ci
- theConfigurationInterpolator
for this configuration- Returns:
- a reference to this object for method chaining
-
setListDelimiterHandler
Sets the value of the listDelimiterHandler property. This property defines the object responsible for dealing with list delimiter and escaping characters. Note:AbstractConfiguration
does not allow setting this property to null. If the defaultListDelimiterHandler
is to be used, do not call this method.- Specified by:
setListDelimiterHandler
in interfaceBasicBuilderProperties<BasicBuilderParameters>
- Parameters:
handler
- theListDelimiterHandler
- Returns:
- a reference to this object for method chaining
-
setLogger
Sets the logger property. With this property a concreteLog
object can be set for the configuration. Thus logging behavior can be controlled.- Specified by:
setLogger
in interfaceBasicBuilderProperties<BasicBuilderParameters>
- Parameters:
log
- theLog
for the configuration produced by this builder- Returns:
- a reference to this object for method chaining
-
setParentInterpolator
Sets the parentConfigurationInterpolator
for this configuration'sConfigurationInterpolator
. Setting a parentConfigurationInterpolator
can be used for defining a default behavior for variables which cannot be resolved. This implementation stores the passed inConfigurationInterpolator
object in the internal parameters map.- Specified by:
setParentInterpolator
in interfaceBasicBuilderProperties<BasicBuilderParameters>
- Parameters:
parent
- the new parentConfigurationInterpolator
- Returns:
- a reference to this object for method chaining
- See Also:
-
setPrefixLookups
Sets additionalLookup
objects for specific prefixes for this configuration object. AllLookup
objects contained in the given map are added to the configuration'sConfigurationInterpolator
. Note: This method only takes effect if noConfigurationInterpolator
is set using theBasicBuilderProperties.setInterpolator(ConfigurationInterpolator)
method. A defensive copy of the passed in map is created. A null argument causes all prefix lookups to be removed from the internal parameters map.- Specified by:
setPrefixLookups
in interfaceBasicBuilderProperties<BasicBuilderParameters>
- Parameters:
lookups
- a map withLookup
objects and their associated prefixes- Returns:
- a reference to this object for method chaining
- See Also:
-
setProperty
Helper method for setting a property value.- Parameters:
key
- the key of the propertyvalue
- the value of the property- Returns:
- a reference to this object
-
setSynchronizer
Sets theSynchronizer
object for this configuration. This object is used to protect this configuration instance against concurrent access. The concreteSynchronizer
implementation used determines whether a configuration instance is thread-safe or not. This implementation stores the passed inSynchronizer
object in the internal parameters map.- Specified by:
setSynchronizer
in interfaceBasicBuilderProperties<BasicBuilderParameters>
- Parameters:
sync
- theSynchronizer
to be used (a value of null means that a defaultSynchronizer
is used)- Returns:
- a reference to this object for method chaining
-
setThrowExceptionOnMissing
Sets the value of the throwExceptionOnMissing property. This property controls the configuration's behavior if missing properties are queried: a value of true causes the configuration to throw an exception, for a value of false it will return null values. (Note: Methods returning a primitive data type will always throw an exception if the property is not defined.)- Specified by:
setThrowExceptionOnMissing
in interfaceBasicBuilderProperties<BasicBuilderParameters>
- Parameters:
b
- the value of the property- Returns:
- a reference to this object for method chaining
-
storeProperty
Sets a property for this parameters object. Properties are stored in an internal map. With this method a new entry can be added to this map. If the value is null, the key is removed from the internal map. This method can be used by sub classes which also store properties in a map.- Parameters:
key
- the key of the propertyvalue
- the value of the property
-