# Poco::Util

# class AbstractConfiguration

Library: Util
Package: Configuration
Header: Poco/Util/AbstractConfiguration.h

## Description

AbstractConfiguration is an abstract base class for different kinds of configuration data, such as INI files, property files, XML configuration files or the Windows Registry.

Configuration property keys have a hierarchical format, consisting of names separated by periods. The exact interpretation of key names is up to the actual subclass implementation of AbstractConfiguration. Keys are case sensitive.

All public methods are synchronized, so the class is safe for multithreaded use. AbstractConfiguration implements reference counting based garbage collection.

Subclasses must override the getRaw(), setRaw() and enumerate() methods.

## Inheritance

Direct Base Classes: Poco::RefCountedObject

All Base Classes: Poco::RefCountedObject

Known Derived Classes: ConfigurationMapper, AbstractConfigurationView, ConfigurationView, FilesystemConfiguration, IniFileConfiguration, JSONConfiguration, LayeredConfiguration, LocalConfigurationView, MapConfiguration, PropertyFileConfiguration, SystemConfiguration, WinRegistryConfiguration, XMLConfiguration

## Member Summary

Member Functions: createLocalView, createView, enableEvents, enumerate, eventsEnabled, expand, getBool, getDouble, getInt, getInt16, getInt32, getInt64, getRaw, getRawString, getString, getUInt, getUInt16, getUInt32, getUInt64, has, hasOption, hasProperty, keys, operator =, parseBool, parseInt, parseInt16, parseInt64, parseUInt, parseUInt16, parseUInt64, remove, removeRaw, setBool, setDouble, setInt, setInt16, setInt32, setInt64, setRaw, setRawWithEvent, setString, setUInt, setUInt16, setUInt32, setUInt64

Inherited Functions: duplicate, referenceCount, release

## Nested Classes

### class KeyValue

A key-value pair, used as event argument.

### class ScopedLock

A helper class allowing to temporarily lock an entire AbstractConfiguration, for use by subclasses.

## Types Aliases

### Keys

using Keys = std::vector < std::string >;

### Ptr

using Ptr = AutoPtr < AbstractConfiguration >;

## Constructors

### AbstractConfiguration

AbstractConfiguration();

Creates the AbstractConfiguration.

### AbstractConfiguration

AbstractConfiguration(
const AbstractConfiguration & param561
) = delete;

## Destructor

### ~AbstractConfiguration

~AbstractConfiguration() override = default;

## Member Functions

### createLocalView

[[nodiscard]]
const Ptr createLocalView(
const std::string & prefix
) const;

Creates a non-mutable view (see LocalConfigurationView) into the configuration. The returned Ptr must be assigned to an AbstractConfiguration::Ptr, not a raw pointer, to prevent use-after-free.

### createLocalView

[[nodiscard]]
Ptr createLocalView(
const std::string & prefix
);

Creates a view (see LocalConfigurationView) into the configuration. The returned Ptr must be assigned to an AbstractConfiguration::Ptr, not a raw pointer, to prevent use-after-free.

### createView

[[nodiscard]]
const Ptr createView(
const std::string & prefix
) const;

Creates a non-mutable view (see ConfigurationView) into the configuration. The returned Ptr must be assigned to an AbstractConfiguration::Ptr, not a raw pointer, to prevent use-after-free.

### createView

[[nodiscard]]
Ptr createView(
const std::string & prefix
);

Creates a view (see ConfigurationView) into the configuration. The returned Ptr must be assigned to an AbstractConfiguration::Ptr, not a raw pointer, to prevent use-after-free.

### enableEvents

void enableEvents(
bool enable = true
);

Enables (or disables) events.

### eventsEnabled

bool eventsEnabled() const;

Returns true if and only if events are enabled.

### expand

std::string expand(
const std::string & value
) const;

Replaces all occurrences of ${<property>} in value with the value of the <property>. If <property> does not exist, nothing is changed.

It is also possible to specify a default value for a referenced property that does not exist, using ${<property>:-<default>}. Note that currently a default value cannot contain a closing curly bracket ("}"). The default value also cannot reference another variable.

If a circular property reference is detected, a CircularReferenceException will be thrown.

### getBool

bool getBool(
const std::string & key
) const;

Returns the boolean value of the property with the given name. Throws a NotFoundException if the key does not exist. Throws a SyntaxException if the property can not be converted to a boolean. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getBool

bool getBool(
const std::string & key,
bool defaultValue
) const;

If a property with the given key exists, returns the property's boolean value, otherwise returns the given default value. Throws a SyntaxException if the property can not be converted to a boolean. The following string values can be converted into a boolean:

- numerical values: non zero becomes true, zero becomes false
- strings: true, yes, on become true, false, no, off become false

Case does not matter. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getDouble

double getDouble(
const std::string & key
) const;

Returns the double value of the property with the given name. Throws a NotFoundException if the key does not exist. Throws a SyntaxException if the property can not be converted to a double. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getDouble

double getDouble(
const std::string & key,
double defaultValue
) const;

