de.smartics.properties.api.config.domain
Interface ConfigurationProperties

All Known Subinterfaces:

ConfigurationPropertiesManagement, ConfigurationPropertiesManagementSpi, ConfigurationPropertiesSpi, SerializableConfigurationProperties, SerializableConfigurationPropertiesManagement, SerializableConfigurationPropertiesManagementSpi

All Known Implementing Classes:

AbstractCacheConfigurationPropertiesManagement, AbstractConfigurationProperties, AbstractConfigurationPropertiesManagement, AbstractInMemoryConfigurationProperties, BootConfigurationProperties, CacheConfigurationPropertiesManagement, ClasspathConfigurationProperties, ConfigurationPropertiesManagementProxy, ConfigurationPropertiesManagementWithDefaults, ConfigurationPropertiesProxy, DataSourceConfigurationProperties, PropertiesConfigurationProperties, SerializableCacheConfigurationPropertiesManagement

public interface ConfigurationProperties

Provides access to all configuration properties for a given application in a given environment.

There are two ways to access property values.

1. Use getProperties(Class) to obtain an implementation of an interface that provides access to the property values through its methods. This is the recommended way to deal with properties.
2. Use one of the getProperty methods. This access may be more convenient, if the context deals with property keys that are provided by the user (e.g. from an UI).

Implementation Notes:

This interface is intended to be implemented by service providers. API users are intended to us this interface to access properties. For details on creating instances of classes implementing this interface please refer to de.smartics.properties.api.config.

Method Summary

void	addPropertyChangeListener(PropertyChangeListener listener) Adds the given listener to track any property changes.
void	addPropertyChangeListener(PropertyKey name, PropertyChangeListener listener) Adds the given listener as a listener to the given property.
PropertiesContext	getContext(Class<?> declaringType) Returns the properties context for the declaring type.
PropertyContext	getContext(PropertyDescriptor descriptor) Returns the properties context the property described by the given descriptor is part of.
ConfigurationKey	getKey() Returns the key of the configuration.
<T> T	getProperties(Class<T> propertiesInterface) Returns a implementation of the given interface that has access to the property keys, the property descriptors and the properties itself, when they are declared in the given interface.
Property	getProperty(PropertyDescriptor descriptor) Returns the property for the given descriptor.
Property	getProperty(PropertyDescriptor descriptor, Object defaultValue) Returns the property for the given descriptor, allowing to transparently provide a default value to be returned in case the property has not been set.
Property	getProperty(PropertyKey key) Returns the property for the given key.
Property	getProperty(String key) Returns the property for the given key.
Property	getProperty(String key, Object defaultValue) Returns the property for the given key, allowing to transparently provide a default value to be returned in case the property has not been set.
Object	getPropertyValue(PropertyDescriptor descriptor) Returns the property value for the given descriptor.
Object	getPropertyValue(PropertyDescriptor descriptor, Object defaultValue) Returns the property value for the given descriptor, allowing to transparently provide a default value to be returned in case the property has not been set.
Object	getPropertyValue(PropertyKey key) Returns the property value for the given key.
Object	getPropertyValue(String key) Returns the property value for the given key.
Object	getPropertyValue(String key, Object defaultValue) Returns the property value for the given key, allowing to transparently provide a default value to be returned in case the property has not been set.
String	getPropertyValueAsString(PropertyDescriptor descriptor) Returns the property string value for the given descriptor.
String	getPropertyValueAsString(PropertyDescriptor descriptor, Object defaultValue) Returns the property string value for the given descriptor.
String	getPropertyValueAsString(String key) Returns the property string value for the given key.
String	getPropertyValueAsString(String key, Object defaultValue) Returns the property string value for the given key.
ResolvedProperty	getResolvedProperty(PropertyDescriptor descriptor, Object defaultValue) Returns the resolved property for the given descriptor's key, allowing to transparently provide a default value to be returned in case the property has not been set.
ResolvedProperty	getResolvedProperty(PropertyKey key, Object defaultValue) Returns the resolved property for the given key, allowing to transparently provide a default value to be returned in case the property has not been set.
ResolvedProperty	getResolvedProperty(String key, Object defaultValue) Returns the resolved property for the given key, allowing to transparently provide a default value to be returned in case the property has not been set.
void	removePropertyChangeListener(PropertyChangeListener listener) Removes the given listener to stop tracking property changes.
void	removePropertyChangeListener(PropertyKey name, PropertyChangeListener listener) Removes the given listener as a listener to the given property.
SerializableConfigurationProperties	toSerializable() Creates a serializable variant of this implementation.
void	validate() Validates all properties in the given configuration in a non-lenient fashion.
void	validate(boolean lenient) Validates all properties in the given configuration.

