Current File : //backups/router/usr/local/include/kea/cc/data.h
// Copyright (C) 2010-2024 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_DATA_H
#define ISC_DATA_H 1
#include <util/bigints.h>
#include <iostream>
#include <map>
#include <stdexcept>
#include <string>
#include <vector>
#include <boost/shared_ptr.hpp>
#include <stdint.h>
#include <exceptions/exceptions.h>
namespace isc { namespace data {
class Element;
// todo: describe the rationale behind ElementPtr?
typedef boost::shared_ptr<Element> ElementPtr;
typedef boost::shared_ptr<const Element> ConstElementPtr;
///
/// @brief A standard Data module exception that is thrown if a function
/// is called for an Element that has a wrong type (e.g. int_value on a
/// ListElement)
///
class TypeError : public isc::Exception {
public:
TypeError(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) {}
};
///
/// @brief A standard Data module exception that is thrown if a parse
/// error is encountered when constructing an Element from a string
///
// i'd like to use Exception here but we need one that is derived from
// runtime_error (as this one is directly based on external data, and
// i want to add some values to any static data string that is provided)
class JSONError : public isc::Exception {
public:
JSONError(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) {}
};
///
/// @brief The @c Element class represents a piece of data, used by
/// the command channel and configuration parts.
///
/// An @c Element can contain simple types (int, real, string, bool and
/// None), and composite types (list and string->element maps)
///
/// Elements should in calling functions usually be referenced through
/// an @c ElementPtr, which can be created using the factory functions
/// @c Element::create() and @c Element::fromJSON()
///
/// Notes to developers: Element is a base class, implemented by a
/// specific subclass for each type (IntElement, BoolElement, etc).
/// Element does define all functions for all types, and defaults to
/// raising a @c TypeError for functions that are not supported for
/// the type in question.
///
class Element {
public:
/// @brief Represents the position of the data element within a
/// configuration string.
///
/// Position comprises a file name, line number and an offset within this
/// line where the element value starts. For example, if the JSON string is
///
/// @code
/// { "foo": "some string",
/// "bar": 123 }
/// \endcode
///
/// the position of the element "bar" is: line_ = 2; pos_ = 9, because
/// beginning of the value "123" is at offset 9 from the beginning of
/// the second line, including whitespaces.
///
/// Note that the @c Position structure is used as an argument to @c Element
/// constructors and factory functions to avoid ambiguity and so that the
/// uint32_t arguments holding line number and position within the line are
/// not confused with the @c Element values passed to these functions.
struct Position {
std::string file_; ///< File name.
uint32_t line_; ///< Line number.
uint32_t pos_; ///< Position within the line.
/// @brief Default constructor.
Position() : file_(""), line_(0), pos_(0) {
}
/// @brief Constructor.
///
/// @param file File name.
/// @param line Line number.
/// @param pos Position within the line.
Position(const std::string& file, const uint32_t line,
const uint32_t pos)
: file_(file), line_(line), pos_(pos) {
}
/// @brief Returns the position in the textual format.
///
/// The returned position has the following format: file:line:pos.
std::string str() const;
};
/// @brief Returns @c Position object with line_ and pos_ set to 0, and
/// with an empty file name.
///
/// The object containing two zeros is a default for most of the
/// methods creating @c Element objects. The returned value is static
/// so as it is not created everytime the function with the default
/// position argument is called.
static const Position& ZERO_POSITION() {
static Position position("", 0, 0);
return (position);
}
/// @brief The types that an Element can hold
///
/// Some of these types need to match their associated integer from the
/// parameter_data_type database table, so let the enums be explicitly
/// mapped to integers, to reduce the chance of messing up.
///
/// any is a special type used in list specifications, specifying that the
/// elements can be of any type.
enum types {
integer = 0,
real = 1,
boolean = 2,
null = 3,
string = 4,
bigint = 5,
list = 6,
map = 7,
any = 8,
};
private:
// technically the type could be omitted; is it useful?
// should we remove it or replace it with a pure virtual
// function getType?
types type_;
/// @brief Position of the element in the configuration string.
Position position_;
protected:
/// @brief Constructor.
///
/// @param t Element type.
/// @param pos Structure holding position of the value of the data element.
/// It comprises the line number and the position within this line. The values
/// held in this structure are used for error logging purposes.
Element(types t, const Position& pos = ZERO_POSITION())
: type_(t), position_(pos) {
}
public:
// base class; make dtor virtual
virtual ~Element() {};
/// @return the type of this element
types getType() const { return (type_); }
/// @brief Returns position where the data element's value starts in a
/// configuration string.
///
/// @warning The returned reference is valid as long as the object which
/// created it lives.
const Position& getPosition() const { return (position_); }
/// Returns a string representing the Element and all its
/// child elements; note that this is different from stringValue(),
/// which only returns the single value of a StringElement
///
/// The resulting string will contain the Element in JSON format.
///
/// @return std::string containing the string representation
std::string str() const;
/// Returns the wireformat for the Element and all its child
/// elements.
///
/// @return std::string containing the element in wire format
std::string toWire() const;
void toWire(std::ostream& out) const;
/// @brief Add the position to a TypeError message
/// should be used in place of isc_throw(TypeError, error)
#define throwTypeError(error) \
{ \
std::string msg_ = error; \
if ((position_.file_ != "") || \
(position_.line_ != 0) || \
(position_.pos_ != 0)) { \
msg_ += " in (" + position_.str() + ")"; \
} \
isc_throw(TypeError, msg_); \
}
/// @name pure virtuals, every derived class must implement these
/// @return true if the other ElementPtr has the same value and the same
/// type (or a different and compatible type), false otherwise.
virtual bool equals(const Element& other) const = 0;
/// Converts the Element to JSON format and appends it to
/// the given stringstream.
virtual void toJSON(std::ostream& ss) const = 0;
/// @name Type-specific getters
///
/// @brief These functions only
/// work on their corresponding Element type. For all other
/// types, a TypeError is thrown.
/// If you want an exception-safe getter method, use
/// getValue() below
//@{
virtual int64_t intValue() const
{ throwTypeError("intValue() called on non-integer Element"); };
virtual isc::util::int128_t bigIntValue() const {
throwTypeError("bigIntValue() called on non-big-integer Element");
}
virtual double doubleValue() const
{ throwTypeError("doubleValue() called on non-double Element"); };
virtual bool boolValue() const
{ throwTypeError("boolValue() called on non-Bool Element"); };
virtual std::string stringValue() const
{ throwTypeError("stringValue() called on non-string Element"); };
virtual const std::vector<ElementPtr>& listValue() const {
// replace with real exception or empty vector?
throwTypeError("listValue() called on non-list Element");
};
virtual const std::map<std::string, ConstElementPtr>& mapValue() const {
// replace with real exception or empty map?
throwTypeError("mapValue() called on non-map Element");
};
//@}
/// @name Exception-safe getters
///
/// @brief The getValue() functions return false if the given reference
/// is of another type than the element contains
/// By default it always returns false; the derived classes
/// override the function for their type, copying their
/// data to the given reference and returning true
///
//@{
virtual bool getValue(int64_t& t) const;
virtual bool getValue(double& t) const;
virtual bool getValue(bool& t) const;
virtual bool getValue(std::string& t) const;
virtual bool getValue(std::vector<ElementPtr>& t) const;
virtual bool getValue(std::map<std::string, ConstElementPtr>& t) const;
//@}
///
/// @name Exception-safe setters.
///
/// @brief Return false if the Element is not
/// the right type. Set the value and return true if the Elements
/// is of the correct type
///
/// Notes: Read notes of IntElement definition about the use of
/// long long int, long int and int.
//@{
virtual bool setValue(const long long int v);
virtual bool setValue(const isc::util::int128_t& v);
bool setValue(const long int i) { return (setValue(static_cast<long long int>(i))); };
bool setValue(const int i) { return (setValue(static_cast<long long int>(i))); };
virtual bool setValue(const double v);
virtual bool setValue(const bool t);
virtual bool setValue(const std::string& v);
virtual bool setValue(const std::vector<ElementPtr>& v);
virtual bool setValue(const std::map<std::string, ConstElementPtr>& v);
//@}
// Other functions for specific subtypes
/// @name ListElement functions
///
/// @brief If the Element on which these functions are called are not
/// an instance of ListElement, a TypeError exception is thrown.
//@{
/// Returns the ElementPtr at the given index. If the index is out
/// of bounds, this function throws an std::out_of_range exception.
/// @param i The position of the ElementPtr to return
virtual ConstElementPtr get(const int i) const;
/// @brief returns element as non-const pointer
///
/// @param i The position of the ElementPtr to retrieve
/// @return specified element pointer
virtual ElementPtr getNonConst(const int i) const;
/// Sets the ElementPtr at the given index. If the index is out
/// of bounds, this function throws an std::out_of_range exception.
/// @param i The position of the ElementPtr to set
/// @param element The ElementPtr to set at the position
virtual void set(const size_t i, ElementPtr element);
/// Adds an ElementPtr to the list
/// @param element The ElementPtr to add
virtual void add(ElementPtr element);
/// Removes the element at the given position. If the index is out
/// of nothing happens.
/// @param i The index of the element to remove.
virtual void remove(const int i);
/// Returns the number of elements in the list.
virtual size_t size() const;
/// Return true if there are no elements in the list.
virtual bool empty() const;
//@}
/// @name MapElement functions
///
/// @brief If the Element on which these functions are called are not
/// an instance of MapElement, a TypeError exception is thrown.
//@{
/// Returns the ElementPtr at the given key
/// @param name The key of the Element to return
/// @return The ElementPtr at the given key, or null if not present
virtual ConstElementPtr get(const std::string& name) const;
/// Sets the ElementPtr at the given key
/// @param name The key of the Element to set
/// @param element The ElementPtr to set at the given key.
virtual void set(const std::string& name, ConstElementPtr element);
/// Remove the ElementPtr at the given key
/// @param name The key of the Element to remove
virtual void remove(const std::string& name);
/// Checks if there is data at the given key
/// @param name The key of the Element checked for existence
/// @return true if there is data at the key, false if not.
virtual bool contains(const std::string& name) const;
/// Recursively finds any data at the given identifier. The
/// identifier is a /-separated list of names of nested maps, with
/// the last name being the leaf that is returned.
///
/// For instance, if you have a MapElement that contains another
/// MapElement at the key "foo", and that second MapElement contains
/// Another Element at key "bar", the identifier for that last
/// element from the first is "foo/bar".
///
/// @param identifier The identifier of the element to find
/// @return The ElementPtr at the given identifier. Returns a
/// null ElementPtr if it is not found, which can be checked with
/// Element::is_null(ElementPtr e).
virtual ConstElementPtr find(const std::string& identifier) const;
/// See @c Element::find()
/// @param identifier The identifier of the element to find
/// @param t Reference to store the resulting ElementPtr, if found.
/// @return true if the element was found, false if not.
virtual bool find(const std::string& identifier, ConstElementPtr& t) const;
//@}
/// @name Factory functions
// TODO: should we move all factory functions to a different class
// so as not to burden the Element base with too many functions?
// and/or perhaps even to a separate header?
/// @name Direct factory functions
/// @brief These functions simply wrap the given data directly
/// in an Element object, and return a reference to it, in the form
/// of an @c ElementPtr.
/// These factory functions are exception-free (unless there is
/// no memory available, in which case bad_alloc is raised by the
/// underlying system).
/// (Note that that is different from an NullElement, which
/// represents an empty value, and is created with Element::create())
///
/// Notes: Read notes of IntElement definition about the use of
/// long long int, long int and int.
//@{
static ElementPtr create(const Position& pos = ZERO_POSITION());
static ElementPtr create(const long long int i,
const Position& pos = ZERO_POSITION());
static ElementPtr create(const isc::util::int128_t& i,
const Position& pos = ZERO_POSITION());
static ElementPtr create(const int i,
const Position& pos = ZERO_POSITION());
static ElementPtr create(const long int i,
const Position& pos = ZERO_POSITION());
static ElementPtr create(const uint32_t i,
const Position& pos = ZERO_POSITION());
static ElementPtr create(const double d,
const Position& pos = ZERO_POSITION());
static ElementPtr create(const bool b,
const Position& pos = ZERO_POSITION());
static ElementPtr create(const std::string& s,
const Position& pos = ZERO_POSITION());
// need both std:string and char *, since c++ will match
// bool before std::string when you pass it a char *
static ElementPtr create(const char *s,
const Position& pos = ZERO_POSITION());
/// @brief Creates an empty ListElement type ElementPtr.
///
/// @param pos A structure holding position of the data element value
/// in the configuration string. It is used for error logging purposes.
static ElementPtr createList(const Position& pos = ZERO_POSITION());
/// @brief Creates an empty MapElement type ElementPtr.
///
/// @param pos A structure holding position of the data element value
/// in the configuration string. It is used for error logging purposes.
static ElementPtr createMap(const Position& pos = ZERO_POSITION());
//@}
/// @name Compound factory functions
/// @brief These functions will parse the given string (JSON)
/// representation of a compound element. If there is a parse
/// error, an exception of the type isc::data::JSONError is thrown.
//@{
/// Creates an Element from the given JSON string
/// @param in The string to parse the element from
/// @param preproc specified whether preprocessing (e.g. comment removal)
/// should be performed
/// @return An ElementPtr that contains the element(s) specified
/// in the given string.
static ElementPtr fromJSON(const std::string& in, bool preproc = false);
/// Creates an Element from the given input stream containing JSON
/// formatted data.
///
/// @param in The string to parse the element from
/// @param preproc specified whether preprocessing (e.g. comment removal)
/// should be performed
/// @throw JSONError
/// @return An ElementPtr that contains the element(s) specified
/// in the given input stream.
static ElementPtr fromJSON(std::istream& in, bool preproc = false);
/// Creates an Element from the given input stream containing JSON
/// formatted data.
///
/// @param in The string to parse the element from
/// @param file_name specified input file name (used in error reporting)
/// @param preproc specified whether preprocessing (e.g. comment removal)
/// should be performed
/// @throw JSONError
/// @return An ElementPtr that contains the element(s) specified
/// in the given input stream.
/// @throw JSONError
static ElementPtr fromJSON(std::istream& in, const std::string& file_name,
bool preproc = false);
/// Creates an Element from the given input stream, where we keep
/// track of the location in the stream for error reporting.
///
/// @param in The string to parse the element from.
/// @param file The input file name.
/// @param line A reference to the int where the function keeps
/// track of the current line.
/// @param pos A reference to the int where the function keeps
/// track of the current position within the current line.
/// @throw JSONError
/// @return An ElementPtr that contains the element(s) specified
/// in the given input stream.
// make this one private?
/// @throw JSONError
static ElementPtr fromJSON(std::istream& in, const std::string& file,
int& line, int &pos);
/// Reads contents of specified file and interprets it as JSON.
///
/// @param file_name name of the file to read
/// @param preproc specified whether preprocessing (e.g. comment removal)
/// should be performed
/// @return An ElementPtr that contains the element(s) specified
/// if the given file.
static ElementPtr fromJSONFile(const std::string& file_name,
bool preproc = false);
//@}
/// @name Type name conversion functions
/// Returns the name of the given type as a string
///
/// @param type The type to return the name of
/// @return The name of the type, or "unknown" if the type
/// is not known.
static std::string typeToName(Element::types type);
/// Converts the string to the corresponding type
/// Throws a TypeError if the name is unknown.
///
/// @param type_name The name to get the type of
/// @return the corresponding type value
static Element::types nameToType(const std::string& type_name);
/// @brief input text preprocessor
///
/// This method performs preprocessing of the input stream (which is
/// expected to contain a text version of to be parsed JSON). For now the
/// sole supported operation is bash-style (line starting with #) comment
/// removal, but it will be extended later to cover more cases (C, C++ style
/// comments, file inclusions, maybe macro replacements?).
///
/// This method processes the whole input stream. It reads all contents of
/// the input stream, filters the content and returns the result in a
/// different stream.
///
/// @param in input stream to be preprocessed
/// @param out output stream (filtered content will be written here)
static void preprocess(std::istream& in, std::stringstream& out);
/// @name Wire format factory functions
/// These function pparse the wireformat at the given stringstream
/// (of the given length). If there is a parse error an exception
/// of the type isc::cc::DecodeError is raised.
//@{
/// Creates an Element from the wire format in the given
/// stringstream of the given length.
/// Since the wire format is JSON, this is the same as
/// fromJSON, and could be removed.
///
/// @param in The input stringstream.
/// @param length The length of the wireformat data in the stream
/// @return ElementPtr with the data that is parsed.
static ElementPtr fromWire(std::stringstream& in, int length);
/// Creates an Element from the wire format in the given string
/// Since the wire format is JSON, this is the same as
/// fromJSON, and could be removed.
///
/// @param s The input string
/// @return ElementPtr with the data that is parsed.
static ElementPtr fromWire(const std::string& s);
//@}
/// @brief Remove all empty maps and lists from this Element and its
/// descendants.
void removeEmptyContainersRecursively() {
if (type_ == list || type_ == map) {
size_t s(size());
for (size_t i = 0; i < s; ++i) {
// Get child.
ElementPtr child;
if (type_ == list) {
child = getNonConst(i);
} else if (type_ == map) {
std::string const key(get(i)->stringValue());
// The ElementPtr - ConstElementPtr disparity between
// ListElement and MapElement is forcing a const cast here.
// It's undefined behavior to modify it after const casting.
// The options are limited. I've tried templating, moving
// this function from a member function to free-standing and
// taking the Element template as argument. I've tried
// making it a virtual function with overridden
// implementations in ListElement and MapElement. Nothing
// works.
child = boost::const_pointer_cast<Element>(get(key));
}
// Makes no sense to continue for non-container children.
if (child->getType() != list && child->getType() != map) {
continue;
}
// Recurse if not empty.
if (!child->empty()){
child->removeEmptyContainersRecursively();
}
// When returning from recursion, remove if empty.
if (child->empty()) {
remove(i);
--i;
--s;
}
}
}
}
};
/// Notes: IntElement type is changed to int64_t.
/// Due to C++ problems on overloading and automatic type conversion,
/// (C++ tries to convert integer type values and reference/pointer
/// if value types do not match exactly)
/// We decided the storage as int64_t,
/// three (long long, long, int) override function definitions
/// and cast int/long/long long to int64_t via long long.
/// Therefore, call by value methods (create, setValue) have three
/// (int,long,long long) definitions. Others use int64_t.
///
class IntElement : public Element {
int64_t i;
public:
IntElement(int64_t v, const Position& pos = ZERO_POSITION())
: Element(integer, pos), i(v) { }
int64_t intValue() const { return (i); }
using Element::getValue;
bool getValue(int64_t& t) const { t = i; return (true); }
using Element::setValue;
bool setValue(long long int v) { i = v; return (true); }
void toJSON(std::ostream& ss) const;
bool equals(const Element& other) const;
};
/// @brief Wrapper over int128_t
class BigIntElement : public Element {
using int128_t = isc::util::int128_t;
using Element::getValue;
using Element::setValue;
public:
/// @brief Constructor
BigIntElement(const int128_t& v, const Position& pos = ZERO_POSITION())
: Element(bigint, pos), i_(v) {
}
/// @brief Retrieve the underlying big integer value.
///
/// @return the underlying value
int128_t bigIntValue() const override {
return (i_);
}
/// @brief Sets the underlying big integer value.
///
/// @return true for no reason
bool setValue(const int128_t& v) override {
i_ = v;
return (true);
}
/// @brief Converts the Element to JSON format and appends it to the given
/// stringstream.
void toJSON(std::ostream& ss) const override;
/// @brief Checks whether the other Element is equal.
///
/// @return true if the other ElementPtr has the same value and the same
/// type (or a different and compatible type), false otherwise.
bool equals(const Element& other) const override;
private:
/// @brief the underlying stored value
int128_t i_;
};
class DoubleElement : public Element {
double d;
public:
DoubleElement(double v, const Position& pos = ZERO_POSITION())
: Element(real, pos), d(v) {};
double doubleValue() const { return (d); }
using Element::getValue;
bool getValue(double& t) const { t = d; return (true); }
using Element::setValue;
bool setValue(const double v) { d = v; return (true); }
void toJSON(std::ostream& ss) const;
bool equals(const Element& other) const;
};
class BoolElement : public Element {
bool b;
public:
BoolElement(const bool v, const Position& pos = ZERO_POSITION())
: Element(boolean, pos), b(v) {};
bool boolValue() const { return (b); }
using Element::getValue;
bool getValue(bool& t) const { t = b; return (true); }
using Element::setValue;
bool setValue(const bool v) { b = v; return (true); }
void toJSON(std::ostream& ss) const;
bool equals(const Element& other) const;
};
class NullElement : public Element {
public:
NullElement(const Position& pos = ZERO_POSITION())
: Element(null, pos) {};
void toJSON(std::ostream& ss) const;
bool equals(const Element& other) const;
};
class StringElement : public Element {
std::string s;
public:
StringElement(std::string v, const Position& pos = ZERO_POSITION())
: Element(string, pos), s(v) {};
std::string stringValue() const { return (s); }
using Element::getValue;
bool getValue(std::string& t) const { t = s; return (true); }
using Element::setValue;
bool setValue(const std::string& v) { s = v; return (true); }
void toJSON(std::ostream& ss) const;
bool equals(const Element& other) const;
};
class ListElement : public Element {
std::vector<ElementPtr> l;
public:
ListElement(const Position& pos = ZERO_POSITION())
: Element(list, pos) {}
const std::vector<ElementPtr>& listValue() const { return (l); }
using Element::getValue;
bool getValue(std::vector<ElementPtr>& t) const {
t = l;
return (true);
}
using Element::setValue;
bool setValue(const std::vector<ElementPtr>& v) {
l = v;
return (true);
}
using Element::get;
ConstElementPtr get(int i) const { return (l.at(i)); }
ElementPtr getNonConst(int i) const { return (l.at(i)); }
using Element::set;
void set(size_t i, ElementPtr e) {
l.at(i) = e;
}
void add(ElementPtr e) { l.push_back(e); };
using Element::remove;
void remove(int i) { l.erase(l.begin() + i); };
void toJSON(std::ostream& ss) const;
size_t size() const { return (l.size()); }
bool empty() const { return (l.empty()); }
bool equals(const Element& other) const;
/// @brief Sorts the elements inside the list.
///
/// The list must contain elements of the same type.
/// Call with the key by which you want to sort when the list contains maps.
/// Nested lists are not supported.
/// Call without a parameter when sorting any other type.
///
/// @param index the key by which you want to sort when the list contains
/// maps
void sort(std::string const& index = std::string());
};
class MapElement : public Element {
std::map<std::string, ConstElementPtr> m;
public:
MapElement(const Position& pos = ZERO_POSITION()) : Element(map, pos) {}
// @todo should we have direct iterators instead of exposing the std::map
// here?
const std::map<std::string, ConstElementPtr>& mapValue() const override {
return (m);
}
using Element::getValue;
bool getValue(std::map<std::string, ConstElementPtr>& t) const override {
t = m;
return (true);
}
using Element::setValue;
bool setValue(const std::map<std::string, ConstElementPtr>& v) override {
m = v;
return (true);
}
using Element::get;
ConstElementPtr get(const std::string& s) const override {
auto found = m.find(s);
return (found != m.end() ? found->second : ConstElementPtr());
}
/// @brief Get the i-th element in the map.
///
/// Useful when required to iterate with an index.
///
/// @param i the position of the element you want to return
/// @return the element at position i
ConstElementPtr get(int const i) const override {
auto it(m.begin());
std::advance(it, i);
return create(it->first);
}
using Element::set;
void set(const std::string& key, ConstElementPtr value) override;
using Element::remove;
void remove(const std::string& s) override { m.erase(s); }
/// @brief Remove the i-th element from the map.
///
/// @param i the position of the element you want to remove
void remove(int const i) override {
auto it(m.begin());
std::advance(it, i);
m.erase(it);
}
bool contains(const std::string& s) const override {
return (m.find(s) != m.end());
}
void toJSON(std::ostream& ss) const override;
// we should name the two finds better...
// find the element at id; raises TypeError if one of the
// elements at path except the one we're looking for is not a
// mapelement.
// returns an empty element if the item could not be found
ConstElementPtr find(const std::string& id) const override;
// find the Element at 'id', and store the element pointer in t
// returns true if found, or false if not found (either because
// it doesn't exist or one of the elements in the path is not
// a MapElement)
bool find(const std::string& id, ConstElementPtr& t) const override;
/// @brief Returns number of stored elements
///
/// @return number of elements.
size_t size() const override {
return (m.size());
}
bool equals(const Element& other) const override;
bool empty() const override { return (m.empty()); }
};
/// Checks whether the given ElementPtr is a NULL pointer
/// @param p The ElementPtr to check
/// @return true if it is NULL, false if not.
bool isNull(ConstElementPtr p);
///
/// @brief Remove all values from the first ElementPtr that are
/// equal in the second. Both ElementPtrs MUST be MapElements
/// The use for this function is to end up with a MapElement that
/// only contains new and changed values (for ModuleCCSession and
/// configuration update handlers)
/// Raises a TypeError if a or b are not MapElements
void removeIdentical(ElementPtr a, ConstElementPtr b);
/// @brief Create a new ElementPtr from the first ElementPtr, removing all
/// values that are equal in the second. Both ElementPtrs MUST be MapElements.
/// The returned ElementPtr will be a MapElement that only contains new and
/// changed values (for ModuleCCSession and configuration update handlers).
/// Raises a TypeError if a or b are not MapElements
ConstElementPtr removeIdentical(ConstElementPtr a, ConstElementPtr b);
/// @brief Merges the data from other into element. (on the first level). Both
/// elements must be MapElements. Every string, value pair in other is copied
/// into element (the ElementPtr of value is copied, this is not a new object)
/// Unless the value is a NullElement, in which case the key is removed from
/// element, rather than setting the value to the given NullElement.
/// This way, we can remove values from for instance maps with configuration
/// data (which would then result in reverting back to the default).
/// Raises a TypeError if either ElementPtr is not a MapElement
void merge(ElementPtr element, ConstElementPtr other);
/// @brief Function used to check if two MapElements refer to the same
/// configuration data. It can check if the two MapElements have the same or
/// have equivalent value for some members.
/// e.g.
/// (
/// left->get("prefix")->stringValue() == right->get("prefix")->stringValue() &&
/// left->get("prefix-len")->intValue() == right->get("prefix-len")->intValue() &&
/// left->get("delegated-len")->intValue() == right->get("delegated-len")->intValue()
/// )
typedef std::function<bool (ElementPtr&, ElementPtr&)> MatchTestFunc;
/// @brief Function used to check if the data provided for the element contains
/// only information used for identification, or it contains extra useful data.
typedef std::function<bool (ElementPtr&)> NoDataTestFunc;
/// @brief Function used to check if the key is used for identification
typedef std::function<bool (const std::string&)> IsKeyTestFunc;
/// @brief Structure holding the test functions used to traverse the element
/// hierarchy.
struct HierarchyTraversalTest {
MatchTestFunc match_;
NoDataTestFunc no_data_;
IsKeyTestFunc is_key_;
};
/// @brief Mapping between a container name and functions used to match elements
/// inside the container.
typedef std::map<std::string, HierarchyTraversalTest> FunctionMap;
/// @brief Hierarchy descriptor of the containers in a specific Element
/// hierarchy tree. The position inside the vector indicates the level at which
/// the respective containers are located.
///
/// e.g.
/// {
/// { { "pools", { ... , ... } }, { "pd-pools", { ... , ... } }, { "option-data", { ... , ... } } },
/// { { "option-data", { ... , ... } } }
/// }
/// At first subnet level the 'pools', 'pd-pools' and 'option-data' containers
/// can be found.
/// At second subnet level the 'option-data' container can be found
/// (obviously only inside 'pools' and 'pd-pools' containers).
typedef std::vector<FunctionMap> HierarchyDescriptor;
/// @brief Merges the diff data by adding the missing elements from 'other'
/// to 'element' (recursively). Both elements must be the same Element type.
/// Raises a TypeError if elements are not the same Element type.
/// @note
/// for non map and list elements the values are updated with the new values
/// for maps:
/// - non map and list elements are added/updated with the new values
/// - list and map elements are processed recursively
/// for lists:
/// - regardless of the element type, all elements from 'other' are added to
/// 'element'
///
/// @param element The element to which new data is added.
/// @param other The element containing the data which needs to be added.
/// @param hierarchy The hierarchy describing the elements relations and
/// identification keys.
/// @param key The container holding the current element.
/// @param idx The level inside the hierarchy the current element is located.
void mergeDiffAdd(ElementPtr& element, ElementPtr& other,
HierarchyDescriptor& hierarchy, std::string key,
size_t idx = 0);
/// @brief Merges the diff data by removing the data present in 'other' from
/// 'element' (recursively). Both elements must be the same Element type.
/// Raises a TypeError if elements are not the same Element type.
/// for non map and list elements the values are set to NullElement
/// for maps:
/// - non map and list elements are removed from the map
/// - list and map elements are processed recursively
/// for lists:
/// - regardless of the element type, all elements from 'other' matching
/// elements in 'element' are removed
///
/// @param element The element from which new data is removed.
/// @param other The element containing the data which needs to be removed.
/// @param hierarchy The hierarchy describing the elements relations and
/// identification keys.
/// @param key The container holding the current element.
/// @param idx The level inside the hierarchy the current element is located.
void mergeDiffDel(ElementPtr& element, ElementPtr& other,
HierarchyDescriptor& hierarchy, std::string key,
size_t idx = 0);
/// @brief Extends data by adding the specified 'extension' elements from
/// 'other' inside the 'container' element (recursively). Both elements must be
/// the same Element type.
/// Raises a TypeError if elements are not the same Element type.
///
/// @param container The container holding the data that must be extended.
/// @param extension The name of the element that contains the data that must be
/// added (if not already present) in order to extend the initial data.
/// @param element The element from which new data is added.
/// @param other The element containing the data which needs to be added.
/// @param hierarchy The hierarchy describing the elements relations and
/// identification keys.
/// @param key The container holding the current element.
/// @param idx The level inside the hierarchy the current element is located.
/// @param alter The flag which indicates if the current element should be
/// updated.
void extend(const std::string& container, const std::string& extension,
ElementPtr& element, ElementPtr& other,
HierarchyDescriptor& hierarchy, std::string key, size_t idx = 0,
bool alter = false);
/// @brief Copy the data up to a nesting level.
///
/// The copy is a deep copy so nothing is shared if it is not
/// under the given nesting level.
///
/// @param from the pointer to the element to copy
/// @param level nesting level (default is 100, 0 means shallow copy,
/// negative means outbound and perhaps looping forever).
/// @return a pointer to a fresh copy
/// @throw raises a BadValue is a null pointer occurs.
ElementPtr copy(ConstElementPtr from, int level = 100);
/// @brief Compares the data with other using unordered lists
///
/// This comparison function handles lists (JSON arrays) as
/// unordered multi sets (multi means an item can occurs more
/// than once as soon as it occurs the same number of times).
bool isEquivalent(ConstElementPtr a, ConstElementPtr b);
/// @brief Pretty prints the data into stream.
///
/// This operator converts the @c ConstElementPtr into a string and
/// inserts it into the output stream @c out with an initial
/// indentation @c indent and add at each level @c step spaces.
/// For maps if there is a comment property it is printed first.
///
/// @param element A @c ConstElementPtr to pretty print
/// @param out A @c std::ostream on which the print operation is performed
/// @param indent An initial number of spaces to add each new line
/// @param step A number of spaces to add to indentation at a new level
void prettyPrint(ConstElementPtr element, std::ostream& out,
unsigned indent = 0, unsigned step = 2);
/// @brief Pretty prints the data into string
///
/// This operator converts the @c ConstElementPtr into a string with
/// an initial indentation @c indent and add at each level @c step spaces.
/// For maps if there is a comment property it is printed first.
///
/// @param element A @c ConstElementPtr to pretty print
/// @param indent An initial number of spaces to add each new line
/// @param step A number of spaces to add to indentation at a new level
/// @return a string where element was pretty printed
std::string prettyPrint(ConstElementPtr element,
unsigned indent = 0, unsigned step = 2);
/// @brief Insert Element::Position as a string into stream.
///
/// This operator converts the @c Element::Position into a string and
/// inserts it into the output stream @c out.
///
/// @param out A @c std::ostream object on which the insertion operation is
/// performed.
/// @param pos The @c Element::Position structure to insert.
/// @return A reference to the same @c std::ostream object referenced by
/// parameter @c out after the insertion operation.
std::ostream& operator<<(std::ostream& out, const Element::Position& pos);
/// @brief Insert the Element as a string into stream.
///
/// This method converts the @c ElementPtr into a string with
/// @c Element::str() and inserts it into the
/// output stream @c out.
///
/// This function overloads the global operator<< to behave as described in
/// ostream::operator<< but applied to @c ElementPtr objects.
///
/// @param out A @c std::ostream object on which the insertion operation is
/// performed.
/// @param e The @c ElementPtr object to insert.
/// @return A reference to the same @c std::ostream object referenced by
/// parameter @c out after the insertion operation.
std::ostream& operator<<(std::ostream& out, const Element& e);
bool operator==(const Element& a, const Element& b);
bool operator!=(const Element& a, const Element& b);
bool operator<(const Element& a, const Element& b);
} // namespace data
} // namespace isc
#endif // ISC_DATA_H
Mini Shell