Package org.apache.tamaya.spi

Interface ConfigurationBuilder

public interface ConfigurationBuilder

A builder for creating new instances of Configuration. Builders can be obtained in exactly two ways:

1. By accessing a preinitialized builder from an existing Configuration, by calling Configuration.toBuilder().
2. By accessing an empty builder instance from ConfigurationProvider.getConfigurationBuilder().

After all changes are applied to a builder a new Configuration instance can be created and can be applied by calling build()}.

Method Summary

Modifier and Type	Method	Description
ConfigurationBuilder	addDefaultPropertyConverters()	Add all auto-discoverable property converters to the context built.
ConfigurationBuilder	addDefaultPropertyFilters()	Add all auto-discoverable property filters to the context built.
ConfigurationBuilder	addDefaultPropertySources()	Adds all registered (default) property sources to the context built.
<T> ConfigurationBuilder	addPropertyConverters(TypeLiteral<T> typeToConvert, Collection<PropertyConverter<T>> propertyConverters)	This method can be used for adding PropertyConverters.
default <T> ConfigurationBuilder	addPropertyConverters(TypeLiteral<T> typeToConvert, PropertyConverter<T>... propertyConverters)	This method can be used for adding PropertyConverters.
ConfigurationBuilder	addPropertyFilters(Collection<PropertyFilter> filters)	Adds the given PropertyFilter instances, hereby the instances are added to the end of the createList with highest priority.
default ConfigurationBuilder	addPropertyFilters(PropertyFilter... filters)	Adds the given PropertyFilter instances, hereby the instances are added to the end of the createList with highest priority.
ConfigurationBuilder	addPropertySources(Collection<PropertySource> propertySources)	This method can be used for programmatically adding PropertySources.
default ConfigurationBuilder	addPropertySources(PropertySource... propertySources)	This method can be used for adding PropertySources.
Configuration	build()	Builds a new Configuration based on the data in this builder.
ConfigurationBuilder	decreasePriority(PropertySource propertySource)	Decreases the priority of the given property source, by moving it towards the start of the chain of property sources.
ClassLoader	getClassLoader()	Get the classloader used by this builder.
Map<TypeLiteral<?>,List<PropertyConverter<?>>>	getPropertyConverter()	Access the current registered property converters.
List<PropertyFilter>	getPropertyFilters()	Access the current chain of property filters.
List<PropertySource>	getPropertySources()	Access the current chain of property sources.
ConfigurationBuilder	highestPriority(PropertySource propertySource)	Increases the priority of the given property source to be maximal, by moving it to the tail of the of property source chain.
ConfigurationBuilder	increasePriority(PropertySource propertySource)	Increases the priority of the given property source, by moving it towards the end of the chain of property sources.
ConfigurationBuilder	lowestPriority(PropertySource propertySource)	Decreases the priority of the given property source to be minimal, by moving it to the start of the chain of property source chain.
ConfigurationBuilder	removePropertyConverters(TypeLiteral<?> typeToConvert)	Removes all converters for the given type, which actually renders a given type unsupported for type conversion.
<T> ConfigurationBuilder	removePropertyConverters(TypeLiteral<T> typeToConvert, Collection<PropertyConverter<T>> propertyConverters)	Removes the given PropertyConverter instances for the given type, if existing.
default <T> ConfigurationBuilder	removePropertyConverters(TypeLiteral<T> typeToConvert, PropertyConverter<T>... propertyConverters)	Removes the given PropertyConverter instances for the given type, if existing.
ConfigurationBuilder	removePropertyFilters(Collection<PropertyFilter> filter)	Removes the given PropertyFilter instances, if existing.
default ConfigurationBuilder	removePropertyFilters(PropertyFilter... filters)	Removes the given PropertyFilter instances, if existing.
ConfigurationBuilder	removePropertySources(Collection<PropertySource> propertySources)	Removes the given property sources, if existing.
default ConfigurationBuilder	removePropertySources(PropertySource... propertySources)	Removes the given property sources, if existing.
ConfigurationBuilder	setClassLoader(ClassLoader classLoader)	Set the classloader to be used for loading of configuration resources, equals to setServiceContext(ServiceContextManager.getServiceContext(classLoader)).
default ConfigurationBuilder	setConfiguration(Configuration config)	Init this builder instance with the given Configuration instance.
ConfigurationBuilder	setContext(ConfigurationContext context)	Init this builder instance with the given ConfigurationContext instance.
ConfigurationBuilder	setMeta(String property, String key, String value)	Adds (overrides existing value) the given sources as property sources.
ConfigurationBuilder	setMeta(String property, Map<String,String> metaData)	Adds (overrides existing value with same same keys) the given sources as property sources.
ConfigurationBuilder	setServiceContext(ServiceContext serviceContext)	Sets the ServiceContext to be used.
ConfigurationBuilder	sortPropertyConverter(Comparator<PropertyConverter> comparator)	Sorts the current registered property converters using the given comparator.
ConfigurationBuilder	sortPropertyFilter(Comparator<PropertyFilter> comparator)	Sorts the current registered property filters using the given comparator.
ConfigurationBuilder	sortPropertySources(Comparator<PropertySource> comparator)	Sorts the current registered property sources using the given comparator.

