isc::process::DCfgMgrBase Class Reference

Configuration Manager. More...

#include <d_cfg_mgr.h>

Inheritance diagram for isc::process::DCfgMgrBase:

Public Member Functions
	DCfgMgrBase (ConfigPtr context)
	Constructor. More...
virtual	~DCfgMgrBase ()
	Destructor. More...
virtual std::string	getConfigSummary (const uint32_t selection)=0
	Returns configuration summary in the textual format. More...
ConfigPtr &	getContext ()
	Fetches the configuration context. More...
isc::data::ConstElementPtr	simpleParseConfig (isc::data::ConstElementPtr config, bool check_only=false, const std::function< void()> &post_config_cb=nullptr)
	Acts as the receiver of new configurations. More...

Protected Member Functions
virtual ConfigPtr	createNewContext ()=0
	Abstract factory which creates a context instance. More...
virtual isc::data::ConstElementPtr	parse (isc::data::ConstElementPtr config, bool check_only)
	Parses actual configuration. More...
void	resetContext ()
	Replaces existing context with a new, empty context. More...
virtual void	setCfgDefaults (isc::data::ElementPtr mutable_config)
	Adds default values to the given config. More...
void	setContext (ConfigPtr &context)
	Update the current context. More...

Detailed Description

Configuration Manager.

DCfgMgrBase is an abstract class that provides the mechanisms for managing an application's configuration. This includes services for parsing sets of configuration values, storing the parsed information in its converted form, and retrieving the information on demand. It is intended to be the worker class which is handed a set of configuration values to process by upper application management layers.

This class allows two configuration methods:

1. classic method

The class presents a public method for receiving new configurations, parseConfig. This method coordinates the parsing effort as follows:

make backup copy of configuration context
Split top-level configuration elements into to sets:
  1. Set of scalar elements (strings, booleans, ints, etc..)
  2. Set of object elements (maps, lists, etc...)
For each entry in the scalar set:
    get derivation-specific parser for element
    run parser
    update context with parsed results
    break on error
 
For each entry in the object set;
    get derivation-specific parser for element
    run parser
    update context with parsed results
    break on error
 
if an error occurred or this is only a check
    restore configuration context from backup

The above structuring ensures that global parameters are parsed first making them available during subsequent object element parsing. The order in which the object elements are processed is either:

1. Natural order presented by the configuration set
2. Specific order determined by a list of element ids

This allows a derivation to specify the order in which its elements are parsed if there are dependencies between elements.

To parse a given element, its id along with the element itself, is passed into the virtual method, parseElement. Derivations are expected to converts the element into application specific object(s), thereby isolating the CPL from application details.

In the event that an error occurs, parsing is halted and the configuration context is restored from backup.

See isc::d2::D2CfgMgr and isc::d2::D2Process for example use of this approach.

1. simple configuration method

This approach assumes usage of isc::data::SimpleParser paradigm. It does not use any intermediate storage, does not use parser pointers, does not enforce parsing order.

Here's the expected control flow order:

1. implementation calls simpleParseConfig from its configure method.
2. simpleParseConfig makes a configuration context
3. parse method from the derived class is called
4. if the configuration was unsuccessful or this is only a check, the old context is reinstantiated. If not, the configuration is kept.

See isc::agent::CtrlAgentCfgMgr and isc::agent::CtrlAgentProcess for example use of this approach.

Definition at line 106 of file d_cfg_mgr.h.

Constructor & Destructor Documentation

DCfgMgrBase()

isc::process::DCfgMgrBase::DCfgMgrBase

(

ConfigPtr

context

)

Constructor.

Parameters

context

is a pointer to the configuration context the manager will use for storing parsed results.

Exceptions

throws

DCfgMgrBaseError if context is null

Definition at line 36 of file d_cfg_mgr.cc.

~DCfgMgrBase()

isc::process::DCfgMgrBase::~DCfgMgrBase ( )

virtual

Destructor.

Definition at line 40 of file d_cfg_mgr.cc.

Member Function Documentation

createNewContext()

virtual ConfigPtr isc::process::DCfgMgrBase::createNewContext ( )

protectedpure virtual

Abstract factory which creates a context instance.

This method is used at the beginning of configuration process to create a fresh, empty copy of the derivation-specific context. This new context will be populated during the configuration process and will replace the existing context provided the configuration process completes without error.

Returns

Returns a ConfigPtr to the new context instance.

Implemented in isc::d2::D2CfgMgr, isc::agent::CtrlAgentCfgMgr, and isc::netconf::NetconfCfgMgr.

