Class Poco::Util::XMLConfiguration
Author: Applied Informatics Software Engineering GmbH and Contributors

# Poco::Util

# class XMLConfiguration

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

## Description

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.

## Inheritance

Direct Base Classes: AbstractConfiguration

All Base Classes: Poco::RefCountedObject, AbstractConfiguration

## Member Summary

Member Functions: enumerate, getRaw, load, loadEmpty, removeRaw, save, setRaw

Inherited Functions: createView, duplicate, enableEvents, enumerate, eventsEnabled, expand, getBool, getDouble, getInt, getInt64, getRaw, getRawString, getString, getUInt, getUInt64, has, hasOption, hasProperty, keys, parseBool, parseInt, parseInt64, parseUInt, parseUInt64, referenceCount, release, remove, removeRaw, setBool, setDouble, setInt, setInt64, setRaw, setRawWithEvent, setString, setUInt, setUInt64

## Constructors

### XMLConfiguration

XMLConfiguration();

Creates an empty XMLConfiguration with a "config" root element.

### XMLConfiguration

XMLConfiguration(
char delim
);

Creates an empty XMLConfiguration with a "config" root element, using the given delimiter char instead of the default '.'.

### XMLConfiguration

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

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

### XMLConfiguration

XMLConfiguration(
std::istream & istr
);

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

### XMLConfiguration

XMLConfiguration(
const std::string & path
);

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

### XMLConfiguration

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

Creates the XMLConfiguration using the given XML document.

### XMLConfiguration

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

Creates the XMLConfiguration using the given XML node.

### XMLConfiguration

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

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

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

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

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 '.'.

## Destructor

### ~XMLConfiguration

~XMLConfiguration();

## Member Functions

### load

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

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

### load

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.

### load

void load(
std::istream & istr
);

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

### load

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

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

### load

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

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

### load

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

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

### loadEmpty

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

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

### save

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

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

### save

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

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

### save

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.

### save

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.

### enumerate

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

See also: Poco::Util::AbstractConfiguration::enumerate()

### getRaw

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

See also: Poco::Util::AbstractConfiguration::getRaw()

### removeRaw

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

See also: Poco::Util::AbstractConfiguration::removeRaw()

### setRaw

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

See also: Poco::Util::AbstractConfiguration::setRaw()