Method Detail

setClassLoader

ConfigurationBuilder setClassLoader(ClassLoader classLoader)

Set the classloader to be used for loading of configuration resources, equals to setServiceContext(ServiceContextManager.getServiceContext(classLoader)).

Parameters:

classLoader - the classloader, not null.

Returns:

the builder for chaining.

See Also:

getClassLoader()

getClassLoader

ClassLoader getClassLoader()

Get the classloader used by this builder.

Returns:

the classloader, never null.

See Also:

setClassLoader(ClassLoader)

setServiceContext

ConfigurationBuilder setServiceContext(ServiceContext serviceContext)

Sets the ServiceContext to be used.

Parameters:

serviceContext - the serviceContext, nuo null.

Returns:

this instance for chaining.

setConfiguration

default ConfigurationBuilder setConfiguration(Configuration config)

Init this builder instance with the given Configuration instance. This method will use any existing property sources, filters, converters and the combination policy of the given Configuration and initialize the current builder with them. All previous property sources, filters, converters and the combination policy of this instance will be replaced.

Parameters:

config - the Configuration instance to be used, not null.

Returns:

this builder, for chaining, never null.

setContext

ConfigurationBuilder setContext(ConfigurationContext context)

Init this builder instance with the given ConfigurationContext instance. This method will use any existing property sources, filters, converters and the combination policy of the given ConfigurationContext and initialize the current builder with them. All previous property sources, filters, converters and the combination policy of this instance will be replaced.

Parameters:

context - the ConfigurationContext instance to be used, not null.

Returns:

this builder, for chaining, never null.

addPropertySources

default ConfigurationBuilder addPropertySources(PropertySource... propertySources)

This method can be used for adding PropertySources. Hereby the property source is added to the tail of property sources with lowest priority regardless of its current ordinal value. To sort the property sources based on their ordinals call sortPropertySources(java.util.Comparator<org.apache.tamaya.spi.PropertySource>).

Parameters:

propertySources - the PropertySources to addPropertyValue

Returns:

this builder, for chaining, never null.

Throws:

IllegalArgumentException - If a property source with a given name already exists.

setMeta

ConfigurationBuilder setMeta(String property,
                             String key,
                             String value)

Adds (overrides existing value) the given sources as property sources.

Parameters:

property - the property key, not null,

key - the key, not null.

value - the value, not null.

Returns:

the current configuration builder.

setMeta

ConfigurationBuilder setMeta(String property,
                             Map<String,String> metaData)

Adds (overrides existing value with same same keys) the given sources as property sources.

Parameters:

property - the property key, not null,

metaData - the metadata, not null.

Returns:

the current configuration builder.

addPropertySources

ConfigurationBuilder addPropertySources(Collection<PropertySource> propertySources)

This method can be used for programmatically adding PropertySources. Hereby the property source is added to the tail of property sources with lowest priority regardless of its current ordinal value. To sort the property sources based on their ordinals call sortPropertySources(java.util.Comparator<org.apache.tamaya.spi.PropertySource>).

Parameters:

propertySources - the PropertySources to addPropertyValue

Returns:

this builder, for chaining, never null.

Throws:

IllegalArgumentException - If a property source with a given name already exists.

addDefaultPropertySources

ConfigurationBuilder addDefaultPropertySources()

Adds all registered (default) property sources to the context built. The sources are ordered based on their ordinal values and added to the chain of property sources with higher priority.

Returns:

this builder, for chaining, never null.

removePropertySources

default ConfigurationBuilder removePropertySources(PropertySource... propertySources)

Removes the given property sources, if existing. The existing order of property sources is preserved.

Parameters:

propertySources - the property sources to remove, not null.

Returns:

the builder for chaining.

removePropertySources

ConfigurationBuilder removePropertySources(Collection<PropertySource> propertySources)

Removes the given property sources, if existing. The existing order of property sources is preserved.

Parameters:

propertySources - the property sources to remove, not null.

Returns:

the builder for chaining.

getPropertySources

List<PropertySource> getPropertySources()

Access the current chain of property sources. Items at the end of the createList have precedence/higher significance.

Returns:

the property source chain, never null.

getPropertyFilters

List<PropertyFilter> getPropertyFilters()

Access the current chain of property filters. Items at the end of the createList have precedence/higher significance.

Returns:

the property filter chain, never null.

getPropertyConverter

Map<TypeLiteral<?>,List<PropertyConverter<?>>> getPropertyConverter()

Access the current registered property converters.

Returns:

the current registered property converters.

increasePriority

ConfigurationBuilder increasePriority(PropertySource propertySource)

Increases the priority of the given property source, by moving it towards the end of the chain of property sources. If the property source given is already at the end this method has no effect. This operation does not change any ordinal values.

Parameters:

propertySource - the property source to be incresed regarding its significance.

Returns:

the builder for chaining.

Throws:

IllegalArgumentException - If no such property source exists in the current chain.

decreasePriority

ConfigurationBuilder decreasePriority(PropertySource propertySource)

Decreases the priority of the given property source, by moving it towards the start of the chain of property sources. If the property source given is already the first this method has no effect. This operation does not change any ordinal values.

Parameters:

propertySource - the property source to be decresed regarding its significance.

Returns:

the builder for chaining.

Throws:

IllegalArgumentException - If no such property source exists in the current chain.

highestPriority

ConfigurationBuilder highestPriority(PropertySource propertySource)

Increases the priority of the given property source to be maximal, by moving it to the tail of the of property source chain. If the property source given is already the last item this method has no effect. This operation does not change any ordinal values.

Parameters:

propertySource - the property source to be maximized regarding its significance.

Returns:

the builder for chaining.

Throws:

IllegalArgumentException - If no such property source exists in the current chain.

lowestPriority

ConfigurationBuilder lowestPriority(PropertySource propertySource)

Decreases the priority of the given property source to be minimal, by moving it to the start of the chain of property source chain. If the property source given is already the first item this method has no effect. This operation does not change any ordinal values.

Parameters:

propertySource - the property source to be minimized regarding its significance.

Returns:

the builder for chaining.

Throws:

IllegalArgumentException - If no such property source exists in the current chain.

addPropertyFilters

default ConfigurationBuilder addPropertyFilters(PropertyFilter... filters)

Adds the given PropertyFilter instances, hereby the instances are added to the end of the createList with highest priority. The ordering of existing property filters remains unchanged. To sort the property filters call sortPropertyFilter(java.util.Comparator<org.apache.tamaya.spi.PropertyFilter>).

Parameters:

filters - the filters to addPropertyValue

Returns:

this builder, for chaining, never null.

addPropertyFilters

ConfigurationBuilder addPropertyFilters(Collection<PropertyFilter> filters)

Adds the given PropertyFilter instances, hereby the instances are added to the end of the createList with highest priority. The ordering of existing property filters remains unchanged. To sort the property filters call sortPropertyFilter(java.util.Comparator<org.apache.tamaya.spi.PropertyFilter>).

Parameters:

filters - the filters to addPropertyValue

Returns:

this builder, for chaining, never null.

addDefaultPropertyFilters

ConfigurationBuilder addDefaultPropertyFilters()

Add all auto-discoverable property filters to the context built.

Returns:

