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

#include <json_feed.h>

Inheritance diagram for isc::config::JSONFeed:

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.

virtual void	defineEvents ()
	Populates 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.

virtual void	defineStates ()
	Populates 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.

virtual void	onModelFailure (const std::string &explanation)
	Handler for fatal model execution errors.

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	verifyEvents ()
	Validates the contents of the set of events.

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.

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 isc::data::Element::fromWire(), isc_throw, needData(), and isc::Exception::what().

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:

Static Public Attributes

Events used during data processing.

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ JSONFeed()

Member Function Documentation

◆ feedOk()

◆ getErrorMessage()

◆ getProcessedText()

◆ initModel()

◆ needData()

◆ poll()

◆ postBuffer()

◆ toElement()

Member Data Documentation

◆ C_COMMENT_BEFORE_JSON_ST

◆ C_COMMENT_ST

◆ DATA_READ_OK_EVT

◆ EOL_COMMENT_BEFORE_JSON_ST

◆ EOL_COMMENT_ST

◆ ESCAPE_JSON_ST

◆ FEED_FAILED_EVT

◆ FEED_FAILED_ST

◆ FEED_OK_EVT

◆ FEED_OK_ST

◆ INNER_JSON_ST

◆ JSON_END_ST

◆ JSON_START_ST

◆ MORE_DATA_PROVIDED_EVT

◆ NEED_MORE_DATA_EVT

◆ RECEIVE_START_ST

◆ START_COMMENT_BEFORE_JSON_ST

◆ START_COMMENT_ST

◆ STOP_COMMENT_BEFORE_JSON_ST

◆ STOP_COMMENT_ST

◆ STRING_JSON_ST

◆ WHITESPACE_BEFORE_JSON_ST