Environment configurations specify typed and untyped environment injector bindings. More...

#include <EnvironmentConfiguration.hpp>

Inheritance diagram for EnvironmentConfiguration:

Collaboration diagram for EnvironmentConfiguration:

Static Public Member Functions
template<typename BaseT >
static void	registerUniqueType (const std::string &typeString, const UniquePropertyCloner< BaseT > &cloner)
	Add a polymorphic type custom property binding builder factory to the global property binding builder factory map. More...

static void	registerUnsignedTypes ()
	Register C++ specific unsigned integer value type property binding builder factories in the global property binding builder factory map. More...

template<typename ValueT >
static void	registerValueType (const std::string &typeString)
	Add a non-polymorphic type custom property binding builder factory to the global property binding builder factory map. More...

Public Member Functions
	EnvironmentConfiguration (const std::vector< std::shared_ptr< Resource::Uri >> &inputs, const std::vector< std::shared_ptr< Resource::Uri >> &specs={})
	Create an environment configuration by specifying a vector of URIs pointing to the source properties texts and a vector of URIs pointing to type specification texts. More...

	EnvironmentConfiguration (const std::vector< Resource::File > &inputs, const std::vector< Resource::File > &specs={})
	Create an environment configuration by specifying a vector of files pointing to the source properties texts and a vector of files pointing to type specification texts. More...

template<typename ... UriT>
	EnvironmentConfiguration (const Resource::Uri &input, const Resource::Uri &firstTypeSpecifications, const UriT &... moreTypeSpecifications)
	Create an environment configuration by specifying the source properties file and the property types via a properties file. More...

template<typename ... UriT>
	EnvironmentConfiguration (const std::shared_ptr< Resource::Uri > &input, const std::shared_ptr< Resource::Uri > &firstTypeSpecifications, const UriT &... moreTypeSpecifications)
	Create an environment configuration by specifying a URI pointing to the source properties text and the property types via a properties file. More...

	EnvironmentConfiguration (const std::string &input, const std::string &typeSpecifications_)
	Create an environment configuration by specifying a string for the source properties text and the property types via a properties file. More...

	EnvironmentConfiguration (const Resource::Uri &input)
	Create an environment configuration by specifying the source properties file. More...

	EnvironmentConfiguration (const std::shared_ptr< Resource::Uri > &input)
	Create an environment configuration by specifying a URI pointing to the source properties text. More...

	EnvironmentConfiguration (const std::string &input)
	Create an environment configuration by specifying a string for the source properties text. More...

void	configure () const override
	Configure the injector configuration. More...

Protected Member Functions
template<typename ... FactoryPtrT>
Impl::PropertyBindingBuilderFactoryPtr	group (std::string name, FactoryPtrT ... tokens) const
	Declare a composite property specification in the environment configuration. More...

template<typename BaseT >
Impl::PropertyBindingBuilderFactoryPtr	unique (std::string name) const
	Declare a polymorphic "unique" value property specification in the environment configuration. More...

template<typename BaseT >
Impl::PropertyBindingBuilderFactoryPtr	unique (std::string name, std::unique_ptr< BaseT > &&defaultValue) const
	Declare a polymorphic "unique" value property specification in the environment configuration, specifying a default value. More...

template<typename BaseT >
Impl::PropertyBindingBuilderFactoryPtr	unique (std::string name, const UniquePropertyCloner< BaseT > &cloner) const
	Declare a polymorphic "unique" value property specification in the environment configuration. More...

template<typename BaseT >
Impl::PropertyBindingBuilderFactoryPtr	unique (std::string name, const UniquePropertyCloner< BaseT > &cloner, std::unique_ptr< BaseT > &&defaultValue) const
	Declare a polymorphic "unique" value property specification in the environment configuration, specifying a default value. More...

template<typename ValueT = std::string>
Impl::PropertyBindingBuilderFactoryPtr	value (std::string name) const
	Declare a non-polymorphic value property specification in the environment configuration. More...

