[master] Merge branch 'trac5021'

doc/devel/mainpage.dox

@@ -71,9 +71,6 @@
  *   - @subpage dhcpv6SignalBasedReconfiguration
  *   - @subpage dhcpv6Other
  *   - @subpage dhcpv4o6Dhcp6
- * - @subpage libprocess
- *   - @subpage cpl
- *   - @subpage cplSignals
  * - @subpage d2
  *   - @subpage d2ProcessDerivation
  *   - @subpage d2ConfigMgt
@@ -91,6 +88,13 @@
  *   - @subpage ctrlSocketClient
  *   - @subpage ctrlSocketImpl
  *   - @subpage ctrlSocketConnections
+ * - @subpage dhcpDatabaseBackends
+ * - @subpage configBackend
+ *   - @subpage configBackendJSONDesign
+ * - @subpage perfdhcpInternals
+ *
+ * @section libraries Kea libraries
+ * - @subpage libcc
  * - @subpage libdhcp
  *   - @subpage libdhcpIntro
  *   - @subpage libdhcpRelay
@@ -98,6 +102,7 @@
  *   - @subpage libdhcpPktFilter
  *   - @subpage libdhcpPktFilter6
  *   - @subpage libdhcpErrorLogging
+ * - @subpage libdhcp_ddns
  * - @subpage libdhcpsrv
  *   - @subpage leasemgr
  *   - @subpage cfgmgr
@@ -108,12 +113,10 @@
  *   - @subpage leaseReclamationRoutine
  *   - @subpage subnetSelect
  *   - @subpage dhcp4o6Ipc
- * - @subpage libdhcp_ddns
- * - @subpage dhcpDatabaseBackends
- * - @subpage dhcpEval
- * - @subpage configBackend
- *   - @subpage configBackendJSONDesign
- * - @subpage perfdhcpInternals
+ * - @subpage libeval
+ * - @subpage libprocess
+ *   - @subpage cpl
+ *   - @subpage cplSignals
  *
  * @section miscellaneousTopics Miscellaneous Topics
  * - @subpage logKeaLogging

src/bin/dhcp4/dhcp4.dox

@@ -279,7 +279,7 @@ class definitions that are subnet specific.
 Client classification is done in isc::dhcp::Dhcpv4Srv::classifyPacket. First, the old
 "built-in" (see @ref dhcpv4ClassifierSimple) classification is called. Then the code
 iterates over all class definitions and for each class definition it calls
-isc::dhcp::evaluate, which is implemented in libeval (see @ref dhcpEval). If the
+isc::dhcp::evaluate, which is implemented in libeval (see @ref libeval). If the
 evaluation is successful, the class name is added to the packet (by calling
 isc::dhcp::pkt::addClass).
 

src/bin/dhcp4/json_config_parser.cc

