ElementJsonSerializers Class Reference

Handles serialization and deserialization of dynamic data::Element objects to and from JSON. More...

#include <RobotAPI/components/ArViz/Introspection/ElementJsonSerializers.h>

Static Public Member Functions
static void	from_json (const nlohmann::json &j, data::Element &element)
	Deserialize element from JSON according to its dynamic type.
static void	from_json (const nlohmann::json &j, data::ElementPtr &elementPtr)
	Deserialize elementPtr from JSON according the type name in j.
static std::vector< std::string >	getRegisteredTypes ()
	Get the type names for which serializers are registered.
static std::string	getTypeName (const nlohmann::json &j)
static bool	isTypeRegistered (const std::string &typeName)
	Indicates whether there is a serializer registered for the given type name.
template<class DerivedElement>
static void	registerSerializer (RawToJsonFn< DerivedElement > to_json, RawFromJsonFn< DerivedElement > from_json, bool overwrite=false)
	Register a JSON seralizer for DerivedElement.
template<class DerivedElement>
static void	registerSerializer (ToJsonFn< DerivedElement > to_json, FromJsonFn< DerivedElement > from_json, bool overwrite=false)
	Register a JSON seralizer for DerivedElement.
template<class DerivedElement>
static void	removeSerializer ()
	Remove a registered serializer for DerivedElement.
static void	to_json (nlohmann::json &j, const data::Element &element)
	Serialize element to JSON according to its dynamic type.
static void	to_json (nlohmann::json &j, const data::Element *elementPtr)
	Serialize element to JSON according to its dynamic type.

Static Public Attributes
static const std::string	JSON_TYPE_NAME_KEY = "__type__"
	JSON key under which demangled type name is stored.

Detailed Description

Handles serialization and deserialization of dynamic data::Element objects to and from JSON.

This class allows serialization of newly defined types through the standard nlohmann::json interface, which builds upon user-defined to_json() and from_json() functions for a user-defined type.

to register your custom data::Element type

Suppose you have a custom class deriving from semrel::data::Element in a namespace myelement, along with serializing functions following the standard pattern employed by nlohmann::json:

namespace myelement
{
    class Mydata::Element : public semrel::data::Element { ... };
 
    void to_json(nlohmann::json& j, const Mydata::Element& element);
    void from_json(const nlohmann::json& j, Mydata::Element& element);
}

To enable serialization through the general serialization functions for data::Element, register your functions to ElementSerializers, specifying your custom type as template argument:

// in namespace myelement
json::ElementSerializers::registerSerializer<Mydata::Element>(to_json, from_json);

You can also specify the namespace, like in myelement::to_json.

To make sure the serializer is always registered, you can create a static variable (extern free or a static class member) whose initialization will register the serializers, e.g.:

// In the header file:
namespace myelement
{
    // Extern free or static member variable.
    extern const int _MY_SHAPE_JSON_REGISTRATION;
}
 
// In the sourcer file:
const int myelement::_MY_SHAPE_JSON_REGISTRATION = []()
{
    // Register serializer when initializing variable.
    json::ElementSerializers::registerSerializer<Mydata::Element>(to_json, from_json);
    return 0;
}();

to register your custom data::Element type

ElementSerializers has a global map, which maps a (demangled) type name to the respective serializer. When serializing an object of type data::Element, the map is searched for an entry for the instance's dynamic type. If one is found, the registered to_json() is used to write the JSON document. In addition, a type name entry specifying the (demangled) derived type name is stored (under the key ElementSerializers::JSON_TYPE_NAME_KEY).

When deserializing from a JSON document, the type name entry is used to determine the correct serializer, which casts the to-be-deserialized data::Element instance to the derived type and passes it to the registered from_json method. When deserializing into a data::ElementPtr, the pointer is allocated a new instance of the deriving type first.

Member Function Documentation

from_json() [1/2]

void from_json ( const nlohmann::json & j, data::Element & element )

