Kea: isc::config::JSONFeed Class Reference

| Kea 3.0.3-git

isc::config::JSONFeed Class Reference

State model for asynchronous read of data in JSON format. More...

`#include <json_feed.h>`

Inheritance diagram for isc::config::JSONFeed:
[legend]

## Static Public Attributes
States supported by the @ref JSONFeed
static const int | RECEIVE_START_ST = SM_DERIVED_STATE_MIN + 1
| State indicating a beginning of a feed.
static const int | WHITESPACE_BEFORE_JSON_ST = SM_DERIVED_STATE_MIN + 2
| Skipping whitespaces before actual JSON.
static const int | EOL_COMMENT_BEFORE_JSON_ST = SM_DERIVED_STATE_MIN + 3
| Skipping an end-of-line comment before actual JSON.
static const int | START_COMMENT_BEFORE_JSON_ST = SM_DERIVED_STATE_MIN + 4
| Starting one of the comments beginning with a slash before actual JSON.
static const int | C_COMMENT_BEFORE_JSON_ST = SM_DERIVED_STATE_MIN + 5
| Skipping a C style comment before actual JSON.
static const int | STOP_COMMENT_BEFORE_JSON_ST = SM_DERIVED_STATE_MIN + 6
| Stopping a C style comment before actual JSON.
static const int | JSON_START_ST = SM_DERIVED_STATE_MIN + 7
| Found first opening brace or square bracket.
static const int | INNER_JSON_ST = SM_DERIVED_STATE_MIN + 8
| Parsing JSON.
static const int | STRING_JSON_ST = SM_DERIVED_STATE_MIN + 9
| Parsing JSON string.
static const int | ESCAPE_JSON_ST = SM_DERIVED_STATE_MIN + 10
| JSON escape next character.
static const int | EOL_COMMENT_ST = SM_DERIVED_STATE_MIN + 11
| Skipping an end-of-line comment.
static const int | START_COMMENT_ST = SM_DERIVED_STATE_MIN + 12
| Starting one of the comments beginning with a slash.
static const int | C_COMMENT_ST = SM_DERIVED_STATE_MIN + 13
| Skipping a C style comment.
static const int | STOP_COMMENT_ST = SM_DERIVED_STATE_MIN + 14
| Stopping a C style comment.
static const int | JSON_END_ST = SM_DERIVED_STATE_MIN + 15
| Found last closing brace or square bracket.
static const int | FEED_OK_ST = SM_DERIVED_STATE_MIN + 100
| Found opening and closing brace or square bracket.
static const int | FEED_FAILED_ST = SM_DERIVED_STATE_MIN + 101
| Invalid syntax detected.
Static Public Attributes inherited from isc::util::StateModel
static const int | END_EVT = 2
| Event issued to end the model execution.
static const int | END_ST = 1
| Final state, all the state model has reached its conclusion.
static const int | FAIL_EVT = 3
| Event issued to abort the model execution.
static const int | NEW_ST = 0
| State that a state model is in immediately after construction.
static const int | NOP_EVT = 0
| Signifies that no event has occurred.
static const int | SM_DERIVED_EVENT_MIN = 11
| Value at which custom events in a derived class should begin.
static const int | SM_DERIVED_STATE_MIN = 11
| Value at which custom states in a derived class should begin.
static const int | START_EVT = 1
| Event issued to start the model execution.

## Events used during data processing.
static const int | DATA_READ_OK_EVT = SM_DERIVED_EVENT_MIN + 1
| Chunk of data successfully read and parsed.
static const int | NEED_MORE_DATA_EVT = SM_DERIVED_EVENT_MIN + 2
| Unable to proceed with parsing until new data is provided.
static const int | MORE_DATA_PROVIDED_EVT = SM_DERIVED_EVENT_MIN + 3
| New data provided and parsing should continue.
static const int | FEED_OK_EVT = SM_DERIVED_EVENT_MIN + 100
| Found opening brace and the matching closing brace.
static const int | FEED_FAILED_EVT = SM_DERIVED_EVENT_MIN + 101
| Invalid syntax detected.
| JSONFeed ()
| Constructor.
void | initModel ()
| Initializes state model.
void | poll ()
| Runs the model as long as data is available.
bool | needData () const
| Checks if the model needs additional data to continue.
bool | feedOk () const
| Checks if the data have been successfully processed.
std::string | getErrorMessage () const
| Returns error string when data processing has failed.
std::string | getProcessedText () const
| Returns the text parsed into the buffer.
data::ElementPtr | toElement () const
| Returns processed data as a structure of isc::data::Element objects.
void | postBuffer (const void *buf, const size_t buf_size)
| Receives additional data read from a data stream.