@@ -566,7 +566,7 @@ configureDhcp4Server(Dhcpv4Srv&, isc::data::ConstElementPtr config_set) {
         // This is a way to convert ConstElementPtr to ElementPtr.
         // We need a config that can be edited, because we will insert
         // default values and will insert derived values as well.
-        ElementPtr mutable_cfg = Element::getMutableMap(config_set);
+        ElementPtr mutable_cfg = const_pointer_cast<Element>(config_set);
 
         // Set all default values if not specified by the user.
         SimpleParser4::setAllDefaults(mutable_cfg);

src/bin/dhcp4/parser_context.cc

@@ -24,14 +24,14 @@ Parser4Context::~Parser4Context()
 {
 }
 
-isc::data::ConstElementPtr
+isc::data::ElementPtr
 Parser4Context::parseString(const std::string& str, ParserType parser_type)
 {
     scanStringBegin(str, parser_type);
     return (parseCommon());
 }
 
-isc::data::ConstElementPtr
+isc::data::ElementPtr
 Parser4Context::parseFile(const std::string& filename, ParserType parser_type) {
     FILE* f = fopen(filename.c_str(), "r");
     if (!f) {
@@ -41,7 +41,7 @@ Parser4Context::parseFile(const std::string& filename, ParserType parser_type) {
     return (parseCommon());
 }
 
-isc::data::ConstElementPtr
+isc::data::ElementPtr
 Parser4Context::parseCommon() {
     isc::dhcp::Dhcp4Parser parser(*this);
     // Uncomment this to get detailed parser logs.

src/bin/dhcp4/parser_context.h

@@ -123,8 +123,8 @@ public:
     /// @param str string to be parsed
     /// @param parser_type specifies expected content (usually DHCP4 or generic JSON)
     /// @return Element structure representing parsed text.
-    isc::data::ConstElementPtr parseString(const std::string& str,
-                                           ParserType parser_type);
+    isc::data::ElementPtr parseString(const std::string& str,
+                                      ParserType parser_type);
 
     /// @brief Run the parser on the file specified.
     ///
@@ -136,8 +136,8 @@ public:
     /// @param filename file to be parsed
     /// @param parser_type specifies expected content (usually DHCP4 or generic JSON)
     /// @return Element structure representing parsed text.
-    isc::data::ConstElementPtr parseFile(const std::string& filename,
-                                         ParserType parser_type);
+    isc::data::ElementPtr parseFile(const std::string& filename,
+                                    ParserType parser_type);
 
     /// @brief Error handler
     ///
@@ -312,7 +312,7 @@ public:
     /// @brief Common part of parseXXX
     ///
     /// @return Element structure representing parsed text.
-    isc::data::ConstElementPtr parseCommon();
+    isc::data::ElementPtr parseCommon();
 };
 
 }; // end of isc::eval namespace

src/bin/dhcp4/tests/dhcp4_test_utils.h

@@ -483,7 +483,7 @@ public:
 ///
 /// @param in string to be parsed
 /// @return ElementPtr structure representing parsed JSON
-inline isc::data::ConstElementPtr
+inline isc::data::ElementPtr
 parseJSON(const std::string& in)
 {
     isc::dhcp::Parser4Context ctx;
@@ -498,7 +498,7 @@ parseJSON(const std::string& in)
 /// @param in string to be parsed
 /// @param verbose display the exception message when it fails
 /// @return ElementPtr structure representing parsed JSON
-inline isc::data::ConstElementPtr
+inline isc::data::ElementPtr
 parseDHCP4(const std::string& in, bool verbose = false)
 {
     try {
@@ -520,7 +520,7 @@ parseDHCP4(const std::string& in, bool verbose = false)
 /// @param in string to be parsed
 /// @param verbose display the exception message when it fails
 /// @return ElementPtr structure representing parsed JSON
-inline isc::data::ConstElementPtr
+inline isc::data::ElementPtr
 parseOPTION_DEF(const std::string& in, bool verbose = false)
 {
     try {

src/bin/dhcp4/tests/simple_parser4_unittest.cc

@@ -7,6 +7,7 @@
 #include <config.h>
 #include <gtest/gtest.h>
 #include <dhcp4/simple_parser4.h>
+#include <dhcp4/tests/dhcp4_test_utils.h>
 #include <cc/data.h>
 
 using namespace isc::data;
@@ -44,7 +45,7 @@ public:
 // This test checks if global defaults are properly set for DHCPv4.
 TEST_F(SimpleParser4Test, globalDefaults4) {
 
-    ElementPtr empty = Element::fromJSON("{ }");
+    ElementPtr empty = parseJSON("{ }");
     size_t num = 0;
 
     EXPECT_NO_THROW(num = SimpleParser4::setAllDefaults(empty));
@@ -65,12 +66,12 @@ TEST_F(SimpleParser4Test, globalDefaults4) {
 // This test checks if the parameters can be inherited from the global
 // scope to the subnet scope.
 TEST_F(SimpleParser4Test, inheritGlobalToSubnet4) {
-    ElementPtr global = Element::fromJSON("{ \"renew-timer\": 1,"
-                                          "  \"rebind-timer\": 2,"
-                                          "  \"preferred-lifetime\": 3,"
-                                          "  \"valid-lifetime\": 4"
-                                          "}");
-    ElementPtr subnet = Element::fromJSON("{ \"renew-timer\": 100 }");
+    ElementPtr global = parseJSON("{ \"renew-timer\": 1,"
+                                  "  \"rebind-timer\": 2,"
+                                  "  \"preferred-lifetime\": 3,"
+                                  "  \"valid-lifetime\": 4"
+                                  "}");
+    ElementPtr subnet = parseJSON("{ \"renew-timer\": 100 }");
 
     // we should inherit 3 parameters. Renew-timer should remain intact,
     // as it was already defined in the subnet scope.

src/bin/dhcp6/dhcp6.dox

@@ -544,7 +544,7 @@ Client classification is done in isc::dhcp::Dhcpv6Srv::classifyPacket. First, th
 "built-in" (see @ref dhcpv6ClassifierSimple) classification is called (see @ref
 isc::dhcp::Dhcpv6Srv::classifyByVendor). Then the code iterates over all class definitions
 and for each class definition it calls isc::dhcp::evaluate, which is implemented in libeval
-(see @ref dhcpEval). If the evaluation is successful, the class name is added to the packet
+(see @ref libeval). If the evaluation is successful, the class name is added to the packet
 (by calling isc::dhcp::pkt::addClass).
 
 If packet belongs to at least one class, this fact is logged. If there are any

src/bin/dhcp6/json_config_parser.cc

@@ -840,7 +840,7 @@ configureDhcp6Server(Dhcpv6Srv&, isc::data::ConstElementPtr config_set) {
         // This is a way to convert ConstElementPtr to ElementPtr.
         // We need a config that can be edited, because we will insert
         // default values and will insert derived values as well.
-        ElementPtr mutable_cfg = Element::getMutableMap(config_set);
+        ElementPtr mutable_cfg = const_pointer_cast<Element>(config_set);
 
         SimpleParser6::setAllDefaults(mutable_cfg);
 

src/bin/dhcp6/parser_context.cc

@@ -24,14 +24,14 @@ Parser6Context::~Parser6Context()
 {
 }
 
-isc::data::ConstElementPtr
+isc::data::ElementPtr
 Parser6Context::parseString(const std::string& str, ParserType parser_type)
 {
     scanStringBegin(str, parser_type);
     return (parseCommon());
 }
 
-isc::data::ConstElementPtr
+isc::data::ElementPtr
 Parser6Context::parseFile(const std::string& filename, ParserType parser_type) {
     FILE* f = fopen(filename.c_str(), "r");
     if (!f) {
@@ -41,7 +41,7 @@ Parser6Context::parseFile(const std::string& filename, ParserType parser_type) {
     return (parseCommon());
 }
 
-isc::data::ConstElementPtr
+isc::data::ElementPtr
 Parser6Context::parseCommon() {
     isc::dhcp::Dhcp6Parser parser(*this);
     // Uncomment this to get detailed parser logs.

src/bin/dhcp6/parser_context.h

@@ -126,8 +126,8 @@ public:
     /// @param str string to be parsed
     /// @param parser_type specifies expected content (usually DHCP6 or generic JSON)
     /// @return Element structure representing parsed text.
-    isc::data::ConstElementPtr parseString(const std::string& str,
-                                           ParserType parser_type);
+    isc::data::ElementPtr parseString(const std::string& str,
+                                      ParserType parser_type);
 
     /// @brief Run the parser on the file specified.
     ///
@@ -139,8 +139,8 @@ public:
     /// @param filename file to be parsed
     /// @param parser_type specifies expected content (usually DHCP6 or generic JSON)
     /// @return Element structure representing parsed text.
-    isc::data::ConstElementPtr parseFile(const std::string& filename,
-                                         ParserType parser_type);
+    isc::data::ElementPtr parseFile(const std::string& filename,
+                                    ParserType parser_type);
 
     /// @brief Error handler
     ///
@@ -321,7 +321,7 @@ public:
     /// @brief Common part of parseXXX
     ///
     /// @return Element structure representing parsed text.
-    isc::data::ConstElementPtr parseCommon();
+    isc::data::ElementPtr parseCommon();
 };
 
 }; // end of isc::eval namespace

src/bin/dhcp6/tests/dhcp6_test_utils.h

@@ -643,7 +643,7 @@ public:
 ///
 /// @param in string to be parsed
 /// @return ElementPtr structure representing parsed JSON
-inline isc::data::ConstElementPtr
+inline isc::data::ElementPtr
 parseJSON(const std::string& in)
 {
     isc::dhcp::Parser6Context ctx;
@@ -658,7 +658,7 @@ parseJSON(const std::string& in)
 /// @param in string to be parsed
 /// @param verbose display the exception message when it fails
 /// @return ElementPtr structure representing parsed JSON
-inline isc::data::ConstElementPtr
+inline isc::data::ElementPtr
 parseDHCP6(const std::string& in, bool verbose = false)
 {
     try {
@@ -680,7 +680,7 @@ parseDHCP6(const std::string& in, bool verbose = false)
 /// @param in string to be parsed
 /// @param verbose display the exception message when it fails
 /// @return ElementPtr structure representing parsed JSON
-inline isc::data::ConstElementPtr
+inline isc::data::ElementPtr
 parseOPTION_DEF(const std::string& in, bool verbose = false)
 {
     try {

src/bin/dhcp6/tests/simple_parser6_unittest.cc

@@ -5,13 +5,15 @@
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 #include <config.h>
-#include <cc/data.h>
-#include <dhcp6/simple_parser6.h>
 #include <gtest/gtest.h>
+#include <dhcp6/simple_parser6.h>
+#include <dhcp6/tests/dhcp6_test_utils.h>
+#include <cc/data.h>
 
 using namespace isc;
 using namespace isc::data;
 using namespace isc::dhcp;
+using namespace isc::dhcp::test;
 
 namespace {
 
@@ -44,7 +46,7 @@ public:
 // This test checks if global defaults are properly set for DHCPv6.
 TEST_F(SimpleParser6Test, globalDefaults6) {
 
-    ElementPtr empty = Element::fromJSON("{ }");
+    ElementPtr empty = parseJSON("{ }");
     size_t num = 0;
 
     EXPECT_NO_THROW(num = SimpleParser6::setAllDefaults(empty));
@@ -61,12 +63,12 @@ TEST_F(SimpleParser6Test, globalDefaults6) {
 // This test checks if the parameters can be inherited from the global
 // scope to the subnet scope.
 TEST_F(SimpleParser6Test, inheritGlobalToSubnet6) {
-    ElementPtr global = Element::fromJSON("{ \"renew-timer\": 1,"
+    ElementPtr global = parseJSON("{ \"renew-timer\": 1,"
                                           "  \"rebind-timer\": 2,"
                                           "  \"preferred-lifetime\": 3,"
                                           "  \"valid-lifetime\": 4"
                                           "}");
-    ElementPtr subnet = Element::fromJSON("{ \"renew-timer\": 100 }");
+    ElementPtr subnet = parseJSON("{ \"renew-timer\": 100 }");
 
     // we should inherit 3 parameters. Renew-timer should remain intact,
     // as it was already defined in the subnet scope.

src/lib/cc/cc.dox

@@ -5,7 +5,7 @@
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 /**
- @page libcc libcc - Kea configuration commands library
+ @page libcc libkea-cc - Kea Configuration Utilities Library
 
 @section ccSimpleParser Simple JSON Parser
 
@@ -36,7 +36,7 @@ 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
+keep pointers to the parser object. As such there are fewer incentives to have
 one generic way to handle all parsers.
 
 @subsection ccSimpleParserDefaults Default values in Simple Parser

src/lib/cc/simple_parser.cc

@@ -123,7 +123,7 @@ size_t SimpleParser::setDefaults(isc::data::ElementPtr scope,
 
         // ... and insert it into the provided Element tree.
         scope->set(def_value.name_, x);
-        cnt++;
+        ++cnt;
     }
 
     return (cnt);

src/lib/cc/simple_parser.h

@@ -8,6 +8,7 @@
 #define SIMPLE_PARSER_H
 
 #include <cc/data.h>
+#include <vector>
 #include <string>
 #include <stdint.h>
 #include <vector>
@@ -34,17 +35,20 @@ typedef std::vector<std::string> ParamsList;
 
 /// @brief A simple parser
 ///
-/// This class is intended to be a simpler replacement for
-/// @ref isc::dhcp::DhcpConfigParser.
+/// This class is intended to be a simpler replacement for @ref
+/// isc::dhcp::DhcpConfigParser. This class has been initially created to
+/// facilitate DHCPv4 and DHCPv6 servers' configuration parsing. Thus examples
+/// provided herein are related to DHCP configuration. Nevertheless, this is a
+/// generic class to be used in other modules too.
+///
 /// The simplification comes from several factors:
 /// - no build/commit nonsense. There's a single step:
 ///   CfgStorage parse(ConstElementPtr json)
 ///   that converts JSON configuration into an object and returns it.
-/// - almost no state kept. The only state kept in most cases is whether the
-///   parsing is done in v4 or v6 context. This greatly simplifies the
-///   parsers (no contexts, no child parsers list, no separate storage for
-///   uint32, strings etc. In fact, there's so little state kept, that this
-///   parser is mostly a collection of static methods.
+/// - no state kept. This greatly simplifies the parsers (no contexts, no child
+///   parsers list, no separate storage for uint32, strings etc. In fact,
+///   this base class is purely static. However, some derived classes may store
+///   some state. Implementors are advised to store as little state as possible.
 /// - no optional parameters (all are mandatory). This simplifies the parser,
 ///   but introduces a new step before parsing where we insert the default
 ///   values into client configuration before parsing. This is actually a good
@@ -99,14 +103,15 @@ class SimpleParser {
 
     /// @brief Utility method that returns position of an element
     ///
-    /// It's mostly useful for logging.
+    /// It's mostly useful for logging. When any necessary parameter is
+    /// missing (either parent is null or it doesn't contain specified
+    /// name) ZERO_POSITION is returned.
     ///
     /// @param name position of that element will be returned
     /// @param parent parent element (optional)
     /// @return position of the element specified.
     static const data::Element::Position&
-    getPosition(const std::string& name, const data::ConstElementPtr parent =
-                data::ConstElementPtr());
+    getPosition(const std::string& name, const data::ConstElementPtr parent);
 
  protected:
 

src/lib/dhcp/libdhcp++.dox

@@ -5,7 +5,7 @@
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 /**
-@page libdhcp libdhcp++
+@page libdhcp libkea-dhcp++ - Low Level DHCP Library
 
 @section libdhcpIntro Libdhcp++ Library Introduction
 

src/lib/dhcp_ddns/libdhcp_ddns.dox

@@ -5,7 +5,7 @@
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 /**
-@page libdhcp_ddns libdhcp_ddns - DHCP_DDNS Request I/O Library
+@page libdhcp_ddns libkea-dhcp_ddns - DHCP_DDNS Request I/O Library
 
 @section libdhcp_ddnsIntro Introduction
 

src/lib/dhcpsrv/libdhcpsrv.dox

@@ -5,7 +5,7 @@
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 /**
- @page libdhcpsrv libdhcpsrv - Server DHCP library
+ @page libdhcpsrv libkea-dhcpsrv - Server DHCP Library
 
 This library contains code used for the DHCPv4 and DHCPv6 servers' operations,
 including the "Lease Manager" that manages information about leases and the

src/lib/dhcpsrv/tests/dhcp_parsers_unittest.cc

@@ -428,7 +428,6 @@ public:
                           const SimpleDefaults& option_def_defaults) {
         size_t cnt = 0;
         // Set global defaults first.
-        /// @todo: Uncomment as part of the ticket 5019 work.
         cnt = SimpleParser::setDefaults(global, global_defaults);
 
         // Now set option defintion defaults for each specified option definition

src/lib/eval/eval.dox

@@ -5,7 +5,7 @@
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 /**
-  @page dhcpEval libeval - Expression evaluation and client classification
+  @page libeval libkea-eval - Expression Evaluation and Client Classification Library
 
   @section dhcpEvalIntroduction Introduction