Commit 81f4dc50 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰

[5039] Doc updated, doxygen warnings removed.

parent 65d187c0
......@@ -24,6 +24,9 @@ component implementation.
@section dhcpv4ConfigParser Configuration Parser in DHCPv4
Note: parsers are currently being migrated to @ref isc::data::SimpleParser. See
@ref ccSimpleParser page for details.
The common configuration parsers for the DHCP servers are located in the
src/lib/dhcpsrv/parsers/ directory. Parsers specific to the DHCPv4 component
are located in the src/bin/dhcp4/json_config_parser.cc. These parsers derive
......
......@@ -24,6 +24,9 @@ component implementation.
@section dhcpv6ConfigParser Configuration Parsers in DHCPv6
Note: parsers are currently being migrated to @ref isc::data::SimpleParser. See
@ref ccSimpleParser page for details.
The common configuration parsers for the DHCP servers are located in the
src/lib/dhcpsrv/parsers/ directory. Parsers specific to the DHCPv6 component
are located in the src/bin/dhcp6/json_config_parser.cc. These parsers derive
......
......@@ -19,4 +19,6 @@ libkea_cc_la_LDFLAGS = -no-undefined -version-info 1:0:0
libkea_cc_includedir = $(pkgincludedir)/cc
libkea_cc_include_HEADERS = data.h
EXTRA_DIST = cc.dox
CLEANFILES = *.gcno *.gcda
// Copyright (C) 2016 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
/**
@page libcc libcc - Kea configuration commands library
@section ccSimpleParser Simple JSON Parser
Since the early beginnings, our configuration parsing code was a mess. It
started back in 2011 when Tomek joined ISC recently and was told to implement
Kea configuration handling in similar way as DNS Auth module. The code grew
over time (DHCP configuration is significantly more complex than DNS, with
more interdependent values) and as of Kea 1.1 release it became very difficult
to manage. The decision has been made to significantly refactor or even
partially rewrite the parser code. The design for this effort is documented
here: http://kea.isc.org/wiki/SimpleParser It discusses the original issues
and the proposed architecture.
There are several aspects of this new approach. The base class for all parsers
is @ref isc::data::SimpleParser. It simplifies the parsers based on
@ref isc::dhcp::DhcpConfigParser by rejecting the
concept of build/commit phases. Instead, there should be a single method
called parse that takes ConstElementPtr as a single parameter (that's the
JSON structures to be parsed) and returns the config structure to be used
in CfgMgr. An example of such a method can be the following:
@code
std::pair<OptionDescriptor, std::string>
OptionDataParser::parse(isc::data::ConstElementPtr single_option)
@endcode
Since each derived class will have the same parameter, but a different return
type, it's not possible to use virtual methods mechanism. That's perfectly
ok, though, as there is only a single instance of the class needed to parse
arbitrary number of parameters of the same type. There is no need to
keep pointers to the parser object. As such there's fewer incentives to have
one generic way to handle all parsers.
@subsection ccSimpleParserDefaults Default values in Simple Parser
Another simplification comes from the fact that almost all parameters
are mandatory in SimpleParser. One source of complexities in the old
parser was the necessity to deal with optional parameters. Simple
parser deals with that by explicitly requiring the input structure to
have all parameters filled. Obviously, it's not feasible to expect
everyone to always specify all parameters, therefore there's an easy
way to fill missing parameters with their default values. There are
several methods to do this, but the most generic one is:
@code
static size_t
isc::data::SimpleParser::setDefaults(isc::data::ElementPtr scope,
const SimpleDefaults& default_values);
@endcode
It takes a pointer to element to be filled with default values and
vector of default values. Having those values specified in a single
place in a way that can easily be read even by non-programmers is a
big advantage of this approach. Here's an example from simple_parser.cc file:
@code
/// This table defines default values for option definitions in DHCPv6
const SimpleDefaults OPTION6_DEF_DEFAULTS = {
{ "record-types", Element::string, ""},
{ "space", Element::string, "dhcp6"},
{ "array", Element::boolean, "false"},
{ "encapsulate", Element::string, "" }
};
@endcode
This array (which technically is implemented as a vector and
initialized the C++11 way) can be passed to the aforementioned
setDefaults. That code will iterate over all default values and see if
there are explicit values provided. If not, the gaps will be filled
with default values. There are also convenience methods specified for
filling in option data defaults, option definition defaults and
setAllDefaults that sets all defaults (starts with global, but then
walks down the Element tree and fills defaults in subsequent scopes).
@subsection ccSimpleParserInherits Inheriting parameters between scopes
SimpleParser provides a mechanism to inherit parameters between scopes,
e.g. to inherit global parameters in the subnet scope if more specific
values are not defined in the subnet scope. This is achieved by calling
@code
static size_t SimpleParser::deriveParams(isc::data::ConstElementPtr parent,
isc::data::ElementPtr child,
const ParamsList& params);
@endcode
ParamsList is a simple vector<string>. There will be more specific
methods implemented in the future, but for the time being only
@ref isc::data::SimpleParser::deriveParams is implemented.
*/
......@@ -33,7 +33,8 @@ typedef std::vector<std::string> ParamsList;
/// @brief A simple parser
///
/// This class is intended to be a simpler replacement for @ref DhcpConfigParser.
/// This class is intended to be a simpler replacement for
/// @ref isc::dhcp::DhcpConfigParser.
/// The simplification comes from several factors:
/// - no build/commit nonsense. There's a single step:
/// CfgStorage parse(ConstElementPtr json)
......@@ -83,6 +84,15 @@ class SimpleParser {
static size_t setDefaults(isc::data::ElementPtr scope,
const SimpleDefaults& default_values);
/// @brief Sets the default values for all entries in a list
///
/// This is a simple utility method that iterates over all
/// parameters in a list and calls setDefaults for each
/// entry.
///
/// @param list list to be iterated over
/// @param default_values list of default values
/// @return number of parameters inserted
static size_t setListDefaults(isc::data::ElementPtr list,
const SimpleDefaults& default_values);
......
......@@ -476,92 +476,5 @@ is used by DHCPv4 and DHCPv6 components.
DHCPv4-over-DHCPv6 which are relayed by a DHCPv6 relay are not yet supported.
@section dhcp6SimpleParser Simple JSON Parser
Since the early beginnings, our configuration parsing code was a mess. It
started back in 2011 when Tomek joined ISC recently and was told to implement
Kea configuration handling in similar way as DNS Auth module. The code grew
over time (DHCP configuration is significantly more complex than DNS, with
more interdependent values) and as of Kea 1.1 release it became very difficult
to manage. The decision has been made to significantly refactor or even
partially rewrite the parser code. The design for this effort is documented
here: http://kea.isc.org/wiki/SimpleParser It discusses the original issues
and the proposed architecture.
There are several aspects of this new approach. The base class for all parsers
is @ref isc::dhcp::SimpleParser. It simplifies the parser be rejecting the
concept of build/commit phases. Instead, there should be a single method
called parse that takes ConstElementPtr as a single parameter (that's the
JSON structures to be parsed) and returns the config structure to be used
in CfgMgr. An example of such a method can be the following:
@code
std::pair<OptionDescriptor, std::string>
OptionDataParser::parse(isc::data::ConstElementPtr single_option)
@endcode
Since each derived class will have the same parameter, but a different return
type, it's not possible to use virtual methods mechanism. That's perfectly
ok, though, as there is only a single instance of the class needed to parse
arbitrary number of parameters of the same type, so there is no need to
keep pointers to the parser object. As such there's fewer incentives to have
one generic way to handle all parsers.
@subsection dhcp6SimpleParserDefaults Default values in Simple Parser
Another simplification comes from the fact that almost all parameters
are mandatory in SimpleParser. One source of complexities in the old
parser was the necessity to deal with optional parameters. Simple
parser deals with that by explicitly requiring the input structure to
have all parameters filled. Obviously, it's not feasible to expect
everyone to always specify all parameters, therefore there's an easy
way to fill missing parameters with their default values. There are
several methods to do this, but the most generic one is:
@code
static size_t
isc::dhcp::SimpleParser::setDefaults(isc::data::ElementPtr scope,
const SimpleDefaults& default_values);
@endcode
It takes a pointer to element to be filled with default values and
vector of default values. Having those values specified in a single
place in a way that can easily be read even by non-programmers is a
big advantage of this approach. Here's an example from simple_parser.cc file:
@code
/// This table defines default values for option definitions in DHCPv6
const SimpleDefaults OPTION6_DEF_DEFAULTS = {
{ "record-types", Element::string, ""},
{ "space", Element::string, "dhcp6"},
{ "array", Element::boolean, "false"},
{ "encapsulate", Element::string, "" }
};
@endcode
This array (which technically is implemented as a vector and
initialized the C++11 way) can be passed to the aforementioned
setDefaults. That code will iterate over all default values and see if
there are explicit values provided. If not, the gaps will be filled
with default values. There are also convenience methods specified for
filling in option data defaults, option definition defaults and
setAllDefaults that sets all defaults (starts with global, but then
walks down the Element tree and fills defaults in subsequent scopes).
@subsection dhcp6SimpleParserInherits Inheriting parameters between scopes
SimpleParser provides a mechanism to inherit parameters between scopes,
e.g. to inherit global parameters in the subnet scope if more specific
values are not defined in the subnet scope. This is achieved by calling
@code
static size_t SimpleParser::deriveParams(isc::data::ConstElementPtr parent,
isc::data::ElementPtr child,
const ParamsList& params);
@endcode
ParamsList is a simple vector<string>. There will be more specific
methods implemented in the future, but for the time being only
@ref isc::dhcp::SimpleParser::inheritGlobalToSubnet is implemented.
*/
......@@ -552,7 +552,7 @@ public:
///
/// Note: ElementPtr is expected to contain all fields. If your
/// ElementPtr does not have them, please use
/// @ref SimpleParser::setOptionDefaults to fill the missing fields
/// @ref isc::data::SimpleParser::setDefaults to fill the missing fields
/// with default values.
///
/// @param single_option ElementPtr containing option defintion
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment