org.apache.tamaya.spi

Interface ConfigurationContextBuilder

public interface ConfigurationContextBuilder

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

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

After all changes are applied to a builder a new ConfigurationContext instance can be created and can be applied by calling ConfigurationProvider.setConfigurationContext(org.apache.tamaya.spi.ConfigurationContext).

Method Summary

Modifier and Type	Method and Description
ConfigurationContextBuilder	addDefaultPropertyConverters() Add all registered (default) property converters to the context built.
ConfigurationContextBuilder	addDefaultPropertyFilters() Add all registered (default) property filters to the context built.
ConfigurationContextBuilder	addDefaultPropertySources() Add all registered (default) property sources to the context built.
<T> ConfigurationContextBuilder	addPropertyConverters(TypeLiteral<T> typeToConvert, Collection<PropertyConverter<T>> propertyConverters) This method can be used for adding PropertyConverters.
<T> ConfigurationContextBuilder	addPropertyConverters(TypeLiteral<T> typeToConvert, PropertyConverter<T>... propertyConverters) This method can be used for adding PropertyConverters.
ConfigurationContextBuilder	addPropertyFilters(Collection<PropertyFilter> filters) Adds the given PropertyFilter instances, hereby the instances are added to the end of the list with highest priority.
ConfigurationContextBuilder	addPropertyFilters(PropertyFilter... filters) Adds the given PropertyFilter instances, hereby the instances are added to the end of the list with highest priority.
ConfigurationContextBuilder	addPropertySources(Collection<PropertySource> propertySources) This method can be used for programmatically adding PropertySources.
ConfigurationContextBuilder	addPropertySources(PropertySource... propertySources) This method can be used for adding PropertySources.
ConfigurationContext	build() Builds a new ConfigurationContext based on the data in this builder.
ConfigurationContextBuilder	decreasePriority(PropertySource propertySource) Decreases the priority of the given property source, by moving it towards the start of the chain of property sources.
Map<TypeLiteral<?>,Collection<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.
ConfigurationContextBuilder	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.
ConfigurationContextBuilder	increasePriority(PropertySource propertySource) Increases the priority of the given property source, by moving it towards the end of the chain of property sources.
ConfigurationContextBuilder	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.
ConfigurationContextBuilder	removePropertyConverters(TypeLiteral<?> typeToConvert) Removes all converters for the given type, which actually renders a given type unsupported for type conversion.
<T> ConfigurationContextBuilder	removePropertyConverters(TypeLiteral<T> typeToConvert, Collection<PropertyConverter<T>> propertyConverters) Removes the given PropertyConverter instances for the given type, if existing.
<T> ConfigurationContextBuilder	removePropertyConverters(TypeLiteral<T> typeToConvert, PropertyConverter<T>... propertyConverters) Removes the given PropertyConverter instances for the given type, if existing.
ConfigurationContextBuilder	removePropertyFilters(Collection<PropertyFilter> filters) Removes the given PropertyFilter instances, if existing.
ConfigurationContextBuilder	removePropertyFilters(PropertyFilter... filters) Removes the given PropertyFilter instances, if existing.
ConfigurationContextBuilder	removePropertySources(Collection<PropertySource> propertySources) Removes the given property sources, if existing.
ConfigurationContextBuilder	removePropertySources(PropertySource... propertySources) Removes the given property sources, if existing.
ConfigurationContextBuilder	setContext(ConfigurationContext context) Init this builder instance with the given ConfigurationContext instance.
ConfigurationContextBuilder	setPropertyValueCombinationPolicy(PropertyValueCombinationPolicy policy) Sets the PropertyValueCombinationPolicy used to evaluate the final property values.
ConfigurationContextBuilder	sortPropertyFilter(Comparator<PropertyFilter> comparator) Sorts the current registered property filters using the given comparator.
ConfigurationContextBuilder	sortPropertySources(Comparator<PropertySource> comparator) Sorts the current registered property sources using the given comparator.

Method Detail

setContext

ConfigurationContextBuilder 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.

Parameters:

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

Returns:

this builder, for chaining, never null.

addPropertySources

ConfigurationContextBuilder 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 add

Returns:

this builder, for chaining, never null.

Throws:

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

addPropertySources

ConfigurationContextBuilder 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 add

Returns:

this builder, for chaining, never null.

Throws:

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

addDefaultPropertySources

ConfigurationContextBuilder addDefaultPropertySources()

Add 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

ConfigurationContextBuilder 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

ConfigurationContextBuilder 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 list have precedence/more 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 list have precedence/more significance.

Returns:

the property source chain, never null.

getPropertyConverter

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

Access the current registered property converters.

Returns:

the current registered property converters.

increasePriority

ConfigurationContextBuilder 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

ConfigurationContextBuilder 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

ConfigurationContextBuilder 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

ConfigurationContextBuilder 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

ConfigurationContextBuilder addPropertyFilters(PropertyFilter... filters)

Adds the given PropertyFilter instances, hereby the instances are added to the end of the list 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 add

Returns:

this builder, for chaining, never null.

addPropertyFilters

ConfigurationContextBuilder addPropertyFilters(Collection<PropertyFilter> filters)

Adds the given PropertyFilter instances, hereby the instances are added to the end of the list 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 add

Returns:

this builder, for chaining, never null.

addDefaultPropertyFilters

ConfigurationContextBuilder addDefaultPropertyFilters()

Add all registered (default) property filters to the context built.

Returns:

this builder, for chaining, never null.

removePropertyFilters

ConfigurationContextBuilder 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

ConfigurationContextBuilder removePropertyFilters(Collection<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.

addPropertyConverters

<T> ConfigurationContextBuilder 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 for

propertyConverters - the PropertyConverters to add for this type

Returns:

this builder, for chaining, never null.

addPropertyConverters

<T> ConfigurationContextBuilder 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 for

propertyConverters - the PropertyConverters to add for this type

Returns:

this builder, for chaining, never null.

addDefaultPropertyConverters

ConfigurationContextBuilder addDefaultPropertyConverters()

Add all registered (default) property converters to the context built.

Returns:

this builder, for chaining, never null.

removePropertyConverters

<T> ConfigurationContextBuilder 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 for

propertyConverters - the converter to remove

Returns:

this builder, for chaining, never null.

removePropertyConverters

<T> ConfigurationContextBuilder 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 for

propertyConverters - the converter to remove

Returns:

this builder, for chaining, never null.

removePropertyConverters

ConfigurationContextBuilder 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 for

Returns:

this builder, for chaining, never null.

sortPropertySources

ConfigurationContextBuilder 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

ConfigurationContextBuilder 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.

setPropertyValueCombinationPolicy

ConfigurationContextBuilder setPropertyValueCombinationPolicy(PropertyValueCombinationPolicy policy)

Sets the PropertyValueCombinationPolicy used to evaluate the final property values.

Parameters:

policy - the PropertyValueCombinationPolicy used, not null.

Returns:

this builder, for chaining, never null.

build

ConfigurationContext build()

Builds a new ConfigurationContext 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 call sortPropertyFilter(Comparator) and/or sortPropertySources(Comparator) before building the context.

Returns:

the final context to be used to create a configuration.

See Also:

ConfigurationProvider.createConfiguration(ConfigurationContext)