class Poco::Util::AbstractConfiguration

Overview

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. More…

#include <AbstractConfiguration.h>

class AbstractConfiguration: public Poco::RefCountedObject
{
public:
    // typedefs

    typedef std::vector<std::string> Keys;

    // classes

    class KeyValue;

    // fields

    Poco::BasicEvent<KeyValue> propertyChanging;
    Poco::BasicEvent<const KeyValue> propertyChanged;
    Poco::BasicEvent<const std::string> propertyRemoving;
    Poco::BasicEvent<const std::string> propertyRemoved;

    // methods

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    void
    keys(Keys& range) const;

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

    const AbstractConfiguration*
    createView(const std::string& prefix) const;

    AbstractConfiguration*
    createView(const std::string& prefix);

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

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

    void
    enableEvents(bool enable = true);

    bool
    eventsEnabled() const;

protected:
    // methods

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

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

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

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

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

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

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

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

// direct descendants

class ConfigurationMapper;
class ConfigurationView;
class FilesystemConfiguration;
class IniFileConfiguration;
class JSONConfiguration;
class LayeredConfiguration;
class MapConfiguration;
class SystemConfiguration;
class WinRegistryConfiguration;
class XMLConfiguration;

Inherited Members

public:
    // methods

    void
    duplicate() const;

    void
    release() const;

    int
    referenceCount() const;

Detailed Documentation

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.

Fields

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.

Poco::BasicEvent<const KeyValue> propertyChanged

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

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.

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

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

Methods

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

Returns true iff the property with the given key exists.

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

Returns true iff the property with the given key exists.

Same as hasProperty().

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

Returns true iff the property with the given key exists.

Same as hasProperty().

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>}), these are expanded.

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>}), these are expanded.

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.

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.

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>}), these are expanded.

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>}), these are expanded.

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>}), these are expanded.

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>}), these are expanded.

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>}), these are expanded.

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>}), these are expanded.

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>}), these are expanded.

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>}), these are expanded.

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.

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.

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.

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.

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.

void
keys(Keys& range) const

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

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.

const AbstractConfiguration*
createView(const std::string& prefix) const

Creates a non-mutable view (see ConfigurationView) into the configuration.

AbstractConfiguration*
createView(const std::string& prefix)

Creates a view (see ConfigurationView) into the configuration.

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

Replaces all occurences of ${<property>} in value with the value of the <property>.

If <property> does not exist, nothing is changed.

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

void
remove(const std::string& key)

Removes the property with the given key.

Does nothing if the key does not exist.

void
enableEvents(bool enable = true)

Enables (or disables) events.

bool
eventsEnabled() const

Returns true iff events are enabled.

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.

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.

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.

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.