Method Detail

getKey

ConfigurationKey getKey()

Returns the key of the configuration.

Returns:

the key of the configuration. Never null.

getContext

PropertiesContext getContext(Class<?> declaringType)
                             throws NullPointerException

Returns the properties context for the declaring type. The declaring type is the interface type annotated with the PropertySet annotation. The context provides information about the properties of that set.

Parameters:

declaringType - the type that declares the properties whose context is requested.

Returns:

the context for the properties declared by the given type.

Throws:

NullPointerException - if declaringType is null.

getContext

PropertyContext getContext(PropertyDescriptor descriptor)
                           throws NullPointerException

Returns the properties context the property described by the given descriptor is part of.

Parameters:

descriptor - the descriptor of the property whose context is requested.

Returns:

the context of the property described by the descriptor.

Throws:

NullPointerException - if descriptor is null.

getProperties

<T> T getProperties(Class<T> propertiesInterface)

Returns a implementation of the given interface that has access to the property keys, the property descriptors and the properties itself, when they are declared in the given interface. The interface must be annotated with an PropertySet annotation.

Type Parameters:

T - type variable to enable a type save return value.

Parameters:

propertiesInterface - a PropertySet annotated interface for which a implementation to access the property keys, descriptors and values is requested.

Returns:

a implementation of the given interface to access property information.

getPropertyValue

Object getPropertyValue(PropertyDescriptor descriptor)
                        throws NullPointerException,
                               PropertyValidationException

Returns the property value for the given descriptor.

Parameters:

descriptor - the key to the property.

Returns:

the value to the property. A value of null is returned in cause of an optional property being not set.

Throws:

NullPointerException - if descriptor is null.

PropertyValidationException - if the property is invalid according to its constraints.

getPropertyValue

Object getPropertyValue(String key)
                        throws IllegalArgumentException,
                               UnknownPropertyException,
                               PropertyValidationException

Returns the property value for the given key.

Parameters:

key - the key to the property.

Returns:

the value to the property. A value of null is returned in cause of an optional property being not set.

Throws:

IllegalArgumentException - if key is blank.

UnknownPropertyException - if key is not known.

PropertyValidationException - if the property is invalid according to its constraints.

getPropertyValue

Object getPropertyValue(PropertyKey key)
                        throws IllegalArgumentException,
                               UnknownPropertyException,
                               PropertyValidationException

Returns the property value for the given key.

Parameters:

key - the key to the property.

Returns:

the value to the property. A value of null is returned in cause of an optional property being not set.

Throws:

IllegalArgumentException - if key is blank.

UnknownPropertyException - if key is not known.

PropertyValidationException - if the property is invalid according to its constraints.

getPropertyValue

Object getPropertyValue(PropertyDescriptor descriptor,
                        Object defaultValue)
                        throws NullPointerException,
                               PropertyValueConversionException,
                               PropertyValidationException,
                               UnknownPropertyException

Returns the property value for the given descriptor, allowing to transparently provide a default value to be returned in case the property has not been set.

Parameters:

descriptor - the key to the property.

defaultValue - the default value to use in case no value has been specified.

Returns:

the value to the property. A value of null is returned in cause of an optional property being not set.

Throws:

NullPointerException - if descriptor is null.

PropertyValueConversionException - if conversion fails.

PropertyValidationException - if the property is invalid according to its constraints.

UnknownPropertyException - if the requested property is not known to the system.

getPropertyValue

Object getPropertyValue(String key,
                        Object defaultValue)
                        throws IllegalArgumentException,
                               UnknownPropertyException,
                               PropertyValidationException

Returns the property value for the given key, allowing to transparently provide a default value to be returned in case the property has not been set.

Parameters:

key - the key to the property.

defaultValue - the default value to use in case no value has been specified.