getConfigSummary()

virtual std::string isc::process::DCfgMgrBase::getConfigSummary ( const uint32_t  selection )

pure virtual

Returns configuration summary in the textual format.

This method returns the brief text describing the current configuration. It may be used for logging purposes, e.g. whn the new configuration is committed to notify a user about the changes in configuration.

Parameters

selection

Bitfield which describes the parts of the configuration to be returned.

Returns

Summary of the configuration in the textual format.

Implemented in isc::d2::D2CfgMgr, isc::agent::CtrlAgentCfgMgr, and isc::netconf::NetconfCfgMgr.

getContext()

ConfigPtr& isc::process::DCfgMgrBase::getContext ( )

inline

Fetches the configuration context.

Returns

returns a pointer reference to the configuration context.

Definition at line 149 of file d_cfg_mgr.h.

Referenced by isc::agent::CtrlAgentCfgMgr::getCtrlAgentCfgContext(), isc::d2::D2CfgMgr::getD2CfgContext(), and isc::netconf::NetconfCfgMgr::getNetconfConfig().

parse()

isc::data::ConstElementPtr isc::process::DCfgMgrBase::parse ( isc::data::ConstElementPtr  config, bool  check_only  )

protectedvirtual

Parses actual configuration.

This method is expected to be implemented in derived classes that employ SimpleParser paradigm (i.e. they call simpleParseConfig rather than parseConfig from their configure method).

Implementations that do not employ this method may provide dummy implementation.

Parameters

config	the Element tree structure that describes the configuration.
check_only	false for normal configuration, true when verifying only

Returns

an Element that contains the results of configuration composed of an integer status value (0 means successful, non-zero means failure), and a string explanation of the outcome.

Reimplemented in isc::d2::D2CfgMgr, isc::agent::CtrlAgentCfgMgr, and isc::netconf::NetconfCfgMgr.

Definition at line 131 of file d_cfg_mgr.cc.

References isc_throw.

resetContext()

void isc::process::DCfgMgrBase::resetContext ( )

protected

Replaces existing context with a new, empty context.

Definition at line 44 of file d_cfg_mgr.cc.

setCfgDefaults()

void isc::process::DCfgMgrBase::setCfgDefaults ( isc::data::ElementPtr  mutable_config )

protectedvirtual

Adds default values to the given config.

Provides derivations a means to add defaults to a configuration Element map prior to parsing it.

Parameters

mutable_config

- configuration to which defaults should be added

Reimplemented in isc::d2::D2CfgMgr.

Definition at line 127 of file d_cfg_mgr.cc.

setContext()

void isc::process::DCfgMgrBase::setContext ( ConfigPtr &  context )

protected

Update the current context.

Replaces the existing context with the given context.

Parameters

context

Pointer to the new context.

Exceptions

DCfgMgrBaseError

if context is NULL.

Definition at line 50 of file d_cfg_mgr.cc.

References isc_throw.

simpleParseConfig()

isc::data::ConstElementPtr isc::process::DCfgMgrBase::simpleParseConfig	(	isc::data::ConstElementPtr	config,
		bool	check_only = false,
		const std::function< void()> &	post_config_cb = nullptr
	)

Acts as the receiver of new configurations.

This method is similar to what parseConfig did, execept it employs the simple parser paradigm: no intermediate storage, no parser pointers no distinction between params_map and objects_map, parse order (if needed) can be enforced in the actual implementation by calling specific parsers first. See isc::agent::CtrlAgentCfgMgr::parse for example.

If check_only is true, the actual parsing is done to check if the configuration is sane, but is then reverted.

Parameters

config	set of configuration elements to be parsed
check_only	true if the config is to be checked only, but not applied
post_config_cb	Callback to be executed after the usual parsing stage. This can be specified as a C++ lambda which configures other parts of the system based on the parsed configuration information. The callback should throw an exception to signal an error. This method will catch this exception and place an exception string within the result returned.

Returns

an Element that contains the results of configuration composed of an integer status value (0 means successful, non-zero means failure), and a string explanation of the outcome.

Definition at line 59 of file d_cfg_mgr.cc.

References isc::config::answerToText(), isc::config::createAnswer(), isc::log::DBGLVL_COMMAND, isc::process::dctl_logger, LOG_DEBUG, LOG_ERROR, LOG_INFO, and isc::config::parseAnswer().

Here is the call graph for this function:

---

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

• d_cfg_mgr.h
• d_cfg_mgr.cc