## Additional Inherited Members
Public Member Functions inherited from isc::util::StateModel
| StateModel ()
| Constructor.
virtual | ~StateModel ()
| Destructor.
bool | didModelFail () const
| Returns whether or not the model failed.
void | endModel ()
| Conducts a normal transition to the end of the model.
std::string | getContextStr () const
| Convenience method which returns a string rendition of the current state and next event.
unsigned int | getCurrState () const
| Fetches the model's current state.
std::string | getEventLabel (const int event) const
| Fetches the label associated with an event value.
unsigned int | getLastEvent () const
| Fetches the model's last event.
unsigned int | getNextEvent () const
| Fetches the model's next event.
std::string | getPrevContextStr () const
| Convenience method which returns a string rendition of the previous state and last event.
unsigned int | getPrevState () const
| Fetches the model's previous state.
std::string | getStateLabel (const int state) const
| Fetches the label associated with an state value.
bool | isModelDone () const
| Returns whether or not the model has finished execution.
bool | isModelNew () const
| Returns whether or not the model is new.
bool | isModelPaused () const
| Returns whether or not the model is paused.
bool | isModelRunning () const
| Returns whether or not the model is running.
bool | isModelWaiting () const
| Returns whether or not the model is waiting.
void | nopStateHandler ()
| An empty state handler.
virtual void | runModel (unsigned int event)
| Processes events through the state model.
void | startModel (const int start_state)
| Begins execution of the model.
void | unpauseModel ()
| Unpauses state model.
Protected Member Functions inherited from isc::util::StateModel
void | abortModel (const std::string &explanation)
| Aborts model execution.
void | defineEvent (unsigned int value, const std::string &label)
| Adds an event value and associated label to the set of events.
void | defineState (unsigned int value, const std::string &label, StateHandler handler, const StatePausing &state_pausing=STATE_PAUSE_NEVER)
| Adds an state value and associated label to the set of states.
bool | doOnEntry ()
| Checks if on entry flag is true.
bool | doOnExit ()
| Checks if on exit flag is true.
const EventPtr & | getEvent (unsigned int value)
| Fetches the event referred to by value.
const StatePtr | getState (unsigned int value)
| Fetches the state referred to by value.
const StatePtr | getStateInternal (unsigned int value)
| Fetches the state referred to by value.
void | initDictionaries ()
| Initializes the event and state dictionaries.
void | postNextEvent (unsigned int event)
| Sets the next event to the given event value.
void | setState (unsigned int state)
| Sets the current state to the given state value.
void | transition (unsigned int state, unsigned int event)
| Sets up the model to transition into given state with a given event.
virtual void | verifyStates ()
| Validates the contents of the set of states.

## Detailed Description

State model for asynchronous read of data in JSON format.

Kea control channel uses stream sockets for forwarding commands received by the Kea Control Agent to respective Kea services. The responses may contain large amounts of data (e.g. lease queries may return thousands of leases). Such responses rarely fit into a single data buffer and require multiple calls to receive/read or asynchronous receive/read.

A receiver performing multiple reads from a socket must be able to locate the boundaries of the command within the data stream. The JSONFeed state model solves this problem.

When the partial data is read from the stream socket it should be provided to the JSONFeed using JSONFeed::postBuffer and then the JSONFeed::poll should be called to start processing the received data. The actual JSON structure can be preceded by whitespaces. When first occurrence of one of the '{' or '[' characters is found in the stream it is considered a beginning of the JSON structure. The model includes an internal counter of new '{' and '[' occurrences. The counter increases one of these characters is found. When any of the '}' or ']' is found, the counter is decreased. When the counter is decreased to 0 it indicates that the entire JSON structure has been received and processed.

As '{', '}', '[' and ']' can be embedded in JSON strings two states for strings and escape in strings are required. Note the processing of escapes is greatly simplified compared to ECMA 404 figure 5.

Added support for '#' to end of line (bash), '//' to end of line (C++) and '/*' to '*‍/' (C) comments both before JSON and inside JSON. Note that this mechanism doesn't check if the JSON structure is well formed. It merely detects the end of the JSON structure if this structure is well formed. The structure is validated when JSONFeed::toElement is called to retrieve the data structures encapsulated with isc::data::Element objects.

Definition at line 71 of file json_feed.h.

## Constructor & Destructor Documentation

## ◆ JSONFeed()

isc::config::JSONFeed::JSONFeed | ( |  | ) |

Constructor.

Definition at line 43 of file json_feed.cc.

References isc::util::StateModel::StateModel().

Here is the call graph for this function:

## Member Function Documentation

## ◆ feedOk()

bool isc::config::JSONFeed::feedOk | ( |  | ) | const

Checks if the data have been successfully processed.

Definition at line 82 of file json_feed.cc.