template<typename ValueT = std::string>
Impl::PropertyBindingBuilderFactoryPtr	value (std::string name, ValueT defaultValue) const
	Declare a non-polymorphic value property specification in the environment configuration, specifying a default value. More...

Detailed Description

Environment configurations specify typed and untyped environment injector bindings.

Implementations of this class can be used to load simple or hierarchical properties files into an application's injector, in order to parameterise the configuration of an application according to the specific environment.

There are two ways to use the environment configuration class:

derive from the EnvironmentConfiguration class and hard wire property type specification declarations in the configure() method of the derived class;
instantiate an EnvironmentConfiguration instance by specifying one or more type specification properties files.

The two approaches can be mixed if required, by deriving from EnvironmentConfiguration and passing one or more type specification properties files to the base class constructor.

The instantiated EnvironmentConfiguration or derived class(es) should then be passed to the injector create function along with the application configuration instance(s).

Each instance of EnvironmentConfiguration or derived classes should be provided with a properties file input. During injector instantiation, a set of named value and shared bindings are created. These bindings represent the simple and composite properties in the properties file.

Typically, environment properties are sourced from one or more properties files on the local disk. Providing paths to the environment's property file(s) can be achieved by various methods, a couple of simple ones being:

passing the environment's home directory via a command line argument and hard wiring the environment properties file name(s) in code;
passing an environment identifier via a command line argument and resolving the home directory and environment configuration file path(s) accordingly.

Once the environment property file path(s) have been obtained, one or more corresponding EnvironmentConfiguration instance(s) can be created and passed to the injector.

The EnvironmentConfiguration class is designed to fail immediately if the property text is not well formed, preventing the application from starting up with an invalid configuration.

If a property type has been registered for a property name, the subsequent creation of a property binding for that property will result in a named value binding of that type being created if the property is simple. The value will be created via a call to the fromString function and placed within the named value binding. For all simple properties in the properties file that do not have types registered for them, a std::string named value binding is created.

All root composite properties in the properties file will result in injector named bindings being created of type EnvironmentProperties. Any property types registered for these property names will be ignored (a warning is also logged).

All simple and composite properties defined as descendants of root composite properties result in named value and shared bindings being created directly or indirectly within the root composite properties bindings in the injector. Refer to the EnvironmentProperties class for more information on the bindings created for descendant properties.

Constructor & Destructor Documentation

◆ EnvironmentConfiguration() [1/8]

EnvironmentConfiguration	(	const std::vector< std::shared_ptr< Resource::Uri >> &	inputs,
		const std::vector< std::shared_ptr< Resource::Uri >> &	specs = `{}`
	)

inline

Create an environment configuration by specifying a vector of URIs pointing to the source properties texts and a vector of URIs pointing to type specification texts.

Parameters

inputs	a vector of URIs pointing to the source properties texts
specs	a vector of URIs pointing to the type specification texts

◆ EnvironmentConfiguration() [2/8]

EnvironmentConfiguration	(	const std::vector< Resource::File > &	inputs,
		const std::vector< Resource::File > &	specs = `{}`
	)

inline

Create an environment configuration by specifying a vector of files pointing to the source properties texts and a vector of files pointing to type specification texts.

This convenience constructor allows file URIS to be supplied by value instead of via pointer containers.

Parameters

inputs	a vector of files pointing to the source properties texts
specs	a vector of files pointing to the type specification texts

◆ EnvironmentConfiguration() [3/8]

EnvironmentConfiguration	(	const Resource::Uri &	input,
		const Resource::Uri &	firstTypeSpecifications,
		const UriT &...	moreTypeSpecifications
	)

inline

Create an environment configuration by specifying the source properties file and the property types via a properties file.

Template Parameters

FileT the Resource::File type for moreTypeSpecifications

Parameters

input	the path to the properties file to parse
firstTypeSpecifications	the first properties type specifications file
moreTypeSpecifications	more properties type specifications files

◆ EnvironmentConfiguration() [4/8]

EnvironmentConfiguration	(	const std::shared_ptr< Resource::Uri > &	input,
		const std::shared_ptr< Resource::Uri > &	firstTypeSpecifications,
		const UriT &...	moreTypeSpecifications
	)

