Package org.apache.tamaya.spi

Interface PropertySource

public interface PropertySource

This interface models a provider that serves configuration properties. The contained properties may be read from a Map of single or several sources (composite). PropertySources are the building blocks of the final configuration.

Implementation Requirements

Implementations of this interface must be

• Thread safe.

A PropertySourceProvider will current picked up via the ServiceLoader mechanism and can be registered via META-INF/services/org.apache.tamaya.spi.PropertySource

If you like to register multiple PropertySources at the same time you can use the PropertySourceProvider interface.

Field Summary

Fields

Modifier and Type	Field	Description
static PropertySource	EMPTY	A resusable instance of an empty PropertySource.
static String	TAMAYA_ORDINAL	property name to override default tamaya ordinals

Method Summary

Modifier and Type	Method	Description
default void	addChangeListener(BiConsumer<Set<String>,PropertySource> l)	Add a change listener for this properrty source.
PropertyValue	get(String key)	Access a property.
default ChangeSupport	getChangeSupport()	Get the support for reporting changes to property sources provided by this instance.
String	getName()	Get the name of the property source.
default int	getOrdinal()	The ordinal value is the default ordering parameter which definines the default order of auto-discovered property sources.
Map<String,PropertyValue>	getProperties()	Access the current properties as Set.
default String	getVersion()	Get the current version.
default boolean	isScannable()	Deprecated. will be removed.
default void	removeAllChangeListeners()	Removes all registered change listeners, if any.
default void	removeChangeListener(BiConsumer<Set<String>,PropertySource> l)	Removes a change listener for this properrty source.

Field Detail

TAMAYA_ORDINAL

static final String TAMAYA_ORDINAL

property name to override default tamaya ordinals

See Also:

Constant Field Values

EMPTY

static final PropertySource EMPTY

A resusable instance of an empty PropertySource.

Method Detail

getOrdinal

default int getOrdinal()

The ordinal value is the default ordering parameter which definines the default order of auto-discovered property sources. Ordering of property sources is important since values from property sources with higher ordinal values override values from less significant property sources. By default Tamaya includes the following property sources:

1. Properties file values (/META-INF/javaconfiguration.properties) (ordinal 100)
2. JNDI values (ordinal 200, only when adding the tamaya-jndi extension module)
3. Environment properties (ordinal 300)
4. System properties (ordinal 1000)

Important Hints for custom implementations:

If a custom implementation should be invoked before the default implementations, use a value > 1000

If a custom implementation should be invoked after the default implementations, use a value < 100

Reordering of the default order of the config-sources:

Example: If the properties file/s should be used before the other implementations, you have to configure an ordinal > 1000. That means, you have to addPropertyValue e.g. tamaya.ordinal=401 to /META-INF/javaconfiguration.properties . Hint: In case of property files every file is handled as independent config-source, but all of them have ordinal 400 by default (and can be reordered in a fine-grained manner.

In cases where it is not possible to change a config sources ordinal value, you may have several options:

• you can use a ConfigurationBuilder to redefine the source order and finally use ConfigurationProvider.setConfiguration(Configuration) to change the current default Configuration.
• finally, the implementor of this API may define alternate mechanism to reconfigure an ordinal in a vendor specific way.

Returns:

the 'importance' aka ordinal of the configured values. The higher, the more important.

getName

String getName()

Get the name of the property source. The name should be unique for the type of source, whereas the id is used to ensure unique identity, either locally or remotely.

Returns:

the configuration's name, never null.

get

PropertyValue get(String key)

Access a property.

Parameters:

key - the property's key, not null.

Returns:

the property value mapProperties, where mapProperties.current(key) == value, including also any metadata. In case a value is null, simply return null.

getProperties

Map<String,PropertyValue> getProperties()

Access the current properties as Set. The resulting Map may not return all items accessible, e.g. when the underlying storage does not support iteration of its entries. null

Returns:

the corresponding mapProperties, never null.

isScannable

@Deprecated
default boolean isScannable()

Deprecated. will be removed.

Determines if this config source can be scanned for its createList of properties.

PropertySources which are not scannable might not be able to find all the configured values to provide via getProperties(). This might happen if the underlying storage doesn't support listing.

Returns:

true if this PropertySource can be scanned for its createList of properties, false if it cannot/should not be scanned.

getChangeSupport

default ChangeSupport getChangeSupport()

Get the support for reporting changes to property sources provided by this instance. This support type should never change during a property source's lifetime.

Returns:

the change support of this property source, not null.

getVersion

default String getVersion()

Get the current version. A new version signals that it is known that properties have changed for this property source. This is especially useful, when getChangeSupport() is ChangeSupport.SUPPORTED. The content and format of the version String is imeplemtation specific. We recommend to addPropertyValue information such as the loading timestamp, the source systems read or whatever is appropriate. By default this method returns "N/A".

Returns:

the version this property source, never null.

addChangeListener

default void addChangeListener(BiConsumer<Set<String>,PropertySource> l)

Add a change listener for this properrty source.

Parameters:

l - the listner, not null.

removeChangeListener

default void removeChangeListener(BiConsumer<Set<String>,PropertySource> l)

Removes a change listener for this properrty source.

Parameters:

l - the listner, not null.

removeAllChangeListeners

default void removeAllChangeListeners()

Removes all registered change listeners, if any.