References isc::util::StateModel::END_EVT, FEED_OK_EVT, isc::util::StateModel::getLastEvent(), and isc::util::StateModel::getNextEvent().

Here is the call graph for this function:

## ◆ getErrorMessage()

std::string isc::config::JSONFeed::getErrorMessage | ( |  | ) | const
| inline

Returns error string when data processing has failed.

Definition at line 190 of file json_feed.h.

## ◆ getProcessedText()

std::string isc::config::JSONFeed::getProcessedText | ( |  | ) | const
| inline

Returns the text parsed into the buffer.

Definition at line 195 of file json_feed.h.

## ◆ initModel()

void isc::config::JSONFeed::initModel | ( |  | ) |

Initializes state model.

Initializes events and states. It sets the model to `RECEIVE_START_ST` and the next event to `START_EVT`.

Definition at line 49 of file json_feed.cc.

References isc::util::StateModel::initDictionaries(), isc::util::StateModel::postNextEvent(), RECEIVE_START_ST, isc::util::StateModel::setState(), and isc::util::StateModel::START_EVT.

Here is the call graph for this function:

## ◆ needData()

bool isc::config::JSONFeed::needData | ( |  | ) | const

Checks if the model needs additional data to continue.

The caller can use this method to check if the model expects additional data to be provided to finish processing input data.

Returns
  true if more data is needed, false otherwise.

Definition at line 76 of file json_feed.cc.

References isc::util::StateModel::getNextEvent(), NEED_MORE_DATA_EVT, and isc::util::StateModel::START_EVT.

Referenced by toElement().

Here is the call graph for this function:

## ◆ poll()

void isc::config::JSONFeed::poll | ( |  | ) |

Runs the model as long as data is available.

It processes the input data character by character until it reaches the end of the input buffer, in which case it returns. The next event is set to `NEED_MORE_DATA_EVT` to indicate the need for providing additional data using JSONFeed::postBuffer. This function also returns when the end of the JSON structure has been detected or when an error has occurred.

Definition at line 61 of file json_feed.cc.

References isc::util::StateModel::abortModel(), isc::util::StateModel::getCurrState(), isc::util::StateModel::getNextEvent(), isc::util::StateModel::getState(), isc::util::StateModel::isModelDone(), NEED_MORE_DATA_EVT, and isc::util::StateModel::NOP_EVT.

Here is the call graph for this function:

## ◆ postBuffer()

void isc::config::JSONFeed::postBuffer | ( | const void * | buf,
|  | const size_t | buf_size )

Receives additional data read from a data stream.

A caller invokes this method to pass additional chunk of data received from the stream.

Parameters

  buf | Pointer to a buffer holding additional input data.
  buf_size | Size of the data in the input buffer.

Definition at line 102 of file json_feed.cc.

References isc::util::StateModel::getCurrState(), isc::util::StateModel::getNextEvent(), MORE_DATA_PROVIDED_EVT, NEED_MORE_DATA_EVT, and isc::util::StateModel::transition().

Here is the call graph for this function:

## ◆ toElement()

ElementPtr isc::config::JSONFeed::toElement | ( |  | ) | const

Returns processed data as a structure of isc::data::Element objects.

Exceptions

  JSONFeedError | if the received JSON is not well formed.

Definition at line 88 of file json_feed.cc.

References Element::fromWire(), isc_throw, and needData().

Here is the call graph for this function:

## Member Data Documentation

## ◆ C_COMMENT_BEFORE_JSON_ST

const int isc::config::JSONFeed::C_COMMENT_BEFORE_JSON_ST = SM_DERIVED_STATE_MIN + 5
| static

Skipping a C style comment before actual JSON.

Definition at line 91 of file json_feed.h.

## ◆ C_COMMENT_ST

const int isc::config::JSONFeed::C_COMMENT_ST = SM_DERIVED_STATE_MIN + 13
| static

Skipping a C style comment.

Definition at line 115 of file json_feed.h.

## ◆ DATA_READ_OK_EVT

const int isc::config::JSONFeed::DATA_READ_OK_EVT = SM_DERIVED_EVENT_MIN + 1
| static

Chunk of data successfully read and parsed.

Definition at line 143 of file json_feed.h.

## ◆ EOL_COMMENT_BEFORE_JSON_ST

const int isc::config::JSONFeed::EOL_COMMENT_BEFORE_JSON_ST = SM_DERIVED_STATE_MIN + 3
| static

Skipping an end-of-line comment before actual JSON.

Definition at line 85 of file json_feed.h.

## ◆ EOL_COMMENT_ST

const int isc::config::JSONFeed::EOL_COMMENT_ST = SM_DERIVED_STATE_MIN + 11
| static

Skipping an end-of-line comment.