Returns:

the value to the property. A value of null is returned in cause of an optional property being not set.

Throws:

IllegalArgumentException - if key is blank.

UnknownPropertyException - if key is not known.

PropertyValidationException - if the property is invalid according to its constraints.

getProperty

Property getProperty(String key)
                     throws IllegalArgumentException,
                            UnknownPropertyException

Returns the property for the given key.

Parameters:

key - the unique key of the property.

Returns:

the requested property.

Throws:

IllegalArgumentException - if key is blank.

UnknownPropertyException - if key is not known.

getProperty

Property getProperty(String key,
                     Object defaultValue)
                     throws IllegalArgumentException,
                            UnknownPropertyException

Returns the property for the given key, allowing to transparently provide a default value to be returned in case the property has not been set.

Parameters:

key - the unique key of the property.

defaultValue - the default value to use in case no value has been specified.

Returns:

the requested property.

Throws:

IllegalArgumentException - if key is blank.

UnknownPropertyException - if key is not known.

getProperty

Property getProperty(PropertyKey key)
                     throws IllegalArgumentException,
                            UnknownPropertyException

Returns the property for the given key.

Parameters:

key - the unique key of the property.

Returns:

the requested property.

Throws:

IllegalArgumentException - if key is blank.

UnknownPropertyException - if key is not known.

getProperty

Property getProperty(PropertyDescriptor descriptor)
                     throws NullPointerException,
                            UnknownPropertyException

Returns the property for the given descriptor.

Parameters:

descriptor - the descriptor containing the unique key of the property.

Returns:

the requested property.

Throws:

NullPointerException - if descriptor is null.

UnknownPropertyException - if the key of the descriptor is not known.

getProperty

Property getProperty(PropertyDescriptor descriptor,
                     Object defaultValue)
                     throws NullPointerException,
                            UnknownPropertyException

Returns the property for the given descriptor, allowing to transparently provide a default value to be returned in case the property has not been set.

Parameters:

descriptor - the descriptor containing the unique key of the property.

defaultValue - the default value to use in case no value has been specified.

Returns:

the requested property.

Throws:

NullPointerException - if descriptor is null.

UnknownPropertyException - if the key of the descriptor is not known.

getResolvedProperty

ResolvedProperty getResolvedProperty(PropertyDescriptor descriptor,
                                     Object defaultValue)
                                     throws IllegalArgumentException,
                                            UnknownPropertyException,
                                            PropertyValidationException

Returns the resolved property for the given descriptor's key, allowing to transparently provide a default value to be returned in case the property has not been set.

Parameters:

descriptor - descriptor key to the property.

defaultValue - the default value to use in case no value has been specified.

Returns:

the resolved property. Never null, although the value / resolved value of the returned property may be null.

Throws:

IllegalArgumentException - if key is blank.

UnknownPropertyException - if key is not known.

PropertyValidationException - if the property is invalid according to its constraints.

getResolvedProperty

ResolvedProperty getResolvedProperty(PropertyKey key,
                                     Object defaultValue)
                                     throws IllegalArgumentException,
                                            UnknownPropertyException,
                                            PropertyValidationException

Returns the resolved property for the given key, allowing to transparently provide a default value to be returned in case the property has not been set.

Parameters:

key - the key to the property.

defaultValue - the default value to use in case no value has been specified.

Returns:

the resolved property. Never null, although the value / resolved value of the returned property may be null.

Throws:

IllegalArgumentException - if key is blank.

UnknownPropertyException - if key is not known.

PropertyValidationException - if the property is invalid according to its constraints.

getResolvedProperty

ResolvedProperty getResolvedProperty(String key,
                                     Object defaultValue)
                                     throws IllegalArgumentException,
                                            UnknownPropertyException,
                                            PropertyValidationException

Returns the resolved property for the given key, allowing to transparently provide a default value to be returned in case the property has not been set.

Parameters:

key - the key to the property.

defaultValue - the default value to use in case no value has been specified.

Returns:

the resolved property. Never null, although the value / resolved value of the returned property may be null.

Throws:

IllegalArgumentException - if key is blank.

UnknownPropertyException - if key is not known.

PropertyValidationException - if the property is invalid according to its constraints.

getPropertyValueAsString