If a property with the given key exists, returns the property's double value, otherwise returns the given default value. Throws a SyntaxException if the property can not be converted to an double. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getInt

int getInt(
const std::string & key
) const;

Returns the int value of the property with the given name. Throws a NotFoundException if the key does not exist. Throws a SyntaxException if the property can not be converted to an int. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getInt

int getInt(
const std::string & key,
int defaultValue
) const;

If a property with the given key exists, returns the property's int value, otherwise returns the given default value. Throws a SyntaxException if the property can not be converted to an int. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getInt16

Poco::Int16 getInt16(
const std::string & key
) const;

Returns the 16-bit int value of the property with the given name. Throws a NotFoundException if the key does not exist. Throws a SyntaxException or a RangeException if the property can not be converted to an Int16. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getInt16

Poco::Int16 getInt16(
const std::string & key,
Poco::Int16 defaultValue
) const;

If a property with the given key exists, returns the property's 16-bit int value, otherwise returns the given default value. Throws a SyntaxException or a RangeException if the property can not be converted to an Int16. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getInt32

Poco::Int32 getInt32(
const std::string & key
) const;

Returns the 32-bit int value of the property with the given name. Throws a NotFoundException if the key does not exist. Throws a SyntaxException if the property can not be converted to an Int32. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getInt32

Poco::Int32 getInt32(
const std::string & key,
Poco::Int32 defaultValue
) const;

If a property with the given key exists, returns the property's 32-bit int value, otherwise returns the given default value. Throws a SyntaxException if the property can not be converted to an Int32. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getInt64

Int64 getInt64(
const std::string & key
) const;

Returns the Int64 value of the property with the given name. Throws a NotFoundException if the key does not exist. Throws a SyntaxException if the property can not be converted to an Int64. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getInt64

Int64 getInt64(
const std::string & key,
Int64 defaultValue
) const;

If a property with the given key exists, returns the property's Int64 value, otherwise returns the given default value. Throws a SyntaxException if the property can not be converted to an Int64. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getRawString

std::string getRawString(
const std::string & key
) const;

Returns the raw string value of the property with the given name. Throws a NotFoundException if the key does not exist. References to other properties are not expanded.

### getRawString

std::string getRawString(
const std::string & key,
const std::string & defaultValue
) const;

If a property with the given key exists, returns the property's raw string value, otherwise returns the given default value. References to other properties are not expanded.

### getString

std::string getString(
const std::string & key
) const;

Returns the string value of the property with the given name. Throws a NotFoundException if the key does not exist. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getString

std::string getString(
const std::string & key,
const std::string & defaultValue
) const;

If a property with the given key exists, returns the property's string value, otherwise returns the given default value. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getUInt

unsigned int getUInt(
const std::string & key
) const;

Returns the unsigned int value of the property with the given name. Throws a NotFoundException if the key does not exist. Throws a SyntaxException if the property can not be converted to an unsigned int. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getUInt

unsigned int getUInt(
const std::string & key,
unsigned int defaultValue
) const;

If a property with the given key exists, returns the property's unsigned int value, otherwise returns the given default value. Throws a SyntaxException if the property can not be converted to an unsigned int. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getUInt16

Poco::UInt16 getUInt16(
const std::string & key
) const;

Returns the unsigned 16-bit int value of the property with the given name. Throws a NotFoundException if the key does not exist. Throws a SyntaxException or a RangeException if the property can not be converted to an UInt16. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getUInt16

Poco::UInt16 getUInt16(
const std::string & key,
Poco::UInt16 defaultValue
) const;

If a property with the given key exists, returns the property's unsigned 16-bit int value, otherwise returns the given default value. Throws a SyntaxException or a RangeException if the property can not be converted to an UInt16. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getUInt32

Poco::UInt32 getUInt32(
const std::string & key
) const;

Returns the 32-bit unsigned int value of the property with the given name. Throws a NotFoundException if the key does not exist. Throws a SyntaxException if the property can not be converted to an UInt32. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getUInt32

Poco::UInt32 getUInt32(
const std::string & key,
Poco::UInt32 defaultValue
) const;

If a property with the given key exists, returns the property's 32-bit unsigned int value, otherwise returns the given default value. Throws a SyntaxException if the property can not be converted to an UInt32. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getUInt64

UInt64 getUInt64(
const std::string & key
) const;

Returns the UInt64 value of the property with the given name. Throws a NotFoundException if the key does not exist. Throws a SyntaxException if the property can not be converted to an UInt64. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### getUInt64

UInt64 getUInt64(
const std::string & key,
UInt64 defaultValue
) const;

If a property with the given key exists, returns the property's UInt64 value, otherwise returns the given default value. Throws a SyntaxException if the property can not be converted to an UInt64. Numbers starting with 0x are treated as hexadecimal. If the value contains references to other properties (${<property>}, or ${<property>:-<default>}), these are expanded (see expand()).

### has

bool has(
const std::string & key
) const;

Returns true if and only if the property with the given key exists.

Same as hasProperty().

### hasOption

bool hasOption(
const std::string & key
) const;

Returns true if and only if the property with the given key exists.

Same as hasProperty().