this builder, for chaining, never null.

removePropertyFilters

default ConfigurationBuilder removePropertyFilters(PropertyFilter... filters)

Removes the given PropertyFilter instances, if existing. The order of the remaining filters is preserved.

Parameters:

filters - the filter to remove

Returns:

this builder, for chaining, never null.

removePropertyFilters

ConfigurationBuilder removePropertyFilters(Collection<PropertyFilter> filter)

Removes the given PropertyFilter instances, if existing. The order of the remaining filters is preserved.

Parameters:

filter - the filter to remove

Returns:

this builder, for chaining, never null.

addPropertyConverters

default <T> ConfigurationBuilder addPropertyConverters(TypeLiteral<T> typeToConvert,
                                                       PropertyConverter<T>... propertyConverters)

This method can be used for adding PropertyConverters. Converters are added at the end after any existing converters. For converters already registered for the current target type the method has no effect.

Type Parameters:

T - the target type.

Parameters:

typeToConvert - the type for which the converter is used

propertyConverters - the PropertyConverters to addPropertyValue for this type

Returns:

this builder, for chaining, never null.

addPropertyConverters

<T> ConfigurationBuilder addPropertyConverters(TypeLiteral<T> typeToConvert,
                                               Collection<PropertyConverter<T>> propertyConverters)

This method can be used for adding PropertyConverters. Converters are added at the end after any existing converters. For converters already registered for the current target type the method has no effect.

Type Parameters:

T - the target type.

Parameters:

typeToConvert - the type for which the converter is used

propertyConverters - the PropertyConverters to addPropertyValue for this type

Returns:

this builder, for chaining, never null.

addDefaultPropertyConverters

ConfigurationBuilder addDefaultPropertyConverters()

Add all auto-discoverable property converters to the context built.

Returns:

this builder, for chaining, never null.

removePropertyConverters

default <T> ConfigurationBuilder removePropertyConverters(TypeLiteral<T> typeToConvert,
                                                          PropertyConverter<T>... propertyConverters)

Removes the given PropertyConverter instances for the given type, if existing.

Type Parameters:

T - the target type.

Parameters:

typeToConvert - the type which the converter is used

propertyConverters - the converter to remove

Returns:

this builder, for chaining, never null.

removePropertyConverters

<T> ConfigurationBuilder removePropertyConverters(TypeLiteral<T> typeToConvert,
                                                  Collection<PropertyConverter<T>> propertyConverters)

Removes the given PropertyConverter instances for the given type, if existing.

Type Parameters:

T - the target type.

Parameters:

typeToConvert - the type which the converter is used

propertyConverters - the converter to remove

Returns:

this builder, for chaining, never null.

removePropertyConverters

ConfigurationBuilder removePropertyConverters(TypeLiteral<?> typeToConvert)

Removes all converters for the given type, which actually renders a given type unsupported for type conversion.

Parameters:

typeToConvert - the type which the converter is used

Returns:

this builder, for chaining, never null.

sortPropertySources

ConfigurationBuilder sortPropertySources(Comparator<PropertySource> comparator)

Sorts the current registered property sources using the given comparator.

NOTE: property sources at the beginning have minimal significance.

Parameters:

comparator - the comparator to be used, not null.

Returns:

this instance for chaining.

sortPropertyFilter

ConfigurationBuilder sortPropertyFilter(Comparator<PropertyFilter> comparator)

Sorts the current registered property filters using the given comparator.

NOTE: property filters at the beginning have minimal significance.

Parameters:

comparator - the comparator to be used, not null.

Returns:

this instance for chaining.

sortPropertyConverter

ConfigurationBuilder sortPropertyConverter(Comparator<PropertyConverter> comparator)

Sorts the current registered property converters using the given comparator.

NOTE: property converters at the beginning have minimal significance.

Parameters:

comparator - the comparator to be used, not null.

Returns:

this instance for chaining.

build

Configuration build()

Builds a new Configuration based on the data in this builder. The ordering of property sources and property filters is not changed, regardless of their ordinals. For ensure a certain ordering/significance use sortPropertyFilter(Comparator) and/or sortPropertySources(Comparator) before building the context.

Returns:

the final configuration, never null.