class Poco::Util::XMLConfiguration

Overview

This configuration class extracts configuration properties from an XML document. More…

#include <XMLConfiguration.h>

class XMLConfiguration: public Poco::Util::AbstractConfiguration
{
public:
    // construction

    XMLConfiguration();
    XMLConfiguration(char delim);
    XMLConfiguration(Poco::XML::InputSource* pInputSource);

    XMLConfiguration(
        Poco::XML::InputSource* pInputSource,
        char delim
        );

    XMLConfiguration(std::istream& istr);

    XMLConfiguration(
        std::istream& istr,
        char delim
        );

    XMLConfiguration(const std::string& path);

    XMLConfiguration(
        const std::string& path,
        char delim
        );

    XMLConfiguration(const Poco::XML::Document* pDocument);

    XMLConfiguration(
        const Poco::XML::Document* pDocument,
        char delim
        );

    XMLConfiguration(const Poco::XML::Node* pNode);

    XMLConfiguration(
        const Poco::XML::Node* pNode,
        char delim
        );

    // methods

    void
    load(Poco::XML::InputSource* pInputSource);

    void
    load(
        Poco::XML::InputSource* pInputSource,
        unsigned long namePoolSize
        );

    void
    load(std::istream& istr);

    void
    load(const std::string& path);

    void
    load(const Poco::XML::Document* pDocument);

    void
    load(const Poco::XML::Node* pNode);

    void
    loadEmpty(const std::string& rootElementName);

    void
    save(const std::string& path) const;

    void
    save(std::ostream& str) const;

    void
    save(
        Poco::XML::DOMWriter& writer,
        const std::string& path
        ) const;

    void
    save(
        Poco::XML::DOMWriter& writer,
        std::ostream& str
        ) const;

protected:
    // methods

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

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

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

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

Inherited Members

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

    void
    duplicate() const;

    void
    release() const;

    int
    referenceCount() const;

    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);

Detailed Documentation

This configuration class extracts configuration properties from an XML document.

An XPath-like syntax for property names is supported to allow full access to the XML document. XML namespaces are not supported. The name of the root element of the XML document is not significant and ignored. Periods in tag names are not supported.

Given the following XML document as an example:

<config>
    <prop1>value1</prop1>
    <prop2>value2</prop2>
    <prop3>
       <prop4 attr="value3"/>
       <prop4 attr="value4"/>
    </prop3>
    <prop5 id="first">value5</prop5>
    <prop5 id="second">value6</prop5>
</config>

The following property names would be valid and would yield the shown values:

prop1                 -> value1
prop2                 -> value2
prop3.prop4           -> (empty string)
prop3.prop4[@attr]    -> value3
prop3.prop4[1][@attr] -> value4
prop5[0]              -> value5
prop5[1]              -> value6
prop5[@id=first]      -> value5
prop5[@id='second']   -> value6

Enumerating attributes is not supported. Calling keys(“prop3.prop4”) will return an empty range.

As a special feature, the delimiter character used to delimit property names can be changed to something other than period (‘.’) by passing the desired character to the constructor. This allows working with XML documents having element names with periods in them.

Construction

XMLConfiguration()

Creates an empty XMLConfiguration with a “config” root element.

XMLConfiguration(char delim)

Creates an empty XMLConfiguration with a “config” root element, using the given delimiter char instead of the default ‘.

‘.

XMLConfiguration(Poco::XML::InputSource* pInputSource)

Creates an XMLConfiguration and loads the XML document from the given InputSource.

XMLConfiguration(
    Poco::XML::InputSource* pInputSource,
    char delim
    )

Creates an XMLConfiguration and loads the XML document from the given InputSource.

Uses the given delimiter char instead of the default ‘.’.

XMLConfiguration(std::istream& istr)

Creates an XMLConfiguration and loads the XML document from the given stream.

XMLConfiguration(
    std::istream& istr,
    char delim
    )

Creates an XMLConfiguration and loads the XML document from the given stream.

Uses the given delimiter char instead of the default ‘.’.

XMLConfiguration(const std::string& path)

Creates an XMLConfiguration and loads the XML document from the given path.

XMLConfiguration(
    const std::string& path,
    char delim
    )

Creates an XMLConfiguration and loads the XML document from the given path.

Uses the given delimiter char instead of the default ‘.’.

XMLConfiguration(const Poco::XML::Document* pDocument)

Creates the XMLConfiguration using the given XML document.

XMLConfiguration(
    const Poco::XML::Document* pDocument,
    char delim
    )

Creates the XMLConfiguration using the given XML document.

Uses the given delimiter char instead of the default ‘.’.

XMLConfiguration(const Poco::XML::Node* pNode)

Creates the XMLConfiguration using the given XML node.

XMLConfiguration(
    const Poco::XML::Node* pNode,
    char delim
    )

Creates the XMLConfiguration using the given XML node.

Uses the given delimiter char instead of the default ‘.’.

Methods

void
load(Poco::XML::InputSource* pInputSource)

Loads the XML document containing the configuration data from the given InputSource.

void
load(
    Poco::XML::InputSource* pInputSource,
    unsigned long namePoolSize
    )

Loads the XML document containing the configuration data from the given InputSource.

Uses the give namePoolSize (which should be a suitable prime like 251, 509, 1021, 4093) for the internal DOM Document’s name pool.

void
load(std::istream& istr)

Loads the XML document containing the configuration data from the given stream.

void
load(const std::string& path)

Loads the XML document containing the configuration data from the given file.

void
load(const Poco::XML::Document* pDocument)

Loads the XML document containing the configuration data from the given XML document.

void
load(const Poco::XML::Node* pNode)

Loads the XML document containing the configuration data from the given XML node.

void
loadEmpty(const std::string& rootElementName)

Loads an empty XML document containing only the root element with the given name.

void
save(const std::string& path) const

Writes the XML document containing the configuration data to the file given by path.

void
save(std::ostream& str) const

Writes the XML document containing the configuration data to the given stream.

void
save(
    Poco::XML::DOMWriter& writer,
    const std::string& path
    ) const

Writes the XML document containing the configuration data to the file given by path, using the given DOMWriter.

This can be used to use a DOMWriter with custom options.

void
save(
    Poco::XML::DOMWriter& writer,
    std::ostream& str
    ) const

Writes the XML document containing the configuration data to the given stream.

This can be used to use a DOMWriter with custom options.

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

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
    )

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

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.