Kea: Element Class Reference

| Kea 3.0.3-git

Element Class Referenceabstract

The `Element` class represents a piece of data, used by the command channel and configuration parts. More...

`#include <data.h>`

Inheritance diagram for Element:
[legend]

## Classes
struct | Position
| Represents the position of the data element within a configuration string. More...

## Public Types
enum | types : int { integer = 0 , real = 1 , boolean = 2 , null = 3 , string = 4 , bigint = 5 , list = 6 , map = 7 , any = 8 }
| The types that an Element can hold. More...

## Public Member Functions
virtual | ~Element ()
const Position & | getPosition () const
| Returns position where the data element's value starts in a configuration string.
types | getType () const
std::string | str () const
| Returns a string representing the Element and all its child elements.
std::string | toWire () const
| Returns the wireformat for the Element and all its child elements.
void | toWire (std::ostream &out) const
| Appends the wireformat for the Element to the stream.
pure virtuals, every derived class must implement these.
virtual bool | equals (const Element &other, unsigned level=MAX_NESTING_LEVEL) const=0
| Test equality.
virtual void | toJSON (std::ostream &ss, unsigned level=MAX_NESTING_LEVEL) const=0
| Converts the Element to JSON format and appends it to the given output stream.
Type-specific getters
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
| Return the integer value.
virtual isc::util::int128_t | bigIntValue () const
| Return the big integer value.
virtual double | doubleValue () const
| Return the double value.
virtual bool | boolValue () const
| Return the boolean value.
virtual std::string | stringValue () const
| Return the string value.
virtual const std::vector< ElementPtr > & | listValue () const
| Return the list value.
virtual const std::map< std::string, ConstElementPtr > & | mapValue () const
| Return the map value.
Exception-safe getters
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
| Get the integer value.
virtual bool | getValue (double &t) const
| Get the double value.
virtual bool | getValue (bool &t) const
| Get the boolean value.
virtual bool | getValue (std::string &t) const
| Get the string value.
virtual bool | getValue (std::vector< ElementPtr > &t) const
| Get the list value.
virtual bool | getValue (std::map< std::string, ConstElementPtr > &t) const
| Get the map value.
Exception-safe setters.
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)
| Set the integer value.
virtual bool | setValue (const isc::util::int128_t &v)
| Set the big integer value.
virtual bool | setValue (const double v)
| Set the double value.
virtual bool | setValue (const bool t)
| Set the boolean value.
virtual bool | setValue (const std::string &v)
| Set the string value.
virtual bool | setValue (const std::vector< ElementPtr > &v)
| Set the list value.
virtual bool | setValue (const std::map< std::string, ConstElementPtr > &v)
| Set the map value.
bool | setValue (const long int i)
| Set the integer value (long int overload).
bool | setValue (const int i)
| Set the integer value (int overload).
ListElement functions.
If the Element on which these functions are called are not an instance of ListElement, a TypeError exception is thrown.
virtual ConstElementPtr | get (const int i) const
| Returns the ElementPtr at the given index.
virtual ElementPtr | getNonConst (const int i) const
| returns element as non-const pointer.
virtual void | set (const size_t i, ElementPtr element)
| Sets the ElementPtr at the given index.
virtual void | add (ElementPtr element)
| Adds an ElementPtr to the list.
virtual void | remove (const int i)
| Removes the element at the given position.
virtual size_t | size () const
| Returns the number of elements in the list.
virtual bool | empty () const
| Return true if there are no elements in the list.
MapElement functions
If the Element on which these functions are called are not an instance of MapElement, a TypeError exception is thrown.
virtual ConstElementPtr | get (const std::string &name) const
| Returns the ElementPtr at the given key.
virtual void | set (const std::string &name, ConstElementPtr element)
| Sets the ElementPtr at the given key.
virtual void | remove (const std::string &name)
| Remove the ElementPtr at the given key.
virtual bool | contains (const std::string &name) const
| Checks if there is data at the given key.
virtual ConstElementPtr | find (const std::string &identifier) const
| Recursively finds any data at the given identifier.
virtual bool | find (const std::string &identifier, ConstElementPtr &t) const
| See `Element::find()`.