inline

Create an environment configuration by specifying a URI pointing to the source properties text and the property types via a properties file.

Template Parameters

UriT	the std::shared_ptr<Resource::Uri> type for moreTypeSpecifications

Parameters

input	the URI pointing to the source properties text
firstTypeSpecifications	the first properties type specifications source
moreTypeSpecifications	more properties type specifications sources

◆ EnvironmentConfiguration() [5/8]

EnvironmentConfiguration	(	const std::string &	input,
		const std::string &	typeSpecifications_
	)

inline

Create an environment configuration by specifying a string for the source properties text and the property types via a properties file.

Parameters

input	the properties text
typeSpecification	the properties type specifications

◆ EnvironmentConfiguration() [6/8]

EnvironmentConfiguration ( const Resource::Uri & input )

inline

Create an environment configuration by specifying the source properties file.

Parameters

input the path to the properties file to parse

◆ EnvironmentConfiguration() [7/8]

EnvironmentConfiguration ( const std::shared_ptr< Resource::Uri > & input )

inline

Create an environment configuration by specifying a URI pointing to the source properties text.

Parameters

input the URI pointing to the source properties text

◆ EnvironmentConfiguration() [8/8]

EnvironmentConfiguration ( const std::string & input )

inline

Create an environment configuration by specifying a string for the source properties text.

Parameters

input the properties text

Member Function Documentation

◆ configure()

void configure ( ) const

inlineoverridevirtual

Configure the injector configuration.

Implements InjectorConfiguration.

◆ group()

Impl::PropertyBindingBuilderFactoryPtr group	(	std::string	name,
		FactoryPtrT ...	tokens
	)		const

inlineprotected

Declare a composite property specification in the environment configuration.

This call is used when the declaration needs to state that the composite property is required.

Template Parameters

FactoryPtrT the intermediate binding builder factory pointer type

Parameters

name	the name of the composite property
tokens	the child property specifications

Returns: a transiently defined object used within the fluent declaration call

◆ registerUniqueType()

static void registerUniqueType	(	const std::string &	typeString,
		const UniquePropertyCloner< BaseT > &	cloner
	)

inlinestatic

Add a polymorphic type custom property binding builder factory to the global property binding builder factory map.

Instances of the polymorphic (unique) type will be created by calling the supplied cloner function.

The type must have a corresponding fromString function, otherwise there will be a compilation error.

This function must be called before the injector is instantiated, in order to define the custom types.

Template Parameters

BaseT the type of the property's value

Parameters

typeString	the string identification of the type
factory	a pointer to the factory to return when typeString is requested
cloner	a function that is used to clone the value

◆ registerUnsignedTypes()

static void registerUnsignedTypes ( )

inlinestatic

Register C++ specific unsigned integer value type property binding builder factories in the global property binding builder factory map.

These types are not pre-registered as they are not listed in the environment configuration pre-registered type list.

The additional types registered are:

unsigned byte (type = unsigned char);
unsigned short (type = unsigned short);
unsigned int (type = unsigned int);
unsigned long (type = unsigned long long).

This function must be called before the injector is instantiated, in order to define the custom types.

◆ registerValueType()

static void registerValueType ( const std::string & typeString )

inlinestatic

Add a non-polymorphic type custom property binding builder factory to the global property binding builder factory map.

Instances of the non-polymorphic (value) type will be created via prototype copying.

The type must have a corresponding fromString function, otherwise there will be a compilation error.

This function must be called before the injector is instantiated, in order to define the custom types.

Template Parameters

ValueT the type of the property's value

Parameters

typeString	the string identification of the type
factory	a pointer to the factory to return when typeString is requested

◆ unique() [1/4]

Impl::PropertyBindingBuilderFactoryPtr unique ( std::string name ) const

inlineprotected

Declare a polymorphic "unique" value property specification in the environment configuration.

A binding builder factory (that supplies the unique pointer cloner for this type) will be required to have been registered for custom types.