### hasProperty

bool hasProperty(
const std::string & key
) const;

Returns true if and only if the property with the given key exists.

### keys

Keys keys(
const std::string & key = std::string ()
) const;

Returns the names of all subkeys under the given key. If an empty key is passed, all root level keys are returned.

### keys

void keys(
Keys & range
) const;

Returns in range the names of all keys at root level.

### keys

void keys(
const std::string & key,
Keys & range
) const;

Returns in range the names of all subkeys under the given key. If an empty key is passed, all root level keys are returned.

### operator =

AbstractConfiguration & operator = (
const AbstractConfiguration & param562
) = delete;

### remove

void remove(
const std::string & key
);

Removes the property with the given key.

Does nothing if the key does not exist.

### setBool

virtual void setBool(
const std::string & key,
bool value
);

Sets the property with the given key to the given value. An already existing value for the key is overwritten.

### setDouble

virtual void setDouble(
const std::string & key,
double value
);

Sets the property with the given key to the given value. An already existing value for the key is overwritten.

### setInt

virtual void setInt(
const std::string & key,
int value
);

Sets the property with the given key to the given value. An already existing value for the key is overwritten.

### setInt16

virtual void setInt16(
const std::string & key,
Poco::Int16 value
);

Sets the property with the given key to the given value. An already existing value for the key is overwritten.

### setInt32

virtual void setInt32(
const std::string & key,
Poco::Int32 value
);

Sets the property with the given key to the given value. An already existing value for the key is overwritten.

### setInt64

virtual void setInt64(
const std::string & key,
Int64 value
);

Sets the property with the given key to the given value. An already existing value for the key is overwritten.

### setString

virtual void setString(
const std::string & key,
const std::string & value
);

Sets the property with the given key to the given value. An already existing value for the key is overwritten.

### setUInt

virtual void setUInt(
const std::string & key,
unsigned int value
);

Sets the property with the given key to the given value. An already existing value for the key is overwritten.

### setUInt16

virtual void setUInt16(
const std::string & key,
Poco::UInt16 value
);

Sets the property with the given key to the given value. An already existing value for the key is overwritten.

### setUInt32

virtual void setUInt32(
const std::string & key,
Poco::UInt32 value
);

Sets the property with the given key to the given value. An already existing value for the key is overwritten.

### setUInt64

virtual void setUInt64(
const std::string & key,
UInt64 value
);

Sets the property with the given key to the given value. An already existing value for the key is overwritten.

### enumerate

virtual void enumerate(
const std::string & key,
Keys & range
) const = 0;

Returns in range the names of all subkeys under the given key. If an empty key is passed, all root level keys are returned.

### getRaw

virtual bool getRaw(
const std::string & key,
std::string & value
) const = 0;

If the property with the given key exists, stores the property's value in value and returns true. Otherwise, returns false.

Must be overridden by subclasses.

### parseBool

static bool parseBool(
const std::string & value
);

### parseInt

static int parseInt(
const std::string & value
);

Returns string as signed integer. Decimal and hexadecimal notation is supported.

### parseInt16

static Poco::Int16 parseInt16(
const std::string & value
);

Returns string as signed 16-bit integer. Decimal and hexadecimal notation is supported.

### parseInt64

static Int64 parseInt64(
const std::string & value
);

Returns string as 64-bit signed integer. Decimal and hexadecimal notation is supported.

### parseUInt

static unsigned parseUInt(
const std::string & value
);

Returns string as unsigned integer. Decimal and hexadecimal notation is supported.

### parseUInt16

static Poco::UInt16 parseUInt16(
const std::string & value
);

Returns string as unsigned 16-bit integer. Decimal and hexadecimal notation is supported.

### parseUInt64

static UInt64 parseUInt64(
const std::string & value
);

Returns string as 64-bit unsigned integer. Decimal and hexadecimal notation is supported.

### removeRaw

virtual void removeRaw(
const std::string & key
);

Removes the property with the given key.

Does nothing if the key does not exist.

Should be overridden by subclasses; the default implementation throws a Poco::NotImplementedException.

### setRaw

virtual void setRaw(
const std::string & key,
const std::string & value
) = 0;

Sets the property with the given key to the given value. An already existing value for the key is overwritten.

Must be overridden by subclasses.

### setRawWithEvent

void setRawWithEvent(
const std::string & key,
std::string value
);

## Variables

### propertyChanged

Poco::BasicEvent < const KeyValue > propertyChanged;

Fired after a property value has been changed or a property has been created.

### propertyChanging

Poco::BasicEvent < KeyValue > propertyChanging;

Fired before a property value is changed or a new property is created.

Can be used to check or fix a property value, or to cancel the change by throwing an exception.

The event delegate can use one of the get...() functions to obtain the current property value.

### propertyRemoved

Poco::BasicEvent < const std::string > propertyRemoved;

Fired after a property has been removed by a call to remove().

### propertyRemoving

Poco::BasicEvent < const std::string > propertyRemoving;

Fired before a property is removed by a call to remove().

Note: This will even be fired if the key does not exist and the remove operation will fail with an exception.