String getPropertyValueAsString(PropertyDescriptor descriptor)
                                throws NullPointerException,
                                       PropertyValidationException

Returns the property string value for the given descriptor. If the property type is not String, the Object.toString() method is called to create the string representation of the value. null is always returned as null (not as the String "null").

Parameters:

descriptor - the key to the property.

Returns:

the value to the property. A value of null is returned in cause of an optional property being not set.

Throws:

NullPointerException - if descriptor is null.

PropertyValidationException - if the property is invalid according to its constraints.

getPropertyValueAsString

String getPropertyValueAsString(String key)
                                throws IllegalArgumentException,
                                       UnknownPropertyException,
                                       PropertyValidationException

Returns the property string value for the given key. If the property type is not String, the Object.toString() method is called to create the string representation of the value. null is always returned as null (not as the String "null").

Parameters:

key - the key to the property.

Returns:

the value to the property. A value of null is returned in cause of an optional property being not set.

Throws:

IllegalArgumentException - if key is blank.

UnknownPropertyException - if key is not known.

PropertyValidationException - if the property is invalid according to its constraints.

getPropertyValueAsString

String getPropertyValueAsString(PropertyDescriptor descriptor,
                                Object defaultValue)
                                throws NullPointerException,
                                       PropertyValidationException

Returns the property string value for the given descriptor. If the property type is not String, the Object.toString() method is called to create the string representation of the value. null is always returned as null (not as the String "null").

Parameters:

descriptor - the key to the property.

defaultValue - the default value to use in case no value has been specified.

Returns:

the value to the property. A value of null is returned in cause of an optional property being not set.

Throws:

NullPointerException - if descriptor is null.

PropertyValidationException - if the property is invalid according to its constraints.

getPropertyValueAsString

String getPropertyValueAsString(String key,
                                Object defaultValue)
                                throws IllegalArgumentException,
                                       UnknownPropertyException,
                                       PropertyValidationException

Returns the property string value for the given key. If the property type is not String, the Object.toString() method is called to create the string representation of the value. null is always returned as null (not as the String "null").

Parameters:

key - the key to the property.

defaultValue - the default value to use in case no value has been specified.

Returns:

the value to the property. A value of null is returned in cause of an optional property being not set.

Throws:

IllegalArgumentException - if key is blank.

UnknownPropertyException - if key is not known.

PropertyValidationException - if the property is invalid according to its constraints.

validate

void validate()
              throws ConfigurationValidationException

Validates all properties in the given configuration in a non-lenient fashion.

Throws:

ConfigurationValidationException - if the configuration contains properties that do not meet the required constraints.

validate

void validate(boolean lenient)
              throws ConfigurationValidationException

Validates all properties in the given configuration.

Parameters:

lenient - the lenient flag that tells the validation process to handle unknown properties gracefully if set to true. If the value is false unknown properties are reported as validation failures.

Throws:

ConfigurationValidationException - if the configuration contains properties that do not meet the required constraints.

addPropertyChangeListener

void addPropertyChangeListener(PropertyKey name,
                               PropertyChangeListener listener)
                               throws NullPointerException

Adds the given listener as a listener to the given property.

Parameters:

name - the name of the property to track changes.

listener - the listener to add.

Throws:

NullPointerException - if name or listener is null.

removePropertyChangeListener

void removePropertyChangeListener(PropertyKey name,
                                  PropertyChangeListener listener)
                                  throws NullPointerException

Removes the given listener as a listener to the given property.

Parameters:

name - the name of the property to stop tracking changes.

listener - the listener to remove.

Throws:

NullPointerException - if name or listener is null.

addPropertyChangeListener

void addPropertyChangeListener(PropertyChangeListener listener)
                               throws NullPointerException

Adds the given listener to track any property changes.

Parameters:

listener - the listener to add.

Throws:

NullPointerException - if listener is null.

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)
                                  throws NullPointerException

Removes the given listener to stop tracking property changes.

Parameters:

listener - the listener to remove.

Throws:

NullPointerException - if listener is null.

toSerializable

SerializableConfigurationProperties toSerializable()

Creates a serializable variant of this implementation.

Returns:

a serializable variant of this implementation.

See Also:

ConfigurationPropertiesProxy, ConfigurationPropertiesManagementProxy