Definition at line 109 of file json_feed.h.

## ◆ ESCAPE_JSON_ST

const int isc::config::JSONFeed::ESCAPE_JSON_ST = SM_DERIVED_STATE_MIN + 10
| static

JSON escape next character.

Definition at line 106 of file json_feed.h.

## ◆ FEED_FAILED_EVT

const int isc::config::JSONFeed::FEED_FAILED_EVT = SM_DERIVED_EVENT_MIN + 101
| static

Invalid syntax detected.

Definition at line 155 of file json_feed.h.

## ◆ FEED_FAILED_ST

const int isc::config::JSONFeed::FEED_FAILED_ST = SM_DERIVED_STATE_MIN + 101
| static

Invalid syntax detected.

For example, non matching braces or invalid characters found.

Definition at line 133 of file json_feed.h.

## ◆ FEED_OK_EVT

const int isc::config::JSONFeed::FEED_OK_EVT = SM_DERIVED_EVENT_MIN + 100
| static

Found opening brace and the matching closing brace.

Definition at line 152 of file json_feed.h.

Referenced by feedOk().

## ◆ FEED_OK_ST

const int isc::config::JSONFeed::FEED_OK_ST = SM_DERIVED_STATE_MIN + 100
| static

Found opening and closing brace or square bracket.

This doesn't however indicate that the JSON is well formed. It only means that matching closing brace or square bracket was found.

Definition at line 128 of file json_feed.h.

## ◆ INNER_JSON_ST

const int isc::config::JSONFeed::INNER_JSON_ST = SM_DERIVED_STATE_MIN + 8
| static

Parsing JSON.

Definition at line 100 of file json_feed.h.

## ◆ JSON_END_ST

const int isc::config::JSONFeed::JSON_END_ST = SM_DERIVED_STATE_MIN + 15
| static

Found last closing brace or square bracket.

Definition at line 121 of file json_feed.h.

## ◆ JSON_START_ST

const int isc::config::JSONFeed::JSON_START_ST = SM_DERIVED_STATE_MIN + 7
| static

Found first opening brace or square bracket.

Definition at line 97 of file json_feed.h.

## ◆ MORE_DATA_PROVIDED_EVT

const int isc::config::JSONFeed::MORE_DATA_PROVIDED_EVT = SM_DERIVED_EVENT_MIN + 3
| static

New data provided and parsing should continue.

Definition at line 149 of file json_feed.h.

Referenced by postBuffer().

## ◆ NEED_MORE_DATA_EVT

const int isc::config::JSONFeed::NEED_MORE_DATA_EVT = SM_DERIVED_EVENT_MIN + 2
| static

Unable to proceed with parsing until new data is provided.

Definition at line 146 of file json_feed.h.

Referenced by needData(), poll(), and postBuffer().

## ◆ RECEIVE_START_ST

const int isc::config::JSONFeed::RECEIVE_START_ST = SM_DERIVED_STATE_MIN + 1
| static

State indicating a beginning of a feed.

Definition at line 79 of file json_feed.h.

Referenced by initModel().

## ◆ START_COMMENT_BEFORE_JSON_ST

const int isc::config::JSONFeed::START_COMMENT_BEFORE_JSON_ST = SM_DERIVED_STATE_MIN + 4
| static

Starting one of the comments beginning with a slash before actual JSON.

Definition at line 88 of file json_feed.h.

## ◆ START_COMMENT_ST

const int isc::config::JSONFeed::START_COMMENT_ST = SM_DERIVED_STATE_MIN + 12
| static

Starting one of the comments beginning with a slash.

Definition at line 112 of file json_feed.h.

## ◆ STOP_COMMENT_BEFORE_JSON_ST

const int isc::config::JSONFeed::STOP_COMMENT_BEFORE_JSON_ST = SM_DERIVED_STATE_MIN + 6
| static

Stopping a C style comment before actual JSON.

Definition at line 94 of file json_feed.h.

## ◆ STOP_COMMENT_ST

const int isc::config::JSONFeed::STOP_COMMENT_ST = SM_DERIVED_STATE_MIN + 14
| static

Stopping a C style comment.

Definition at line 118 of file json_feed.h.

## ◆ STRING_JSON_ST

const int isc::config::JSONFeed::STRING_JSON_ST = SM_DERIVED_STATE_MIN + 9
| static

Parsing JSON string.

Definition at line 103 of file json_feed.h.

## ◆ WHITESPACE_BEFORE_JSON_ST

const int isc::config::JSONFeed::WHITESPACE_BEFORE_JSON_ST = SM_DERIVED_STATE_MIN + 2
| static

Skipping whitespaces before actual JSON.

Definition at line 82 of file json_feed.h.

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

- json_feed.h
- json_feed.cc