## Static Public Member Functions
static const Position & | ZERO_POSITION ()
| Returns `Position` object with line_ and pos_ set to 0, and with an empty file name.
Direct factory functions
These functions simply wrap the given data directly in an Element object, and return a reference to it, in the form of an `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())
| Create a NullElement.
static ElementPtr | create (const long long int i, const Position &pos=ZERO_POSITION())
| Create an IntElement.
static ElementPtr | create (const int i, const Position &pos=ZERO_POSITION())
| Create an IntElement (int overload).
static ElementPtr | create (const long int i, const Position &pos=ZERO_POSITION())
| Create an IntElement (long int overload).
static ElementPtr | create (const uint32_t i, const Position &pos=ZERO_POSITION())
| Create an IntElement (int32_t overload).
static ElementPtr | create (const isc::util::int128_t &i, const Position &pos=ZERO_POSITION())
| Create a BigIntElement.
static ElementPtr | create (const double d, const Position &pos=ZERO_POSITION())
| Create a DoubleElement.
static ElementPtr | create (const bool b, const Position &pos=ZERO_POSITION())
| Create a BoolElement.
static ElementPtr | create (const std::string &s, const Position &pos=ZERO_POSITION())
| Create a StringElement.
static ElementPtr | create (const char *s, const Position &pos=ZERO_POSITION())
| Create a StringElement (char* overload).
static ElementPtr | createList (const Position &pos=ZERO_POSITION())
| Creates an empty ListElement type ElementPtr.
static ElementPtr | createMap (const Position &pos=ZERO_POSITION())
| Creates an empty MapElement type ElementPtr.
Compound factory functions
static ElementPtr | fromJSON (const std::string &in, bool preproc=false)
| These functions will parse the given string (JSON) representation of a compound element.
static ElementPtr | fromJSON (std::istream &in, bool preproc=false)
| Creates an Element from the given input stream containing JSON formatted data.
static ElementPtr | fromJSON (std::istream &in, const std::string &file_name, bool preproc=false)
| Creates an Element from the given input stream containing JSON formatted data.
static ElementPtr | fromJSON (std::istream &in, const std::string &file, int &line, int &pos, unsigned level=MAX_NESTING_LEVEL)
| Creates an Element from the given input stream, where we keep track of the location in the stream for error reporting.
static ElementPtr | fromJSONFile (const std::string &file_name, bool preproc=false)
| Reads contents of specified file and interprets it as JSON.
Type name conversion functions.
static std::string | typeToName (Element::types type)
| Returns the name of the given type as a string.
static Element::types | nameToType (const std::string &type_name)
| Converts the string to the corresponding type Throws a TypeError if the name is unknown.
static void | preprocess (std::istream &in, std::stringstream &out)
| input text preprocessor.

## Static Public Attributes
static constexpr unsigned | MAX_NESTING_LEVEL = 100U
| Maximum nesting level of Element objects.

## Protected Member Functions
| Element (types t, const Position &pos=ZERO_POSITION())
| Constructor.

## Wire format factory functions
static ElementPtr | fromWire (std::stringstream &in, int length)
| These function parse the wireformat at the given stringstream (of the given length).
static ElementPtr | fromWire (const std::string &s)
| Creates an Element from the wire format in the given string.
void | removeEmptyContainersRecursively (unsigned level=MAX_NESTING_LEVEL)
| Remove all empty maps and lists from this Element and its descendants.

## Detailed Description

The `Element` class represents a piece of data, used by the command channel and configuration parts.

An `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 `ElementPtr`, which can be created using the factory functions `Element::create()` and `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 `TypeError` for functions that are not supported for the type in question.

Definition at line 73 of file data.h.

## Member Enumeration Documentation

## ◆ types

enum isc::data::Element::types : int

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.

Enumerator
integer |
real |
boolean |
null |
string |
bigint |
list |
map |
any |

Definition at line 152 of file data.h.

## Constructor & Destructor Documentation

## ◆ Element()

isc::data::Element::Element | ( | types | t,
|  | const Position & | pos = ZERO_POSITION() )
| inlineprotected

Constructor.

Parameters

  t | Element type.
  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.

Definition at line 181 of file data.h.

## ◆ ~Element()

virtual isc::data::Element::~Element | ( |  | ) |
| inlinevirtual

Definition at line 188 of file data.h.

## Member Function Documentation

## ◆ add()

void isc::data::Element::add | ( | ElementPtr | element | ) |
| virtual

Adds an ElementPtr to the list.

Parameters

  element | The ElementPtr to add

Definition at line 203 of file data.cc.

## ◆ bigIntValue()

virtual isc::util::int128_t isc::data::Element::bigIntValue | ( |  | ) | const
| inlinevirtual

Return the big integer value.

Definition at line 280 of file data.h.

## ◆ boolValue()

virtual bool isc::data::Element::boolValue | ( |  | ) | const
| inlinevirtual

Return the boolean value.

Definition at line 290 of file data.h.

## ◆ contains()

bool isc::data::Element::contains | ( | const std::string & | name | ) | const
| virtual

Checks if there is data at the given key.

Parameters

  name | The key of the Element checked for existence

Returns
  true if there is data at the key, false if not.

Definition at line 238 of file data.cc.

## ◆ create() [1/10]

ElementPtr isc::data::Element::create | ( | const bool | b,
|  | const Position & | pos = ZERO_POSITION() )
| static

Create a BoolElement.

Parameters

  b | The boolean.
  pos | The position.

Returns
  The BoolElement with the argument at the position.

Definition at line 334 of file data.cc.

## ◆ create() [2/10]

ElementPtr isc::data::Element::create | ( | const char * | s,
|  | const Position & | pos = ZERO_POSITION() )
| static

Create a StringElement (char* overload).

Parameters

  s | The string.
  pos | The position.

Returns
  The StringElement with the argument at the position.

Definition at line 344 of file data.cc.

## ◆ create() [3/10]

ElementPtr isc::data::Element::create | ( | const double | d,
|  | const Position & | pos = ZERO_POSITION() )
| static

Create a DoubleElement.

Parameters

  d | The double.
  pos | The position.

Returns
  The DoubleElement with the argument at the position.

Definition at line 329 of file data.cc.

## ◆ create() [4/10]

ElementPtr isc::data::Element::create | ( | const int | i,
|  | const Position & | pos = ZERO_POSITION() )
| static

Create an IntElement (int overload).

Parameters

  i | The integer.
  pos | The position.

Returns
  The IntElement with the argument at the position.

Definition at line 314 of file data.cc.

## ◆ create() [5/10]

ElementPtr isc::data::Element::create | ( | const isc::util::int128_t & | i,
|  | const Position & | pos = ZERO_POSITION() )
| static

Create a BigIntElement.

Parameters

  i | The big integer.
  pos | The position.

Returns
  The BigIntElement with the argument at the position.

Definition at line 309 of file data.cc.

## ◆ create() [6/10]

ElementPtr isc::data::Element::create | ( | const long int | i,
|  | const Position & | pos = ZERO_POSITION() )
| static

Create an IntElement (long int overload).

Parameters

  i | The integer.
  pos | The position.

Returns
  The IntElement with the argument at the position.

Definition at line 319 of file data.cc.

## ◆ create() [7/10]

ElementPtr isc::data::Element::create | ( | const long long int | i,
|  | const Position & | pos = ZERO_POSITION() )
| static

Create an IntElement.

Parameters

  i | The integer.
  pos | The position.

Returns
  The IntElement with the argument at the position.

Definition at line 304 of file data.cc.

## ◆ create() [8/10]

ElementPtr isc::data::Element::create | ( | const Position & | pos = ZERO_POSITION() | ) |
| static

Create a NullElement.

Parameters

  pos | The position.

Returns
  The NullElement at the position.

Definition at line 299 of file data.cc.

Referenced by isc::config::HttpCommandConfig::HttpCommandConfig(), isc::subnet_cmds::SubnetCmdsImpl::addNetwork(), isc::subnet_cmds::SubnetCmdsImpl::addSubnet(), isc::stat_cmds::LeaseStatCmdsImpl::addValueRow4(), isc::stat_cmds::LeaseStatCmdsImpl::addValueRow6(), isc::yang::AdaptorSubnet::assignID(), isc::host_cache::HostCache::cacheSizeHandler(), isc::yang::AdaptorPool::canonizePool(), isc::yang::Translator::checkAndSetUserContext(), isc::yang::Translator::checkAndStringifyAndSetLeaf(), isc::gss_tsig::GssTsigImpl::commandProcessed(), isc::ha::HAImpl::commandProcessed(), isc::process::DControllerBase::configGetHandler(), isc::process::DControllerBase::configHashGetHandler(), isc::process::DControllerBase::configWriteHandler(), isc::ha::CommandCreator::createDHCPDisable(), isc::ha::CommandCreator::createDHCPEnable(), isc::lease_cmds::LeaseCmdsImpl::createFailedLeaseMap(), isc::ha::CommandCreator::createHAReset(), isc::ha::CommandCreator::createHeartbeat(), isc::ha::CommandCreator::createLease4Delete(), isc::ha::CommandCreator::createLease4GetPage(), isc::ha::CommandCreator::createLease4Update(), isc::ha::CommandCreator::createLease6BulkApply(), isc::ha::CommandCreator::createLease6BulkApply(), isc::ha::CommandCreator::createLease6Delete(), isc::ha::CommandCreator::createLease6GetPage(), isc::ha::CommandCreator::createLease6Update(), isc::ha::CommandCreator::createMaintenanceNotify(), isc::stat_cmds::LeaseStatCmdsImpl::createResultSet(), isc::ha::CommandCreator::createSyncCompleteNotify(), isc::subnet_cmds::SubnetCmdsImpl::delNetwork(), isc::lease_cmds::BindingVariableMgr::evaluateVariables(), isc::config::CmdResponseCreator::filterCommand(), isc::class_cmds::ClassCmdsImpl::getClassList(), isc::subnet_cmds::SubnetCmdsImpl::getNetworkList(), isc::yang::TranslatorPdPool::getPdPoolIetf6(), isc::yang::TranslatorPdPool::getPdPoolKea(), isc::yang::TranslatorPool::getPoolKea(), isc::ha::CommunicationState::getReport(), isc::agent::CtrlAgentCommandMgr::handleCommand(), isc::config::HookedCommandMgr::handleCommand(), handleLease6Cmds(), isc::yang::Translator::initializeDeserializer(), isc::lease_cmds::LeaseCmdsImpl::leaseGetPageHandler(), isc::gss_tsig::GssTsigImpl::listHandler(), isc::agent::AgentSimpleParser::parse(), isc::d2::D2CfgMgr::parse(), isc::http::PostHttpRequestJson::parseBodyAsJson(), isc::ha::HAService::processHeartbeat(), isc::ha::HAService::processMaintenanceNotify(), isc::ha::HAService::processStatusGet(), isc::yang::AdaptorHost::quoteIdentifier(), isc::host_cmds::HostCmdsImpl::reservationGetAllHandler(), isc::host_cmds::HostCmdsImpl::reservationGetByAddressHandler(), isc::host_cmds::HostCmdsImpl::reservationGetByHostnameHandler(), isc::host_cmds::HostCmdsImpl::reservationGetByIdHandler(), isc::host_cmds::HostCmdsImpl::reservationGetHandler(), isc::host_cmds::HostCmdsImpl::reservationGetPageHandler(), isc::process::DControllerBase::serverTagGetHandler(), isc::yang::AdaptorOption::setCode(), isc::yang::TranslatorPdPool::setPdPoolIetf6(), isc::yang::TranslatorPdPool::setPdPoolKea(), isc::yang::TranslatorPool::setPoolIetf6(), isc::yang::AdaptorOption::setSpace(), isc::process::DControllerBase::statusGetHandler(), isc::subnet_cmds::SubnetCmdsImpl::subnetToElement(), isc::radius::RadiusAccess::terminate4Internal(), isc::radius::RadiusAccess::terminate6Internal(), isc::agent::CtrlAgentCfgContext::toElement(), isc::config::HttpCommandConfig::toElement(), isc::config::UnixCommandConfig::toElement(), isc::d2::D2CfgContext::toElement(), isc::d2::DdnsDomain::toElement(), isc::d2::DnsServerInfo::toElement(), isc::d2::TSIGKeyInfo::toElement(), isc::db::BackendSelector::toElement(), isc::db::Server::toElement(), isc::gss_tsig::DnsServer::toElement(), isc::gss_tsig::ManagedKey::toElement(), isc::hooks::HooksConfig::toElement(), isc::host_cache::toElement(), isc::http::BasicHttpAuthClient::toElement(), isc::http::BasicHttpAuthConfig::toElement(), isc::http::CfgHttpHeader::toElement(), isc::lease_cmds::BindingVariable::toElement(), isc::netconf::CfgControlSocket::toElement(), isc::netconf::CfgServer::toElement(), isc::process::ConfigBase::toElement(), isc::process::ConfigControlInfo::toElement(), isc::process::LoggingDestination::toElement(), isc::process::LoggingInfo::toElement(), isc::radius::AttrInt::toElement(), isc::radius::AttrIpAddr::toElement(), isc::radius::AttrIpv6Addr::toElement(), isc::radius::AttrIpv6Prefix::toElement(), isc::radius::AttrString::toElement(), isc::radius::CfgAttributes::toElement(), isc::radius::RadiusImpl::toElement(), isc::radius::Server::toElement(), isc::class_cmds::ClassCmdsImpl::updateClass(), isc::subnet_cmds::SubnetCmdsImpl::updateSubnet(), isc::ha::HAService::verifyAsyncResponse(), and isc::process::DControllerBase::versionGetHandler().

## ◆ create() [9/10]

ElementPtr isc::data::Element::create | ( | const std::string & | s,
|  | const Position & | pos = ZERO_POSITION() )
| static

Create a StringElement.

Parameters

  s | The string.
  pos | The position.

Returns
  The StringElement with the argument at the position.

Definition at line 339 of file data.cc.

## ◆ create() [10/10]

ElementPtr isc::data::Element::create | ( | const uint32_t | i,
|  | const Position & | pos = ZERO_POSITION() )
| static

Create an IntElement (int32_t overload).

Parameters

  i | The integer.
  pos | The position.

Returns
  The IntElement with the argument at the position.

Definition at line 324 of file data.cc.

## ◆ createList()

ElementPtr isc::data::Element::createList | ( | const Position & | pos = ZERO_POSITION() | ) |
| static

Creates an empty ListElement type ElementPtr.

Parameters

  pos | A structure holding position of the data element value in the configuration string. It is used for error logging purposes.

Definition at line 349 of file data.cc.

Referenced by isc::subnet_cmds::SubnetCmdsImpl::addNetwork(), isc::subnet_cmds::SubnetCmdsImpl::addSubnet(), isc::stat_cmds::LeaseStatCmdsImpl::addValueRow4(), isc::stat_cmds::LeaseStatCmdsImpl::addValueRow6(), isc::host_cache::HostCache::cacheGetByIdHandler(), isc::http::CfgHttpHeaderstoElement(), isc::ha::HAImpl::commandProcessed(), isc::ha::CommandCreator::createLease6BulkApply(), isc::ha::CommandCreator::createLease6BulkApply(), isc::stat_cmds::LeaseStatCmdsImpl::createResultSet(), isc::subnet_cmds::SubnetCmdsImpl::delNetwork(), isc::subnet_cmds::SubnetCmdsImpl::delSubnet(), isc::gss_tsig::GssTsigImpl::getAllHandler(), isc::class_cmds::ClassCmdsImpl::getClass(), isc::class_cmds::ClassCmdsImpl::getClassList(), isc::gss_tsig::GssTsigImpl::getHandler(), isc::yang::Translator::getItem(), isc::subnet_cmds::SubnetCmdsImpl::getNetwork(), isc::subnet_cmds::SubnetCmdsImpl::getNetworkList(), isc::ha::CommunicationState::getReport(), isc::subnet_cmds::SubnetCmdsImpl::getSubnet(), isc::subnet_cmds::SubnetCmdsImpl::getSubnetList(), isc::agent::CtrlAgentCommandMgr::handleCommand(), isc::config::HookedCommandMgr::handleCommand(), isc::lease_cmds::LeaseCmdsImpl::lease6BulkApplyHandler(), isc::lease_cmds::LeaseCmdsImpl::leaseGetAllHandler(), isc::lease_cmds::LeaseCmdsImpl::leaseGetByClientIdHandler(), isc::lease_cmds::LeaseCmdsImpl::leaseGetByDuidHandler(), isc::lease_cmds::LeaseCmdsImpl::leaseGetByHostnameHandler(), isc::lease_cmds::LeaseCmdsImpl::leaseGetByHwAddressHandler(), isc::lease_cmds::LeaseCmdsImpl::leaseGetPageHandler(), isc::gss_tsig::GssTsigImpl::listHandler(), isc::d2::D2SimpleParser::parse(), isc::agent::CtrlAgentCommandMgr::processCommand(), isc::ha::HAService::processHeartbeat(), isc::ha::HAService::processStatusGet(), isc::host_cmds::HostCmdsImpl::reservationGetAllHandler(), isc::host_cmds::HostCmdsImpl::reservationGetByAddressHandler(), isc::host_cmds::HostCmdsImpl::reservationGetByHostnameHandler(), isc::host_cmds::HostCmdsImpl::reservationGetByIdHandler(), isc::host_cmds::HostCmdsImpl::reservationGetPageHandler(), isc::yang::AdaptorConfig::sanitizeDatabase(), isc::d2::D2CfgContext::toElement(), isc::d2::DdnsDomain::toElement(), isc::d2::DdnsDomainListMgr::toElement(), isc::gss_tsig::DnsServer::toElement(), isc::hooks::HooksConfig::toElement(), isc::host_cache::HostCacheImpl::toElement(), isc::host_cache::toElement(), isc::http::BasicHttpAuthConfig::toElement(), isc::process::ConfigBase::toElement(), isc::process::ConfigControlInfo::toElement(), isc::process::LoggingInfo::toElement(), isc::radius::Attributes::toElement(), isc::radius::CfgAttributes::toElement(), isc::radius::RadiusImpl::toElement(), isc::radius::RadiusService::toElement(), isc::subnet_cmds::SubnetCmdsImpl::updateSubnet(), and isc::ha::HAService::verifyAsyncResponse().

## ◆ createMap()

ElementPtr isc::data::Element::createMap | ( | const Position & | pos = ZERO_POSITION() | ) |
| static

Creates an empty MapElement type ElementPtr.

Parameters

  pos | A structure holding position of the data element value in the configuration string. It is used for error logging purposes.

Definition at line 354 of file data.cc.

Referenced by addContext(), isc::subnet_cmds::SubnetCmdsImpl::addNetwork(), isc::subnet_cmds::SubnetCmdsImpl::addSubnet(), isc::host_cache::HostCache::cacheSizeHandler(), isc::ha::HAImpl::commandProcessed(), isc::process::DControllerBase::configHashGetHandler(), isc::process::DControllerBase::configWriteHandler(), isc::ha::CommandCreator::createDHCPDisable(), isc::ha::CommandCreator::createDHCPEnable(), isc::lease_cmds::LeaseCmdsImpl::createFailedLeaseMap(), isc::ha::CommandCreator::createHAReset(), isc::ha::CommandCreator::createHeartbeat(), isc::ha::CommandCreator::createLease4GetPage(), isc::ha::CommandCreator::createLease6BulkApply(), isc::ha::CommandCreator::createLease6BulkApply(), isc::ha::CommandCreator::createLease6GetPage(), isc::ha::CommandCreator::createMaintenanceNotify(), isc::stat_cmds::LeaseStatCmdsImpl::createResultSet(), isc::ha::CommandCreator::createSyncCompleteNotify(), isc::subnet_cmds::SubnetCmdsImpl::delNetwork(), isc::subnet_cmds::SubnetCmdsImpl::delSubnet(), isc::lease_cmds::BindingVariableMgr::evaluateVariables(), isc::config::CmdResponseCreator::filterCommand(), isc::stats::StatContext::getAll(), isc::gss_tsig::GssTsigImpl::getAllHandler(), isc::class_cmds::ClassCmdsImpl::getClass(), isc::yang::TranslatorClass::getClassKea(), isc::class_cmds::ClassCmdsImpl::getClassList(), isc::yang::TranslatorConfig::getConfigControlKea(), isc::yang::TranslatorConfig::getConfigIetf6(), isc::yang::TranslatorConfig::getConfigKea4(), isc::yang::TranslatorConfig::getConfigKea6(), isc::yang::Adaptor::getContext(), isc::yang::TranslatorControlSocket::getControlSocketAuthenticationClient(), isc::yang::TranslatorControlSocket::getControlSocketHttpHeader(), isc::yang::TranslatorControlSocket::getControlSocketKea(), isc::yang::TranslatorDatabase::getDatabaseKea(), isc::yang::TranslatorConfig::getDdnsKea(), isc::yang::TranslatorConfig::getExpiredKea(), isc::yang::TranslatorConfig::getHook(), isc::yang::TranslatorHost::getHostKea(), isc::yang::TranslatorConfig::getInterfacesKea(), isc::yang::TranslatorLogger::getLoggerKea(), isc::subnet_cmds::SubnetCmdsImpl::getNetwork(), isc::subnet_cmds::SubnetCmdsImpl::getNetworkList(), isc::yang::TranslatorOptionData::getOptionDataKea(), isc::yang::TranslatorOptionDef::getOptionDefKea(), isc::yang::TranslatorLogger::getOutputOption(), isc::yang::TranslatorPdPool::getPdPoolIetf6(), isc::yang::TranslatorPdPool::getPdPoolKea(), isc::yang::TranslatorPool::getPoolIetf6(), isc::yang::TranslatorPool::getPoolKea(), isc::ha::CommunicationState::getReport(), isc::yang::TranslatorConfig::getServerKeaDhcp4(), isc::yang::TranslatorConfig::getServerKeaDhcp6(), isc::yang::TranslatorConfig::getServerKeaDhcpCommon(), isc::yang::TranslatorSharedNetwork::getSharedNetworkKea(), isc::subnet_cmds::SubnetCmdsImpl::getSubnet(), isc::yang::TranslatorSubnet::getSubnetIetf6(), isc::yang::TranslatorSubnet::getSubnetKea(), isc::subnet_cmds::SubnetCmdsImpl::getSubnetList(), isc::lease_cmds::LeaseCmdsImpl::lease6BulkApplyHandler(), isc::lease_cmds::LeaseCmdsImpl::leaseGetAllHandler(), isc::lease_cmds::LeaseCmdsImpl::leaseGetByClientIdHandler(), isc::lease_cmds::LeaseCmdsImpl::leaseGetByDuidHandler(), isc::lease_cmds::LeaseCmdsImpl::leaseGetByHostnameHandler(), isc::lease_cmds::LeaseCmdsImpl::leaseGetByHwAddressHandler(), isc::lease_cmds::LeaseCmdsImpl::leaseGetPageHandler(), isc::gss_tsig::GssTsigImpl::listHandler(), isc::d2::D2CfgMgr::parse(), isc::host_cache::HCConfigParser::parse(), isc::lease_cmds::Lease4Parser::parse(), isc::lease_cmds::Lease6Parser::parse(), isc::ha::HAService::processHeartbeat(), isc::ha::HAService::processMaintenanceNotify(), isc::ha::HAService::processStatusGet(), isc::host_cmds::HostCmdsImpl::reservationGetAllHandler(), isc::host_cmds::HostCmdsImpl::reservationGetByAddressHandler(), isc::host_cmds::HostCmdsImpl::reservationGetByHostnameHandler(), isc::host_cmds::HostCmdsImpl::reservationGetByIdHandler(), isc::host_cmds::HostCmdsImpl::reservationGetPageHandler(), isc::process::DControllerBase::serverTagGetHandler(), isc::stat_cmds::LeaseStatCmdsImpl::statLease4GetHandler(), isc::stat_cmds::LeaseStatCmdsImpl::statLease6GetHandler(), isc::process::DControllerBase::statusGetHandler(), isc::subnet_cmds::SubnetCmdsImpl::subnetToElement(), isc::radius::RadiusAccess::terminate4Internal(), isc::radius::RadiusAccess::terminate6Internal(), isc::agent::CtrlAgentCfgContext::toElement(), isc::config::HttpCommandConfig::toElement(), isc::config::UnixCommandConfig::toElement(), isc::d2::D2CfgContext::toElement(), isc::d2::DdnsDomain::toElement(), isc::d2::DnsServerInfo::toElement(), isc::d2::TSIGKeyInfo::toElement(), isc::db::BackendSelector::toElement(), isc::db::Server::toElement(), isc::gss_tsig::DnsServer::toElement(), isc::gss_tsig::ManagedKey::toElement(), isc::hooks::HooksConfig::toElement(), isc::host_cache::toElement(), isc::http::BasicHttpAuthClient::toElement(), isc::http::BasicHttpAuthConfig::toElement(), isc::lease_cmds::BindingVariable::toElement(), isc::netconf::CfgControlSocket::toElement(), isc::netconf::CfgServer::toElement(), isc::netconf::NetconfConfig::toElement(), isc::process::ConfigBase::toElement(), isc::process::ConfigControlInfo::toElement(), isc::process::LoggingDestination::toElement(), isc::process::LoggingInfo::toElement(), isc::radius::AttrInt::toElement(), isc::radius::AttrIpAddr::toElement(), isc::radius::AttrIpv6Addr::toElement(), isc::radius::AttrIpv6Prefix::toElement(), isc::radius::AttrString::toElement(), isc::radius::CfgAttributes::toElement(), isc::radius::RadiusImpl::toElement(), isc::radius::RadiusService::toElement(), isc::radius::Server::toElement(), isc::subnet_cmds::SubnetCmdsImpl::updateSubnet(), isc::ha::HAService::verifyAsyncResponse(), and isc::process::DControllerBase::versionGetHandler().

## ◆ doubleValue()

virtual double isc::data::Element::doubleValue | ( |  | ) | const
| inlinevirtual

Return the double value.

Definition at line 285 of file data.h.

## ◆ empty()

bool isc::data::Element::empty | ( |  | ) | const
| virtual

Return true if there are no elements in the list.

Definition at line 218 of file data.cc.

## ◆ equals()

virtual bool isc::data::Element::equals | ( | const Element & | other,
|  | unsigned | level = MAX_NESTING_LEVEL ) const
| pure virtual

Test equality.

Parameters

  other | The other element to compare with.
  level | The maximum level of recursion.

Returns
  true if the other ElementPtr has the same value and the same type (or a different and compatible type), false otherwise.

Exceptions

  BadValue | when nesting depth is more than level.

## ◆ find() [1/2]

ConstElementPtr isc::data::Element::find | ( | const std::string & | identifier | ) | const
| virtual

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".

Parameters

  identifier | The identifier of the element to find

Returns
  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).

Definition at line 243 of file data.cc.

## ◆ find() [2/2]

bool isc::data::Element::find | ( | const std::string & | identifier,
|  | ConstElementPtr & | t ) const
| virtual

See `Element::find()`.

Parameters

  identifier | The identifier of the element to find
  t | Reference to store the resulting ElementPtr, if found.

Returns
  true if the element was found, false if not.

Definition at line 248 of file data.cc.

## ◆ fromJSON() [1/4]

ElementPtr isc::data::Element::fromJSON | ( | const std::string & | in,
|  | bool | preproc = false )
| static

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

Parameters

  in | The string to parse the element from
  preproc | specified whether preprocessing (e.g. comment removal) should be performed

Returns
  An ElementPtr that contains the element(s) specified in the given string.

Definition at line 859 of file data.cc.

Referenced by isc::yang::Translator::checkAndGetAndJsonifyLeaf(), isc::db::PgSqlExchange::getColumnValue(), isc::db::MySqlBinding::getJSON(), isc::yang::Translator::initializeDeserializer(), isc::http::HttpResponseJson::parseBodyAsJson(), isc::http::PostHttpRequestJson::parseBodyAsJson(), and isc::test::runToElementTest().

## ◆ fromJSON() [2/4]

ElementPtr isc::data::Element::fromJSON | ( | std::istream & | in,
|  | bool | preproc = false )
| static

Creates an Element from the given input stream containing JSON formatted data.

Parameters

  in | The string to parse the element from
  preproc | specified whether preprocessing (e.g. comment removal) should be performed

Exceptions

  JSONError |

Returns
  An ElementPtr that contains the element(s) specified in the given input stream.

Definition at line 762 of file data.cc.

## ◆ fromJSON() [3/4]

ElementPtr isc::data::Element::fromJSON | ( | std::istream & | in,
|  | const std::string & | file,
|  | int & | line,
|  | int & | pos,
|  | unsigned | level = MAX_NESTING_LEVEL )
| static

Creates an Element from the given input stream, where we keep track of the location in the stream for error reporting.

Parameters

  in | The string to parse the element from.
  file | The input file name.
  line | A reference to the int where the function keeps track of the current line.
  pos | A reference to the int where the function keeps track of the current position within the current line.
  level | The maximum level of recursion.

Returns
  An ElementPtr that contains the element(s) specified in the given input stream.

Exceptions

  JSONError |

Definition at line 786 of file data.cc.

## ◆ fromJSON() [4/4]

ElementPtr isc::data::Element::fromJSON | ( | std::istream & | in,
|  | const std::string & | file_name,
|  | bool | preproc = false )
| static

Creates an Element from the given input stream containing JSON formatted data.

Parameters

  in | The string to parse the element from
  file_name | specified input file name (used in error reporting)
  preproc | specified whether preprocessing (e.g. comment removal) should be performed

Exceptions

  JSONError |

Returns
  An ElementPtr that contains the element(s) specified in the given input stream.

Exceptions

  JSONError |

Definition at line 776 of file data.cc.

## ◆ fromJSONFile()

ElementPtr isc::data::Element::fromJSONFile | ( | const std::string & | file_name,
|  | bool | preproc = false )
| static

Reads contents of specified file and interprets it as JSON.

Parameters

  file_name | name of the file to read
  preproc | specified whether preprocessing (e.g. comment removal) should be performed

Returns
  An ElementPtr that contains the element(s) specified if the given file.

Definition at line 878 of file data.cc.

Referenced by isc::host_cache::HostCache::cacheLoadHandler(), and isc::process::DControllerBase::configFromFile().

## ◆ fromWire() [1/2]

ElementPtr isc::data::Element::fromWire | ( | const std::string & | s | ) |
| static

Creates an Element from the wire format in the given string.

Note
  : Since the wire format is JSON, this is the same as fromJSON, and could be removed.

Parameters

  s | The input string.

Returns
  ElementPtr with the data that is parsed.

Definition at line 1053 of file data.cc.

## ◆ fromWire() [2/2]

ElementPtr isc::data::Element::fromWire | ( | std::stringstream & | in,
|  | int | length )
| static

These function parse 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.

Note
  : Since the wire format is JSON, this is the same as fromJSON, and could be removed.

Parameters

  in | The input stringstream.
  length | The length of the wireformat data in the stream.

Returns
  ElementPtr with the data that is parsed.

Definition at line 1061 of file data.cc.

Referenced by isc::config::JSONFeed::toElement().

## ◆ get() [1/2]

ConstElementPtr isc::data::Element::get | ( | const int | i | ) | const
| virtual

Returns the ElementPtr at the given index.

If the index is out of bounds, this function throws an std::out_of_range exception.

Parameters

  i | The position of the ElementPtr to return

Returns
  specified element pointer.

Definition at line 188 of file data.cc.

## ◆ get() [2/2]

ConstElementPtr isc::data::Element::get | ( | const std::string & | name | ) | const
| virtual

Returns the ElementPtr at the given key.

Parameters

  name | The key of the Element to return

Returns
  The ElementPtr at the given key, or null if not present

Definition at line 223 of file data.cc.

## ◆ getNonConst()

ElementPtr isc::data::Element::getNonConst | ( | const int | i | ) | const
| virtual

returns element as non-const pointer.

Parameters

  i | The position of the ElementPtr to retrieve.

Returns
  specified element pointer.

Definition at line 193 of file data.cc.

## ◆ getPosition()

const Position & isc::data::Element::getPosition | ( |  | ) | const
| inline

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.

Returns
  The position.

Definition at line 201 of file data.h.

## ◆ getType()

types isc::data::Element::getType | ( |  | ) | const
| inline

Returns
  the type of this element.

Definition at line 191 of file data.h.

## ◆ getValue() [1/6]

bool isc::data::Element::getValue | ( | bool & | t | ) | const
| virtual

Get the boolean value.

Parameters

  t | The reference to the boolean.

Returns
  false.

Definition at line 133 of file data.cc.

## ◆ getValue() [2/6]

bool isc::data::Element::getValue | ( | double & | t | ) | const
| virtual

Get the double value.

Parameters

  t | The reference to the double.

Returns
  false.

Definition at line 128 of file data.cc.

## ◆ getValue() [3/6]

bool isc::data::Element::getValue | ( | int64_t & | t | ) | const
| virtual

Get the integer value.

Parameters

  t | The reference to the integer.

Returns
  false.

Definition at line 123 of file data.cc.

## ◆ getValue() [4/6]

bool isc::data::Element::getValue | ( | std::map< std::string, ConstElementPtr > & | t | ) | const
| virtual

Get the map value.

Parameters

  t | The reference to the map.

Returns
  false.

Definition at line 148 of file data.cc.

## ◆ getValue() [5/6]

bool isc::data::Element::getValue | ( | std::string & | t | ) | const
| virtual

Get the string value.

Parameters

  t | The reference to the string.

Returns
  false.

Definition at line 138 of file data.cc.

## ◆ getValue() [6/6]

bool isc::data::Element::getValue | ( | std::vector< ElementPtr > & | t | ) | const
| virtual

Get the list value.

Parameters

  t | The reference to the list.

Returns
  false.

Definition at line 143 of file data.cc.

## ◆ intValue()

virtual int64_t isc::data::Element::intValue | ( |  | ) | const
| inlinevirtual

Return the integer value.

Definition at line 275 of file data.h.

## ◆ listValue()

virtual const std::vector< ElementPtr > & isc::data::Element::listValue | ( |  | ) | const
| inlinevirtual

Return the list value.

Definition at line 300 of file data.h.

## ◆ mapValue()

virtual const std::map< std::string, ConstElementPtr > & isc::data::Element::mapValue | ( |  | ) | const
| inlinevirtual

Return the map value.

Definition at line 306 of file data.h.

## ◆ nameToType()

Element::types isc::data::Element::nameToType | ( | const std::string & | type_name | ) |
| static

Converts the string to the corresponding type Throws a TypeError if the name is unknown.

Parameters

  type_name | The name to get the type of.

Returns
  the corresponding type value

Definition at line 735 of file data.cc.

## ◆ preprocess()

void isc::data::Element::preprocess | ( | std::istream & | in,
|  | std::stringstream & | out )
| static

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.

Parameters

  in | input stream to be preprocessed.
  out | output stream (filtered content will be written here).

Definition at line 1752 of file data.cc.

## ◆ remove() [1/2]

void isc::data::Element::remove | ( | const int | i | ) |
| virtual

Removes the element at the given position.

If the index is out of nothing happens.

Parameters

  i | The index of the element to remove.

Definition at line 208 of file data.cc.

## ◆ remove() [2/2]

void isc::data::Element::remove | ( | const std::string & | name | ) |
| virtual

Remove the ElementPtr at the given key.

Parameters

  name | The key of the Element to remove

Definition at line 233 of file data.cc.

## ◆ removeEmptyContainersRecursively()

void isc::data::Element::removeEmptyContainersRecursively | ( | unsigned | level = MAX_NESTING_LEVEL | ) |

Remove all empty maps and lists from this Element and its descendants.

Parameters

  level | nesting level.

Definition at line 57 of file data.cc.

## ◆ set() [1/2]

void isc::data::Element::set | ( | const size_t | i,
|  | ElementPtr | element )
| virtual

Sets the ElementPtr at the given index.

If the index is out of bounds, this function throws an std::out_of_range exception.

Parameters

  i | The position of the ElementPtr to set
  element | The ElementPtr to set at the position

Definition at line 198 of file data.cc.

## ◆ set() [2/2]

void isc::data::Element::set | ( | const std::string & | name,
|  | ConstElementPtr | element )
| virtual

Sets the ElementPtr at the given key.

Parameters

  name | The key of the Element to set
  element | The ElementPtr to set at the given key.

Definition at line 228 of file data.cc.

## ◆ setValue() [1/9]

bool isc::data::Element::setValue | ( | const bool | t | ) |
| virtual

Set the boolean value.

Parameters

  t | The new boolean value.

Returns
  False.

Definition at line 168 of file data.cc.

## ◆ setValue() [2/9]

bool isc::data::Element::setValue | ( | const double | v | ) |
| virtual

Set the double value.

Parameters

  v | The new double value.

Returns
  False.

Definition at line 163 of file data.cc.

## ◆ setValue() [3/9]

bool isc::data::Element::setValue | ( | const int | i | ) |
| inline

Set the integer value (int overload).

Parameters

  i | The new integer value.

Returns
  True (and set the value) when the Element type is integer, false otherwise.

Definition at line 424 of file data.h.

## ◆ setValue() [4/9]

bool isc::data::Element::setValue | ( | const isc::util::int128_t & | v | ) |
| virtual

Set the big integer value.

Parameters

  v | The new big integer value.

Returns
  False.

Definition at line 158 of file data.cc.

## ◆ setValue() [5/9]

bool isc::data::Element::setValue | ( | const long int | i | ) |
| inline

Set the integer value (long int overload).

Parameters

  i | The new integer value.

Returns
  True (and set the value) when the Element type is integer, false otherwise.

Definition at line 415 of file data.h.

## ◆ setValue() [6/9]

bool isc::data::Element::setValue | ( | const long long int | v | ) |
| virtual

Set the integer value.

Parameters

  v | The new integer value.

Returns
  False.

Definition at line 153 of file data.cc.

## ◆ setValue() [7/9]

bool isc::data::Element::setValue | ( | const std::map< std::string, ConstElementPtr > & | v | ) |
| virtual

Set the map value.

Parameters

  v | The new map value.

Returns
  False.

Definition at line 183 of file data.cc.

## ◆ setValue() [8/9]

bool isc::data::Element::setValue | ( | const std::string & | v | ) |
| virtual

Set the string value.

Parameters

  v | The new string value.

Returns
  False.

Definition at line 173 of file data.cc.

## ◆ setValue() [9/9]

bool isc::data::Element::setValue | ( | const std::vector< ElementPtr > & | v | ) |
| virtual

Set the list value.

Parameters

  v | The new list value.

Returns
  False.

Definition at line 178 of file data.cc.

## ◆ size()

size_t isc::data::Element::size | ( |  | ) | const
| virtual

Returns the number of elements in the list.

Definition at line 213 of file data.cc.

## ◆ str()

std::string isc::data::Element::str | ( |  | ) | const

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. Based on toJSON.

Returns
  std::string containing the string representation.

Definition at line 104 of file data.cc.

## ◆ stringValue()

virtual std::string isc::data::Element::stringValue | ( |  | ) | const
| inlinevirtual

Return the string value.

Definition at line 295 of file data.h.

## ◆ toJSON()

virtual void isc::data::Element::toJSON | ( | std::ostream & | ss,
|  | unsigned | level = MAX_NESTING_LEVEL ) const
| pure virtual

Converts the Element to JSON format and appends it to the given output stream.

Parameters

  ss | The output stream where to append the JSON format.
  level | The maximum level of recursion.

Exceptions

  BadValue | when nesting depth is more than level.

## ◆ toWire() [1/2]

std::string isc::data::Element::toWire | ( |  | ) | const

Returns the wireformat for the Element and all its child elements.

Based on toJSON.

Returns
  std::string containing the element in wire format

Definition at line 111 of file data.cc.

## ◆ toWire() [2/2]

void isc::data::Element::toWire | ( | std::ostream & | out | ) | const

Appends the wireformat for the Element to the stream.

Parameters

  out | The output stream where to append the wireformat.

Definition at line 118 of file data.cc.

## ◆ typeToName()

std::string isc::data::Element::typeToName | ( | Element::types | type | ) |
| static

Returns the name of the given type as a string.

Parameters

  type | The type to return the name of.

Returns
  The name of the type, or "unknown" if the type is not known.

Definition at line 709 of file data.cc.

Referenced by load(), isc::radius::RadiusServiceParser::parse(), and isc::host_cmds::HostCmdsImpl::reservationUpdateHandler().

## ◆ ZERO_POSITION()

const Position & isc::data::Element::ZERO_POSITION | ( |  | ) |
| inlinestatic

Returns `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 `Element` objects. The returned value is static so as it is not created every time the function with the default position argument is called.

Definition at line 139 of file data.h.

## Member Data Documentation

## ◆ MAX_NESTING_LEVEL

unsigned isc::data::Element::MAX_NESTING_LEVEL = 100U
| staticconstexpr

Maximum nesting level of Element objects.

Many methods and functions perform a recursive walk on an element containing lists or/and maps. This recursion is limited to using an allowed level of nesting argument which is decremented at each recursive call until it reaches 0. This was extended to recursive parsing of a JSON text as stack overflows were reported with excessive recursion on specially crafted input. This constant is the default allowed level of nesting, its value is arbitrary (but enough for all realistic cases) and used before limiting recursion in all recursive methods/functions.

Definition at line 86 of file data.h.

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

- data.h
- data.cc