static

Deserialize element from JSON according to its dynamic type.

Exceptions

`error::NoTypeNameEntryInJsonObject`	If j does not contain the key JSON_TYPE_NAME_KEY (or is not a JSON object).
`error::TypeNameMismatch`	If the type name in j does not match element's dynamic type.
`error::NoSerializerForType`	If there is no serializer for the given name.

from_json() [2/2]

void from_json ( const nlohmann::json & j, data::ElementPtr & elementPtr )

static

Deserialize elementPtr from JSON according the type name in j.

If there is a registered serializer for the type name in j, assigns a new instance of the dynamic type to elementPtr and deserializes the created instance from j. /// Get the accepted demangled type names.

Exceptions

`error::NoTypeNameEntryInJsonObject`	If j does not contain the key JSON_TYPE_NAME_KEY (or is not a JSON object).
`error::NoSerializerForType`	If there is no serializer for the type in j.

getRegisteredTypes()

std::vector< std::string > getRegisteredTypes ( )

static

Get the type names for which serializers are registered.

getTypeName()

std::string getTypeName ( const nlohmann::json & j )

static

isTypeRegistered()

bool isTypeRegistered ( const std::string & typeName )

static

Indicates whether there is a serializer registered for the given type name.

registerSerializer() [1/2]

template<class DerivedElement>

static void registerSerializer ( RawToJsonFn< DerivedElement > to_json, RawFromJsonFn< DerivedElement > from_json, bool overwrite = false )

inlinestatic

Register a JSON seralizer for DerivedElement.

Can be called with raw function pointers with automatic type deduction e.g.:

namespace my_element {
    // Standard serialization methods.
    void to_json(nlohmann::json& j, const Mydata::Element& box);
    void from_json(const nlohmann::json& j, Mydata::Element& box);
}
 
void register() {
    // Register serializer:
    registerSerializer<my_element::Mydata::Element>(my_element::to_json, my_element::from_json);
}

Exceptions

`error::SerializerAlreadyRegisteredForType`

If there already is a registered serializer for that type.

registerSerializer() [2/2]

template<class DerivedElement>

static void registerSerializer ( ToJsonFn< DerivedElement > to_json, FromJsonFn< DerivedElement > from_json, bool overwrite = false )

inlinestatic

Register a JSON seralizer for DerivedElement.

Can be called with std::function objects, e.g. lambdas:

// Capture `serializer` by reference.
registerSerializer<Box>(
     [&](nlohmann::json& j, const Box& box) { myserializer.to_json(j, box); },
     [&](const nlohmann::json& j, Box& box) { myserializer.from_json(j, cyl); }
);

Exceptions

`error::SerializerAlreadyRegisteredForType`

If there already is a registered serializer for that type.

removeSerializer()

template<class DerivedElement>

static void removeSerializer ( )

inlinestatic

Remove a registered serializer for DerivedElement.

to_json() [1/2]

void to_json ( nlohmann::json & j, const data::Element & element )

static

Serialize element to JSON according to its dynamic type.

Exceptions

`error::NoSerializerForType`

If there is no serializer for the given name.

to_json() [2/2]

void to_json ( nlohmann::json & j, const data::Element * elementPtr )

static

Serialize element to JSON according to its dynamic type.

Exceptions

`error::data::ElementPointerIsNull`	If elementPtr is null.
`error::NoSerializerForType`	If there is no serializer for the element type.

See also

to_json(nlohmann::json& j, const data::Element& element)

Member Data Documentation

JSON_TYPE_NAME_KEY

const std::string JSON_TYPE_NAME_KEY = "__type__"

static

JSON key under which demangled type name is stored.

---

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

• RobotAPI/components/ArViz/Introspection/ElementJsonSerializers.h
• RobotAPI/components/ArViz/Introspection/ElementJsonSerializers.cpp
• RobotAPI/components/ArViz/Introspection/register_element_json_serializers.cpp