If no entry is found in the binding builder factory map for the specified type, an exception will be thrown.

Template Parameters

BaseT the base type of the class that the property value will be converted to

Parameters

name	the name of the value property

Returns: a transiently defined object used within the fluent declaration call

Exceptions

EnvironmentConfigurationException if no binding builder factory map for the specified type has been registered

◆ unique() [2/4]

Impl::PropertyBindingBuilderFactoryPtr unique	(	std::string	name,
		std::unique_ptr< BaseT > &&	defaultValue
	)		const

inlineprotected

Declare a polymorphic "unique" value property specification in the environment configuration, specifying a default value.

The unique pointer cloner function will be looked up in the registered factory map. If no entry is found in the factory map, an exception will be thrown.

This overload should be used when a default value for the property should be used when no such property is provided in the environment properties file.

Template Parameters

BaseT the base type of the class that the property value will be converted to

Parameters

name	the name of the value property
defaultValue	the value used in the resulting binding if the property is not set

Returns: a transiently defined object used within the fluent declaration call

◆ unique() [3/4]

Impl::PropertyBindingBuilderFactoryPtr unique	(	std::string	name,
		const UniquePropertyCloner< BaseT > &	cloner
	)		const

inlineprotected

Declare a polymorphic "unique" value property specification in the environment configuration.

The supplied unique pointer cloner function will be used for cloning the unique pointer prototype value.

Template Parameters

BaseT the base type of the class that the property value will be converted to

Parameters

name	the name of the value property

Returns: a transiently defined object used within the fluent declaration call

◆ unique() [4/4]

Impl::PropertyBindingBuilderFactoryPtr unique	(	std::string	name,
		const UniquePropertyCloner< BaseT > &	cloner,
		std::unique_ptr< BaseT > &&	defaultValue
	)		const

inlineprotected

Declare a polymorphic "unique" value property specification in the environment configuration, specifying a default value.

The supplied unique pointer cloner function will be used for cloning the unique pointer prototype value.

This overload should be used when a default value for the property should be used when no such property is provided in the environment properties file.

Template Parameters

BaseT the base type of the class that the property value will be converted to

Parameters

name	the name of the value property
defaultValue	the value used in the resulting binding if the property is not set

Returns: a transiently defined object used within the fluent declaration call

◆ value() [1/2]

Impl::PropertyBindingBuilderFactoryPtr value ( std::string name ) const

inlineprotected

Declare a non-polymorphic value property specification in the environment configuration.

Template Parameters

ValueT the value type that the property value will be converted to

Parameters

name	the name of the value property

Returns: a transiently defined object used within the fluent declaration call

◆ value() [2/2]

Impl::PropertyBindingBuilderFactoryPtr value	(	std::string	name,
		ValueT	defaultValue
	)		const

inlineprotected

Declare a non-polymorphic value property specification in the environment configuration, specifying a default value.

This overload should be used when a default value for the property should be used when no such property is provided in the environment properties file.

Template Parameters

ValueT the value type that the property value will be converted to

Parameters

name	the name of the value property
defaultValue	the value used in the resulting binding if the property is not set

Returns: a transiently defined object used within the fluent declaration call

The documentation for this class was generated from the following file:

EnvironmentConfiguration.hpp (6)

Static Public Member Functions

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ EnvironmentConfiguration() [1/8]

◆ EnvironmentConfiguration() [2/8]

◆ EnvironmentConfiguration() [3/8]

◆ EnvironmentConfiguration() [4/8]

◆ EnvironmentConfiguration() [5/8]

◆ EnvironmentConfiguration() [6/8]

◆ EnvironmentConfiguration() [7/8]

◆ EnvironmentConfiguration() [8/8]

Member Function Documentation

◆ configure()

◆ group()

◆ registerUniqueType()

◆ registerUnsignedTypes()

◆ registerValueType()

◆ unique() [1/4]

◆ unique() [2/4]

◆ unique() [3/4]

◆ unique() [4/4]

◆ value() [1/2]

◆ value() [2/2]