--- /dev/null
-/// @brief JSON adaptor between canonical Kea and Yang models.
+ // Copyright (C) 2018 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/.
+
+ #ifndef ISC_ADAPTOR_H
+ #define ISC_ADAPTOR_H 1
+
+ #include <exceptions/exceptions.h>
+ #include <cc/data.h>
+
+ namespace isc {
+ namespace yang {
+
+ /// @brief Missing key error.
+ class MissingKey : public isc::Exception {
+ public:
+ MissingKey(const char* file, size_t line, const char* what) :
+ isc::Exception(file, line, what)
+ {}
+ };
+
-/// what required or rendered by a Yang model, e.g. moving a parameter
++/// @brief JSON adaptor between canonical Kea and YANG models.
+ ///
+ /// An adaptor slightly modifies a JSON configuration between canonical Kea
++/// what required or rendered by a YANG model, e.g. moving a parameter
+ /// to/from a parent.
+ /// The basic adaptor provides a set of tools.
+ class Adaptor {
+ public:
+
+ /// @brief Constructor.
+ Adaptor();
+
+ /// @brief Destructor.
+ virtual ~Adaptor();
+
+ /// @brief Get user context.
+ ///
+ /// Get user-context and/or comment and return it with the comment
+ /// if exists moved inside the user-context (without checking if
+ /// there is already a comment as it should never be the case).
+ ///
+ /// This behavior is used to handle comments. For historical purposes
+ /// Kea allows to define comments in some scopes. Once the user-context
+ /// has been introduced, the comment (as a separate text field)
+ /// disappeared and was moved to comment key within user-context.
+ /// Nevertheless, the old syntax is still supported.
+ static isc::data::ConstElementPtr
+ getContext(isc::data::ConstElementPtr parent);
+
+ /// @brief Moves a parameter from parent to a list of children.
+ ///
+ /// Move a parameter from the parent to each item in a list.
+ /// If the parameter exists in a child, it is skipped for this
+ /// particular child, not overridden.
+ ///
+ /// @param name The parameter name.
+ /// @param parent The parent element.
+ /// @param list The children list.
+ static void fromParent(const std::string& name,
+ isc::data::ConstElementPtr parent,
+ isc::data::ConstElementPtr list);
+
+ /// @brief Moves a parameter to a parent.
+ ///
+ /// Move a parameter from children to the parent. All children
+ /// on the list must have the parameter specified and it has to have
+ /// the same value.
+ ///
+ /// @param name The parameter name.
+ /// @param parent The parent element.
+ /// @param list The children list.
+ static void toParent(const std::string& name,
+ isc::data::ElementPtr parent,
+ isc::data::ConstElementPtr list);
+
+ /// @brief Modify a configuration in its JSON element format.
+ ///
+ /// Smart merging tool, e.g. completing a from yang configuration.
+ ///
+ /// A modification is a path and actions:
+ /// - path item can be:
+ /// * a string: current scope is a map, go down following the string
+ /// as a key.
+ /// * a number: current scope is a list, go down the number as an index.
+ /// * special value -1: current scope is a list, apply to all items.
+ /// * map { "<key>": <value> }: current scope is a list, go down to
+ /// the item using the key / value pair.
+ /// - an action can be: insert, replace or delete:
+ /// * insert adds a value at a key:
+ /// . in a map the key is the new entry key
+ /// . in a list an integer key is the new element index
+ /// . in a list a map key is the key / value pair the to-be-modified
+ /// element contains
+ /// * replace adds or replaces if it already exists a value at
+ /// an entry key in a map.
+ /// * delete removes a value designed by a key
+ ///
+ /// For instance to add a control-socket entry in a configuration
+ /// from a generic (vs Kea) model:
+ /// @code
+ /// path := [ ]
+ /// actions := [ {
+ /// "action": "insert",
+ /// "key": "Dhcp4",
+ /// "value":
+ /// {
+ /// "control-socket":
+ /// {
+ /// "socket-type": "unix",
+ /// "socket-name": "/tmp/kea4-ctrl-socket"
+ /// }
+ /// }
+ /// }
+ /// @endcode
+ ///
+ /// @param path The search list to follow down to the place to
+ /// apply the action list.
+ /// @param actions The action list
+ /// @param config The configuration (JSON map) to modify.
+ /// @note modify does not throw but returns on unexpected conditions.
+ static void modify(isc::data::ConstElementPtr path,
+ isc::data::ConstElementPtr actions,
+ isc::data::ElementPtr config);
+
+ };
+
+ }; // end of namespace isc::yang
+ }; // end of namespace isc
+
+ #endif // ISC_ADAPTOR_H
namespace isc {
namespace yang {
--/// @brief Between Yang and JSON translator class for basic values.
++/// @brief Between YANG and JSON translator class for basic values.
class TranslatorBasic {
public:
/// @brief Destructor.
virtual ~TranslatorBasic();
-- /// @brief Translate basic value from Yang to JSON.
++ /// @brief Translate basic value from YANG to JSON.
///
/// @note Please don't use this outside tests.
///
/// @throw NotImplemented when the value type is not supported.
static isc::data::ElementPtr value(S_Val s_val);
-- /// @brief Get and translate basic value from Yang to JSON.
++ /// @brief Get and translate basic value from YANG to JSON.
///
/// @note Should be const as it is read only...
///
/// @throw NotImplemented when the value type is not supported.
isc::data::ElementPtr getItem(const std::string& xpath);
-- /// @brief Get and translate a list of basic values from Yang to JSON.
++ /// @brief Get and translate a list of basic values from YANG to JSON.
///
/// @param xpath The xpath of the list of basic values.
/// @return The ListElement representing the leaf-list at xpath or
/// null when not found.
isc::data::ElementPtr getItems(const std::string& xpath);
-- /// @brief Translate basic value from JSON to Yang.
++ /// @brief Translate basic value from JSON to YANG.
///
/// @note Please don't use this outside tests.
///
/// @param type The sysrepo type.
static S_Val value(isc::data::ConstElementPtr elem, sr_type_t type);
-- /// @brief Translate and set basic value from JSON to Yang.
++ /// @brief Translate and set basic value from JSON to YANG.
///
/// @param xpath The xpath of the basic value.
/// @param elem The JSON element.
void setItem(const std::string& xpath, isc::data::ConstElementPtr elem,
sr_type_t type);
-- /// @brief Delete basic value from Yang.
++ /// @brief Delete basic value from YANG.
///
/// @param xpath The xpath of the basic value.
void delItem(const std::string& xpath);
/// List iterator methods keeping the session private.
-- /// @brief Get iterator over a Yang list.
++ /// @brief Get iterator over a YANG list.
///
/// @param xpath The xpath of the list.
/// @return An S_Iter_Value pointer. Null is the list does not exist.
S_Iter_Value getIter(const std::string& xpath);
-- /// @brief Get xpath of the next Yang list item.
++ /// @brief Get xpath of the next YANG list item.
///
/// @param iter The iterator pointing to the previous element
/// @return The xpath of the next element. Empty string when at the end of the list.
namespace isc {
namespace yang {
--// @brief Between Yang and JSON translator class for the option data.
++// @brief A translator class for converting an option data between
++// YANG and JSON.
++//
++// Currently supports on kea-dhcp[46]-server, not yet ietf-dhcpv6-server.
++//
++// JSON syntax for Kea DHCP with command channel is:
++// @code
++// {
++// "code": <code>,
++// "name": <name>,
++// "space": <space>,
++// "csv-format": <csv format flag>,
++// "data": <value>,
++// "always-send": <always send flag>,
++// "user-context": { <json map> },
++// "comment": "<comment>"
++// }
++// @endcode
++//
++// YANG syntax for kea-dhcp[46] with code and space as keys is:
++// @code
++// +--rw name? string
++// +--rw data? string
++// +--rw code uint8 / uint16
++// +--rw space string
++// +--rw csv-format? string
++// +--rw always-send? boolean
++// +--rw user-context? string
++// @endcode
class TranslatorOptionData : virtual public TranslatorBasic {
public:
/// @brief Destructor.
virtual ~TranslatorOptionData();
-- /// @brief Get and translate an option data from Yang to JSON.
++ /// @brief Get and translate an option data from YANG to JSON.
///
-- /// JSON syntax for Kea DHCP with command channel is:
-- /// @code
-- /// {
-- /// "code": <code>,
-- /// "name": <name>,
-- /// "space": <space>,
-- /// "csv-format": <csv format flag>,
-- /// "data": <value>,
-- /// "always-send": <always send flag>,
-- /// "user-context": { <json map> },
-- /// "comment": "<comment>"
-- /// }
-- /// @endcode
///
/// @param xpath The xpath of the option data.
/// @return JSON representation of the option data.
/// @throw SysrepoError when sysrepo raises an error.
isc::data::ElementPtr getOptionData(const std::string& xpath);
-- /// @brief Translate and set option data from JSON to Yang.
++ /// @brief Translate and set option data from JSON to YANG.
///
/// @param xpath The xpath of the option data.
/// @param elem The JSON element.
/// @brief setOptionData for kea-dhcp[46].
///
-- /// Yang syntax for kea-dhcp[46] with code and space as keys is:
-- /// @code
-- /// +--rw name? string
-- /// +--rw data? string
-- /// +--rw code uint8 / uint16
-- /// +--rw space string
-- /// +--rw csv-format? string
-- /// +--rw always-send? boolean
-- /// +--rw user-context? string
-- /// @endcode
-- ///
/// @param xpath The xpath of the option data.
/// @param elem The JSON element.
void setOptionDataKea(const std::string& xpath,
std::string model_;
};
--// @brief Between Yang and JSON translator class for option data list.
++// @brief A translator class for converting an option data list between
++// YANG and JSON.
++//
++// Currently supports on kea-dhcp[46]-server, not yet ietf-dhcpv6-server.
++//
++// YANG syntax is a option-data list keyed by code and space.
++//
class TranslatorOptionDataList : virtual public TranslatorOptionData {
public:
/// @brief Destructor.
virtual ~TranslatorOptionDataList();
-- /// @brief Get and translate option data list from Yang to JSON.
++ /// @brief Get and translate option data list from YANG to JSON.
///
/// @param xpath The xpath of the option data list.
/// @throw SysrepoError when sysrepo raises an error.
isc::data::ConstElementPtr getOptionDataList(const std::string& xpath);
-- /// @brief Translate and set option data list from JSON to Yang.
++ /// @brief Translate and set option data list from JSON to YANG.
///
/// @param xpath The xpath of the option data list.
/// @param elem The JSON element.
/// @brief setOptionDataList for kea-dhcp[46].
///
-- /// Yang syntax is a option-data list keyed by code and space.
-- ///
/// @param xpath The xpath of the option data list.
/// @param elem The JSON element.
void setOptionDataListKea(const std::string& xpath,
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
/**
-- @page libyang libkea-yang - Kea Yang Utilities Library
++ @page libyang libkea-yang - Kea YANG Utilities Library
The libkea-yang library was developed to handle base YANG operations,
such are retrieving YANG schema and configuration and translating
data between YANG syntax and JSON that is understandable by Kea.
--@section yangTranslator Translator between Yang and JSON
++@section yangTranslator Translator between YANG and JSON
An essential concept is the idea of translator. It is a primitive that is able
to convert certain data structure between YANG and JSON. It is envisaged
the basic / base class and recursively of translators for embedded parts.
@c isc::yang::TranslatorBasic provides some methods:
-- - getItem() gets and translates basic value from Yang to JSON
-- - getItems() gets and translates a leaf-list from Yang to JSON
++ - getItem() gets and translates basic value from YANG to JSON
++ - getItems() gets and translates a leaf-list from YANG to JSON
(for a list please use an iterator)
-- - setItem() translates and sets a basic value from JSON to Yang
++ - setItem() translates and sets a basic value from JSON to YANG
- delItem() deletes a value
-- - getIter() gets an iterator over a Yang list
++ - getIter() gets an iterator over a YANG list
- getNext() returns the xpath of the next item
@section yangTranslatorPool Pool translator
The new thing here is the use of adaptors to move timers from subnets
to pools and back.
-before translation to Yang to ease this translation or after translation
-from Yang to follow the Kea syntax, for instance by adding static
+ @section yangAdaptor Adapting JSON configuration
+
+ Adaptors are tools which adapts JSON complete or partial configuration
++before translation to YANG to ease this translation or after translation
++from YANG to follow the Kea syntax, for instance by adding static
+ components which are not in the model.
+
+ Methods provided by adaptors are class methods (i.e. declared static).
+ Specific adaptors are derived from the isc::yang::Adaptor base class.
+
@page unitTestsSysrepo Running unit-tests with Sysrepo
To run YANG/NETCONF/Sysrepo tests you obviously need to compile Kea with
projects / thirdparty / kea.git / commitdiff
