MIRA
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Types | Public Member Functions | Static Public Member Functions | Protected Types | Protected Member Functions | Static Protected Member Functions | Protected Attributes | List of all members
JSONDeserializer Class Reference

Deserializer for serializing objects from JSON format. More...

#include <serialization/JSONSerializer.h>

Inheritance diagram for JSONDeserializer:
Inheritance graph
[legend]

Public Types

enum  InputFormat { STANDARD = 0x00, ACCEPT_STRING_MAP_AS_OBJECT = 0x01 }
 Flags for JSON input format. More...
 
typedef Base::VersionType VersionType
 
typedef boost::mpl::bool_< false > isReadOnly
 
typedef boost::mpl::bool_< true > isObjectTrackingSupported
 
typedef ReflectorInterface
< JSONDeserializer >
::AcceptDesiredVersion 
AcceptDesiredVersion
 
typedef boost::mpl::bool_< true > useHumanReadableIDs
 Specifies, if the Reflector supports human readable IDs. More...
 
typedef boost::mpl::bool_< false > requireReflectBarriers
 Specifies whether the Reflector uses so-called 'reflect barriers' to allow maintaining separate states for individual blocks of reflected data. More...
 

Public Member Functions

 MIRA_ENUM_TO_FLAGS_INCLASS (InputFormat) JSONDeserializer(const json
 
template<typename T >
void deserialize (T &value)
 
void deserialize (json::Value &value)
 
const json::ValuegetMember (const json::Value *value, const std::string &name)
 
const json::ValuegetItem (const json::Value *value, std::size_t index)
 
template<typename T >
VersionType version (VersionType expectedVersion, const T *object=NULL)
 
 MIRA_DEPRECATED ("Please call as version<MyType>(v) or version(v, this)", VersionType version(VersionType expectedVersion))
 
template<typename T >
VersionType version (VersionType expectedVersion, AcceptDesiredVersion, const T *caller=NULL)
 
template<typename T >
void atomic (T &member)
 
void atomic (json::Value &member)
 
template<typename T >
void object (T &member)
 
template<typename T >
void collection (T &member)
 
template<typename mapped_type >
void collection (std::map< std::string, mapped_type > &member)
 
const json::ArraygetCollection ()
 
template<typename T >
void pointer (T *&pointer)
 
std::string pointerClassType ()
 
template<typename T >
void invokeMemberOverwrite (T &member, const ReflectMemberMeta &meta)
 
uint32 getStringMapElementCount ()
 
template<typename Container >
void mapEntry (int id, Container &c, typename Container::iterator &hint)
 
void deserialize (const std::string &name, T &value)
 Deserializes the specified object value with the given name. More...
 
void trackObject (T &member)
 
void pointerNormal (T *&pointer, int typeId)
 
void pointerPolymorphic (T *&pointer, int typeId)
 
void pointerAbstract (T *&pointer, int typeId)
 
void sharedPointerReset (boost::shared_ptr< T > &ptr, T *rawPtr)
 
void sharedPointerReset (std::shared_ptr< T > &ptr, T *rawPtr)
 
void sharedPointerReset (SType< T > &ptr, T *rawPtr, std::map< void *, SType< void > > &pointerMap)
 
void pushObjectTrackingStore ()
 
void popObjectTrackingStore ()
 
void member (const char *name, T &member, const char *comment, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, const std::string &id, T &member, const char *comment, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, const T &member, Setter< T > setter, const char *comment, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, Getter< T > getter, Setter< T > setter, const char *comment, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, T &member, const char *comment, const T &defaultValue, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, T &member, const char *comment, const U &defaultValue, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, const T &member, Setter< T > setter, const char *comment, const T &defaultValue, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, const T &member, Setter< T > setter, const char *comment, const U &defaultValue, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, Getter< T > getter, Setter< T > setter, const char *comment, const T &defaultValue, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void member (const char *name, Getter< T > getter, Setter< T > setter, const char *comment, const U &defaultValue, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, T &member, const char *comment, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, const std::string &id, T &member, const char *comment, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, const T &member, Setter< T > setter, const char *comment, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, Getter< T > getter, Setter< T > setter, const char *comment, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, T &member, const char *comment, const T &defaultValue, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, T &member, const char *comment, const U &defaultValue, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, const T &member, Setter< T > setter, const char *comment, const T &defaultValue, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, const T &member, Setter< T > setter, const char *comment, const U &defaultValue, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, Getter< T > getter, Setter< T > setter, const char *comment, const T &defaultValue, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void property (const char *name, Getter< T > getter, Setter< T > setter, const char *comment, const U &defaultValue, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 
void delegate (T &member, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 Delegates the serialization directly to the specified member, without creating a separate compound for the current object. More...
 
void delegate (const T &member, Setter< T > setter, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 Delegates the serialization directly to the specified member, without creating a separate compound for the current object. More...
 
void delegate (Getter< T > getter, Setter< T > setter, ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 Delegates the serialization directly to the specified member, without creating a separate compound for the current object. More...
 
const ReflectMemberMetagetCurrentMemberMeta () const
 Returns the meta-information of the current member that is reflected. More...
 
const std::string & getCurrentMemberFullID () const
 Returns the full human readable object id / name of the current member being reflected. More...
 
void invokeMember (T &member, const ReflectMemberMeta &meta)
 Is called to invoke this Reflector on the member with the specified meta information. More...
 
void invokePointerObject (T &member)
 Is called to reflect objects of pointers. More...
 
void invokeMemberWithoutDefault (T &member, const ReflectMemberMeta &meta)
 Delegates to invokeMember() and rethrows any occurring XMemberNotFound exception as XIO exception. More...
 
void invokeMemberWithDefault (T &member, const ReflectMemberMeta &meta, const U &defaultValue)
 Delegates to invokeMember() and handles any occurring XMemberNotFound exception by setting the member to the given default value. More...
 
void invokeMemberWithDefault (T &member, const ReflectMemberMeta &meta, const serialization::IgnoreMissing &defaultValue)
 Delegates to invokeMember() and handles any occurring XMemberNotFound exception by ignoring the exception and hence the missing member, as indicated by IgnoreMissing as default value. More...
 
VersionType requireVersion (VersionType version, VersionType minVersion, const T *caller=NULL)
 implements ReflectorInterface (for documentation see ReflectorInterface) More...
 
void requireVersion (VersionType requiredVersion, const T *caller=NULL)
 implements ReflectorInterface (for documentation see ReflectorInterface) More...
 
VersionType requireVersion (VersionType version, VersionType minVersion, AcceptDesiredVersion, const T *caller=NULL)
 implements ReflectorInterface (for documentation see ReflectorInterface) More...
 
void requireVersion (VersionType requiredVersion, AcceptDesiredVersion, const T *caller=NULL)
 implements ReflectorInterface (for documentation see ReflectorInterface) More...
 
 MIRA_DEPRECATED ("Please call as requireVersion<MyType>(v, minV) or requireVersion(v, minV, this)", VersionType requireVersion(VersionType version, VersionType minVersion))
 
 MIRA_DEPRECATED ("Please call as requireVersion<MyType>(v) or requireVersion(v, this)", void requireVersion(VersionType requiredVersion))
 
void reflectBase (Base &base)
 implements ReflectorInterface (for documentation see ReflectorInterface) More...
 
ReflectState preReflect (const char *context="")
 If a reflector requires reflection barriers, preReflect() and postReflect() should be called before/after calling an external method within reflect(), to declare these barriers (such a 'barrier' is just a declaration to the reflector, in fact). More...
 
void postReflect (const ReflectState &)
 See preReflect for documentation. More...
 
Visiting methods that are called by the RecursiveMemberReflector

while reflecting the members

void enumeration (T &member)
 Is called by the if the member is an enumeration. More...
 
Methods for reflecting members

These visiting methods are supported by the RecursiveMemberReflector.

void roproperty (const char *name, const T &member, const char *comment, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 A property that just reflects a runtime state of the object and can be displayed but not altered. More...
 
void roproperty (const char *name, const std::string &id, const T &member, const char *comment, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 Same as above, with an extra parameter for specifying the id explicitly if it differs from name. More...
 
void roproperty (const char *name, Getter< T > getter, const char *comment, PropertyHint &&hint=PropertyHint(), ReflectCtrlFlags flags=REFLECT_CTRLFLAG_NONE)
 Same as above, with a special getter method for reading the member. More...
 
void itemName (const std::string &name)
 If the currently reflected object is an item within a collection, this allows to specify an explicit name for that item. More...
 
Methods for reflecting RPC (remote procedure call) methods
void interface (const char *name)
 Indicates that the class implements the specified RPC interface. More...
 
void method (const char *name, Method method, const char *comment, const char *paramName, const char *paramDescription, P paramSampleValue,...)
 Specifies that the class that is reflected provides a service through the specified static member function or free function. More...
 
void method (const char *name, Method method, Class *object, const char *comment, const char *paramName, const char *paramDescription, P paramSampleValue,...)
 Specifies that the class that is reflected provides a service through the specified non-static member function. More...
 
void method (const char *name, Method method, const char *comment, const char *paramName, const char *paramDescription, P paramSampleValue,...)
 Specifies that the class that is reflected provides a service through the specified function wrapper. More...
 

Static Public Member Functions

static int forcedDeserializeVersion ()
 Returns either the version number from value of environment variable 'MIRA_FORCE_DESERIALIZE_VERSION', or -1 (= do not force a version). More...
 
static void registerClass ()
 Registers a new polymorphic class at the PolymorphPointerReflector. More...
 
static void unregisterClass ()
 Unregisters the class. More...
 
static bool isReflectedAsPointer ()
 For internal use only: Returns true, if the type T is ever reflected as pointer within the current translation unit (C file). More...
 
static bool usesHumanReadableIDs ()
 Returns true, if the concrete derived Reflector supports human readable IDs. More...
 

Protected Types

typedef std::map< std::string,
void * > 
ObjectNameToInstanceMap
 
typedef std::vector< void * > ObjectsVector
 
typedef std::pair
< ObjectsVector,
ObjectNameToInstanceMap
TrackingState
 
typedef std::map< void
*, boost::shared_ptr< void > > 
BoostSharedPointerMap
 
typedef std::map< void
*, std::shared_ptr< void > > 
StdSharedPointerMap
 

Protected Member Functions

bool isTrackingEnabled () const
 Returns true, if object tracking is enabled for the type T. More...
 
T * resolveReference (int objectId)
 Resolves a pointer reference to a previously stored object with the specified full id. More...
 
T * resolveReference (const std::string &fullId)
 Same as the above method, but here the object id can be specified as full human readable id. More...
 
void invokeTrackObject (T &member)
 tracks the given object (if pointer tracking is enabled for type T) More...
 
JSONDeserializerThis ()
 "Curiously recurring template pattern" (CRTP). More...
 
void invoke (T &object)
 Invokes this reflector on the specified object. More...
 
void invokeOverwrite (T &object)
 The actual invoke implementation, that may also be overwritten in derived classes to add additional functionality. More...
 

Static Protected Member Functions

static int checkForcedVersion (const std::string &variable)
 

Protected Attributes

ObjectNameToInstanceMap mObjectNameToInstance
 maps full id names to instance pointers More...
 
ObjectsVector mObjects
 maps the ids to the instance pointers More...
 
std::stack< TrackingStatemTrackingStack
 
BoostSharedPointerMap mBoostSharedPointers
 
StdSharedPointerMap mStdSharedPointers
 

Optional Class Versioning.

These visiting methods may be supported by different reflectors like the RecursiveMemberReflector and the RPCMethodReflector, etc.

Note
Specifying versions for serialized classes is optional.
requireVersion() and version() currently are supported by serialization reflectors only.
typedef
serialization::ClassVersionMap 
ClassVersionMap
 
VersionType requireVersion (VersionType version, VersionType minVersion, const T *caller=NULL)
 Same as above, but allows to specify a minimum supported version, and throws XIO if the minimum version requirement is not met. More...
 
void requireVersion (VersionType version, const T *caller=NULL)
 Specifies the current class version, which is also the minimum (and therefore only) version accepted (therefore, no need to return a version number). More...
 
VersionType requireVersion (VersionType version, VersionType minVersion, AcceptDesiredVersion, const T *caller=NULL)
 Extension of requireVersion() (see above), that additionally signals the reflector that the caller will properly handle a different version than the one it specifies itself. More...
 
void requireVersion (VersionType version, AcceptDesiredVersion, const T *caller=NULL)
 Extension of requireVersion() (see above), that additionally signals the reflector that the caller will properly handle a different version than it one it specifies itself. More...
 
 MIRA_DEPRECATED ("Please call as version<MyType>(v) or version(v, this)", VersionType version(VersionType version))
 Deprecated 'anonymous' (no type) version(). More...
 
 MIRA_DEPRECATED ("Please call as requireVersion<MyType>(v, minV) or requireVersion(v, minV, this)", VersionType requireVersion(VersionType version, VersionType minVersion))
 Deprecated 'anonymous' (no type) requireVersion(). More...
 
 MIRA_DEPRECATED ("Please call as requireVersion<MyType>(v) or requireVersion(v, this)", VersionType requireVersion(VersionType version))
 Deprecated 'anonymous' (no type) requireVersion(). More...
 
VersionType version (VersionType version, const T *caller=NULL)
 Specifies the current class version and returns the version found in the data stream. More...
 
VersionType version (VersionType version, AcceptDesiredVersion, const T *caller=NULL)
 Extension of version() (see above), that additionally signals the reflector that the caller will properly handle a different version than the one it specifies itself. More...
 
void desireClassVersions (const ClassVersionMap &versions)
 Historically, classes have just been defining their current version themselves during serialization (the case where an object exists and its state is read out and serialized), by calling Reflector::version() with the respective version number parameter. More...
 

Detailed Description

Deserializer for serializing objects from JSON format.

Example usage:

// load the json content
json::read(..., v);
// create the JSON deserializer
JSONDeserializer deserializer(v);
// the object that will be filled with the content
std::vector<int> myValue;
// deserialize the value
deserializer.deserialize(myValue);
// myValue is now filled with the content that was stored in the JSON value

For the serialization of JSON content see JSONSerializer.

See Also
Serialization, JSONSerializer

Member Typedef Documentation

typedef boost::mpl::bool_<false> isReadOnly
inherited
typedef boost::mpl::bool_<true> isObjectTrackingSupported
inherited
typedef std::map<std::string, void*> ObjectNameToInstanceMap
protectedinherited
typedef std::vector<void*> ObjectsVector
protectedinherited
typedef std::pair<ObjectsVector, ObjectNameToInstanceMap> TrackingState
protectedinherited
typedef std::map<void*, boost::shared_ptr<void> > BoostSharedPointerMap
protectedinherited
typedef std::map<void*, std::shared_ptr<void> > StdSharedPointerMap
protectedinherited
typedef boost::mpl::bool_<true> useHumanReadableIDs
inherited

Specifies, if the Reflector supports human readable IDs.

This type must be set to the proper boost::mpl::bool type by the derived Reflector class. (Default is true)

typedef boost::mpl::bool_<false> requireReflectBarriers
inherited

Specifies whether the Reflector uses so-called 'reflect barriers' to allow maintaining separate states for individual blocks of reflected data.

A reflect barrier is just a virtual separation line declared by a reflected object. It tells the reflector that certain parts of the reflected data should be considered as independent and can have separate states (if the reflector maintains any states for data). As an example, the BinarySerializer reserves space for a version number for each reflected object. If there is more than one individual block, it reserves space for a version for each of the blocks. If the reflector needs reflect barriers, it defines requireReflectBarriers::type to true in its class scope, and defines methods preReflect() and postReflect() that should be called by reflected objects for separation of independent reflection blocks (where the separation is not already implied by visitors like reflector.member()!) (The default is false). Also see ReflectState and MIRA_REFLECT_CALL.

Member Enumeration Documentation

Flags for JSON input format.

Enumerator
STANDARD 

Default format.

ACCEPT_STRING_MAP_AS_OBJECT 

Accept associative containers with string keys as JSON object (keys = member names), in ADDITION to the standard array format (i.e.

the deserializer will understand BOTH formats)

Member Function Documentation

MIRA_ENUM_TO_FLAGS_INCLASS ( InputFormat  ) const
inline
void deserialize ( T &  value)
inline
void deserialize ( json::Value value)
inline
const json::Value* getMember ( const json::Value value,
const std::string &  name 
)
inline
const json::Value* getItem ( const json::Value value,
std::size_t  index 
)
inline
VersionType version ( VersionType  expectedVersion,
const T *  object = NULL 
)
inline
MIRA_DEPRECATED ( "Please call as version<MyType>(v) or version(v, this)"  ,
VersionType   versionVersionType expectedVersion 
)
inline
VersionType version ( VersionType  expectedVersion,
AcceptDesiredVersion  ,
const T *  caller = NULL 
)
inline
void atomic ( T &  member)
inline
void atomic ( json::Value member)
inline
void object ( T &  member)
inline
void collection ( T &  member)
inline
void collection ( std::map< std::string, mapped_type > &  member)
inline
const json::Array* getCollection ( )
inline
void pointer ( T *&  pointer)
inline
std::string pointerClassType ( )
inline
void invokeMemberOverwrite ( T &  member,
const ReflectMemberMeta meta 
)
inline
uint32 getStringMapElementCount ( )
inline
void mapEntry ( int  id,
Container &  c,
typename Container::iterator &  hint 
)
inline
static int forcedDeserializeVersion ( )
inlinestaticinherited

Returns either the version number from value of environment variable 'MIRA_FORCE_DESERIALIZE_VERSION', or -1 (= do not force a version).

void deserialize ( const std::string &  name,
T &  value 
)
inlineinherited

Deserializes the specified object value with the given name.

If you overwrite this method in a derived class you usually SHOULD call this method of the base class.

void trackObject ( T &  member)
inlineinherited
void pointerNormal ( T *&  pointer,
int  typeId 
)
inlineinherited
void pointerPolymorphic ( T *&  pointer,
int  typeId 
)
inlineinherited
void pointerAbstract ( T *&  pointer,
int  typeId 
)
inlineinherited
void sharedPointerReset ( boost::shared_ptr< T > &  ptr,
T *  rawPtr 
)
inlineinherited
void sharedPointerReset ( std::shared_ptr< T > &  ptr,
T *  rawPtr 
)
inlineinherited
void sharedPointerReset ( SType< T > &  ptr,
T *  rawPtr,
std::map< void *, SType< void > > &  pointerMap 
)
inlineinherited
bool isTrackingEnabled ( ) const
inlineprotectedinherited

Returns true, if object tracking is enabled for the type T.

void pushObjectTrackingStore ( )
inlineinherited
void popObjectTrackingStore ( )
inlineinherited
T* resolveReference ( int  objectId)
inlineprotectedinherited

Resolves a pointer reference to a previously stored object with the specified full id.

This is usually called by the derived concrete deserializer that has implemented the pointer() method where it detects a stored pointer reference. Instead of calling the pointer() method of this base class it then has to call this method to resolve the pointer reference. If no object with the given ID exits, an exception is thrown.

T* resolveReference ( const std::string &  fullId)
inlineprotectedinherited

Same as the above method, but here the object id can be specified as full human readable id.

Note
Can only be used for Reflectors that support human readable IDs, otherwise an exception is thrown.
void member ( const char *  name,
T &  member,
const char *  comment,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void member ( const char *  name,
const std::string &  id,
T &  member,
const char *  comment,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void member ( const char *  name,
const T &  member,
Setter< T >  setter,
const char *  comment,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void member ( const char *  name,
Getter< T >  getter,
Setter< T >  setter,
const char *  comment,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void member ( const char *  name,
T &  member,
const char *  comment,
const T &  defaultValue,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void member ( const char *  name,
T &  member,
const char *  comment,
const U &  defaultValue,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void member ( const char *  name,
const T &  member,
Setter< T >  setter,
const char *  comment,
const T &  defaultValue,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void member ( const char *  name,
const T &  member,
Setter< T >  setter,
const char *  comment,
const U &  defaultValue,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void member ( const char *  name,
Getter< T >  getter,
Setter< T >  setter,
const char *  comment,
const T &  defaultValue,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void member ( const char *  name,
Getter< T >  getter,
Setter< T >  setter,
const char *  comment,
const U &  defaultValue,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void property ( const char *  name,
T &  member,
const char *  comment,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void property ( const char *  name,
const std::string &  id,
T &  member,
const char *  comment,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void property ( const char *  name,
const T &  member,
Setter< T >  setter,
const char *  comment,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void property ( const char *  name,
Getter< T >  getter,
Setter< T >  setter,
const char *  comment,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void property ( const char *  name,
T &  member,
const char *  comment,
const T &  defaultValue,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void property ( const char *  name,
T &  member,
const char *  comment,
const U &  defaultValue,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void property ( const char *  name,
const T &  member,
Setter< T >  setter,
const char *  comment,
const T &  defaultValue,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void property ( const char *  name,
const T &  member,
Setter< T >  setter,
const char *  comment,
const U &  defaultValue,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void property ( const char *  name,
Getter< T >  getter,
Setter< T >  setter,
const char *  comment,
const T &  defaultValue,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void property ( const char *  name,
Getter< T >  getter,
Setter< T >  setter,
const char *  comment,
const U &  defaultValue,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited
void delegate ( T &  member,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

Delegates the serialization directly to the specified member, without creating a separate compound for the current object.

This method usually is used together with IsTransparentSerializable. Note: only one call of delegate is allowed within one reflect method.

void delegate ( const T &  member,
Setter< T >  setter,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

Delegates the serialization directly to the specified member, without creating a separate compound for the current object.

This method usually is used together with IsTransparentSerializable. Note: only one call of delegate is allowed within one reflect method.

void delegate ( Getter< T >  getter,
Setter< T >  setter,
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

Delegates the serialization directly to the specified member, without creating a separate compound for the current object.

This method usually is used together with IsTransparentSerializable. Note: only one call of delegate is allowed within one reflect method.

void enumeration ( T &  member)
inlineinherited

Is called by the if the member is an enumeration.

(Type A2)

As for all the other visit-methods the parameter is a reference to the actual visited/reflected member.

The default implementation casts the enum to an uint32 and calls atomic().

static void registerClass ( )
inlinestaticinherited

Registers a new polymorphic class at the PolymorphPointerReflector.

Each RecursiveMemberReflector only is able to process pointers to polymorphic classes that are registered using this method.

The MIRA_CLASS_SERIALIZATION macro provides a simple mechanism to register a class in all known MemberReflectors and calls their registerClass() method. If you implement a new MemberReflector you should modify the MIRA_CLASS_SERIALIZATION macro and add your reflector there.

See Also
MIRA_CLASS_SERIALIZATION
static void unregisterClass ( )
inlinestaticinherited

Unregisters the class.

The MIRA_CLASS_SERIALIZATION macro provides a simple mechanism to register a class in all known MemberReflectors and calls their registerClass() method. If you implement a new MemberReflector you should modify the MIRA_CLASS_SERIALIZATION macro and add your reflector there.

See Also
MIRA_CLASS_SERIALIZATION
const ReflectMemberMeta& getCurrentMemberMeta ( ) const
inlineinherited

Returns the meta-information of the current member that is reflected.

const std::string& getCurrentMemberFullID ( ) const
inlineinherited

Returns the full human readable object id / name of the current member being reflected.

This method must not be called if the Reflector has set useHumanReadableIDs to false. If it is called anyway we will assert here.

static bool isReflectedAsPointer ( )
inlinestaticinherited

For internal use only: Returns true, if the type T is ever reflected as pointer within the current translation unit (C file).

void invokeTrackObject ( T &  member)
inlineprotectedinherited

tracks the given object (if pointer tracking is enabled for type T)

void invokeMember ( T &  member,
const ReflectMemberMeta meta 
)
inlineinherited

Is called to invoke this Reflector on the member with the specified meta information.

This method delegates the call to the most derived invokeMemberOverwrite() method that may be overwritten in subclasses.

Note
Usually, the RecursiveMemberReflector should be invoked using this invokeMember() method instead of the invoke() method of the ReflectorInterface base class. The invoke() method is called internally by the RecursiveMemberReflector.
void invokePointerObject ( T &  member)
inlineinherited

Is called to reflect objects of pointers.

They will use the same meta as the pointer

void invokeMemberWithoutDefault ( T &  member,
const ReflectMemberMeta meta 
)
inlineinherited

Delegates to invokeMember() and rethrows any occurring XMemberNotFound exception as XIO exception.

void invokeMemberWithDefault ( T &  member,
const ReflectMemberMeta meta,
const U &  defaultValue 
)
inlineinherited

Delegates to invokeMember() and handles any occurring XMemberNotFound exception by setting the member to the given default value.

void invokeMemberWithDefault ( T &  member,
const ReflectMemberMeta meta,
const serialization::IgnoreMissing defaultValue 
)
inlineinherited

Delegates to invokeMember() and handles any occurring XMemberNotFound exception by ignoring the exception and hence the missing member, as indicated by IgnoreMissing as default value.

The value of the member remains unchanged.

VersionType requireVersion ( VersionType  version,
VersionType  minVersion,
const T *  caller = NULL 
)
inlineinherited

implements ReflectorInterface (for documentation see ReflectorInterface)

void requireVersion ( VersionType  requiredVersion,
const T *  caller = NULL 
)
inlineinherited

implements ReflectorInterface (for documentation see ReflectorInterface)

VersionType requireVersion ( VersionType  version,
VersionType  minVersion,
AcceptDesiredVersion  ,
const T *  caller = NULL 
)
inlineinherited

implements ReflectorInterface (for documentation see ReflectorInterface)

void requireVersion ( VersionType  requiredVersion,
AcceptDesiredVersion  ,
const T *  caller = NULL 
)
inlineinherited

implements ReflectorInterface (for documentation see ReflectorInterface)

VersionType requireVersion ( VersionType  version,
VersionType  minVersion,
const T *  caller = NULL 
)
inlineinherited

Same as above, but allows to specify a minimum supported version, and throws XIO if the minimum version requirement is not met.

Calls version() internally.

Usage:

template<typename Reflector>
void reflect(Reflector& r)
{
VersionType v = r.requireVersion(4, 2, this); // specifies version 4,
// requires version 2 or higher
if(v==3) { // handle reading version 3
...
} else // only versions 2 or 4 remain
...
}
Note
Specifying versions for serialized classes is optional.
requireVersion() and version() currently are supported by serialization reflectors only
void requireVersion ( VersionType  version,
const T *  caller = NULL 
)
inlineinherited

Specifies the current class version, which is also the minimum (and therefore only) version accepted (therefore, no need to return a version number).

See above.

VersionType requireVersion ( VersionType  version,
VersionType  minVersion,
AcceptDesiredVersion  ,
const T *  caller = NULL 
)
inlineinherited

Extension of requireVersion() (see above), that additionally signals the reflector that the caller will properly handle a different version than the one it specifies itself.

void requireVersion ( VersionType  version,
AcceptDesiredVersion  ,
const T *  caller = NULL 
)
inlineinherited

Extension of requireVersion() (see above), that additionally signals the reflector that the caller will properly handle a different version than it one it specifies itself.

MIRA_DEPRECATED ( "Please call as requireVersion<MyType>(v, minV) or requireVersion(v, minV, this)"  ,
VersionType  requireVersionVersionType version, VersionType minVersion 
)
inlineinherited
MIRA_DEPRECATED ( "Please call as requireVersion<MyType>(v) or requireVersion(v, this)"  ,
void  requireVersionVersionType requiredVersion 
)
inlineinherited
MIRA_DEPRECATED ( "Please call as version<MyType>(v) or version(v, this)"  ,
VersionType  versionVersionType version 
)
inlineinherited

Deprecated 'anonymous' (no type) version().

MIRA_DEPRECATED ( "Please call as requireVersion<MyType>(v, minV) or requireVersion(v, minV, this)"  ,
VersionType  requireVersionVersionType version, VersionType minVersion 
)
inlineinherited

Deprecated 'anonymous' (no type) requireVersion().

MIRA_DEPRECATED ( "Please call as requireVersion<MyType>(v) or requireVersion(v, this)"  ,
VersionType  requireVersionVersionType version 
)
inlineinherited

Deprecated 'anonymous' (no type) requireVersion().

void reflectBase ( Base &  base)
inlineinherited

implements ReflectorInterface (for documentation see ReflectorInterface)

JSONDeserializer * This ( )
inlineprotectedinherited

"Curiously recurring template pattern" (CRTP).

Safely casts this into Derived. This is safe since when implementing derived class their type is passed as template parameter.

See Wikipedia for more details on CRTP if necessary!

void invoke ( T &  object)
inlineprotectedinherited

Invokes this reflector on the specified object.

This is like calling object.reflect(*this). However, this automatically examines if the class T contains a reflect method. In this case it calls the intrusive reflect method, otherwise it uses the non-intrusive reflect method.

void invokeOverwrite ( T &  object)
inlineprotectedinherited

The actual invoke implementation, that may also be overwritten in derived classes to add additional functionality.

Note
If you overwrite this method you should call the implementation of the base class unless you perform your own invocation process.
VersionType version ( VersionType  version,
const T *  caller = NULL 
)
inlineinherited

Specifies the current class version and returns the version found in the data stream.

During serialization (read-only reflector), the specified version usually is stored as class version in the data stream. However, the serialized version can be overridden by setting a specific version for a certain class identifier, using desireClassVersions(). In that case, version() may return a different value than specified, and the class' reflect() method must implement reflection according to that version number. During deserialization (write-only reflector), the reflector reads the version found in the data stream and returns it. Providing the type of the caller enables defining separate version numbers for all base classes of an inherited type. Each class in the inheritance hierarchy can store and retrieve a version number independently of all its bases or sub-classes (assuming reflect() calls the reflect() method of the base class using reflectBase()). The type of the caller is also required to look up whether a specific version is desired (see desireClassVersions()). The sole purpose of the 'caller' parameter is to enable automatic deduction of the template parameter T. It can be omitted when T is given explicitly.

Usage:

template<typename Reflector>
void reflect(Reflector& r)
{
VersionType v = r.version(3, this); // specifies current version 3
// in serialization case, normally returns v=3, unless
// configured differently using desireClassVersions()
// in deserialization case, returns the version read from serialized data
// (or throws XIO if that is higher than 3, i.e. incompatible)
r.member("X", x, "");
if (version >= 2)
r.member("X2", x2, "");
if (version == 3)
...
}
Note
Specifying versions for serialized classes is optional.
requireVersion() and version() currently are supported by serialization reflectors only
VersionType version ( VersionType  version,
AcceptDesiredVersion  ,
const T *  caller = NULL 
)
inlineinherited

Extension of version() (see above), that additionally signals the reflector that the caller will properly handle a different version than the one it specifies itself.

void desireClassVersions ( const ClassVersionMap versions)
inlineinherited

Historically, classes have just been defining their current version themselves during serialization (the case where an object exists and its state is read out and serialized), by calling Reflector::version() with the respective version number parameter.

Different versions of a class were only considered during deserialization (i.e. restoring an object state from serialized data). In some cases it may be desirable, however, to serialize a different version (naturally, this can not be a higher version than the class implementation knows, only lower). This is useful e.g. to ensure serializing data that is compatible with a certain other (older) implementation, thus it can be deserialized by another instance.

For such cases, a mechanism is provided to generally enable requesting a specific version for any class from the reflector. This involves providing a map of class types (type names) to version numbers to the reflector. When a class contained in the map calls version() in its reflect() method, the call shall return the version number from the version map instead of the version number indicated by the class implementation itself. The class serialization must then follow that returned version.

A call to this method will always overwrite any previous setting of desired versions, i.e. the map is not cumulative.

Note
Since this is an addition to the ReflectorInterface in MIRABase 1.9.0, it cannot be ensured that all existing classes supported by the MIRA serialization framework (i.e., all classes for which exists an intrusive or non-intrusive reflect() method) properly support this mechanism of external version selection for serialization. In order to allow the reflector to be sure the class understands and observes a different version returned to it (or otherwise make the reflector refrain from changing the version indicated by the class and issue a warning instead), variants of the above version()/requireVersion() methods are introduced which implicitly provide that confirmation when called. See below.
void roproperty ( const char *  name,
const T &  member,
const char *  comment,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

A property that just reflects a runtime state of the object and can be displayed but not altered.

void roproperty ( const char *  name,
const std::string &  id,
const T &  member,
const char *  comment,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

Same as above, with an extra parameter for specifying the id explicitly if it differs from name.

void roproperty ( const char *  name,
Getter< T >  getter,
const char *  comment,
PropertyHint &&  hint = PropertyHint(),
ReflectCtrlFlags  flags = REFLECT_CTRLFLAG_NONE 
)
inlineinherited

Same as above, with a special getter method for reading the member.

See Also
Getters and Setters
void itemName ( const std::string &  name)
inlineinherited

If the currently reflected object is an item within a collection, this allows to specify an explicit name for that item.

This currently is interpreted by the PropertySerializer only.

void interface ( const char *  name)
inlineinherited

Indicates that the class implements the specified RPC interface.

If you indicate that your class implements the specified interface by calling this method in your reflect method, there is an implicit contract that your class provides all methods that are defined by that interface.

void method ( const char *  name,
Method  method,
const char *  comment,
const char *  paramName,
const char *  paramDescription,
paramSampleValue,
  ... 
)
inherited

Specifies that the class that is reflected provides a service through the specified static member function or free function.

The method will then be available for RPC calls. For each method its name (used to identify the method in RPC calls) and a comment that describes the method must be specified.

Parameters
nameThe name of the method (used for calling it)
methodThe static member function (or free function) that implements the method
commentA comment that describes the method
paramNameOptional additional argument(s) for the names of the method's parameters
paramDescriptionOptional additional argument(s) for the descriptions of the method's parameters.
paramSampleValueOptional additional argument(s) providing a sample value for each parameter. These are not default values, they are only used for documentation purpose, and should mainly serve to illustrate notation.

The optional parameter documentation arguments must be either a sequence of pairs of const char* values or a sequence of triplets, where each third value is a value of the respective method parameter's type. (name and description must both be provided, for all parameters or for none, and if sample values are to be added, they also need to be added for all parameters).

Examples:

r.method("myMethod1", myStaticMethod1, "static method that does something");
r.method("myMethod2", myStaticMethod2, "static method that does something else",
"x", "1st parameter", "y", "2nd parameter");
r.method("myMethod3", myStaticMethod3, "yet another static method"
"a", "parameter 1", ParamType1(...), "b", "parameter b", ParamType2(...));
void method ( const char *  name,
Method  method,
Class object,
const char *  comment,
const char *  paramName,
const char *  paramDescription,
paramSampleValue,
  ... 
)
inherited

Specifies that the class that is reflected provides a service through the specified non-static member function.

The method will then be available for RPC calls. For each method its name (used to identify the method in RPC calls) and a comment that describes the method must be specified.

Parameters
nameThe name of the method (used for calling it)
methodThe non-static member function (const or non-const) that implements the method
objectA pointer to the object on which the function is called (usually "this")
commentA comment that describes the method
paramNameOptional additional argument(s) for the names of the method's parameters
paramDescriptionOptional additional argument(s) for the descriptions of the method's parameters.
paramSampleValueOptional additional argument(s) providing a sample value for each parameter.

See above for documentation of optional parameter documentation arguments.

Example:

r.method("myMethod2", &MyClass::myMethod, this, "a non-static method");
void method ( const char *  name,
Method  method,
const char *  comment,
const char *  paramName,
const char *  paramDescription,
paramSampleValue,
  ... 
)
inherited

Specifies that the class that is reflected provides a service through the specified function wrapper.

The method will then be available for RPC calls. For each method its name (used to identify the method in RPC calls) and a comment that describes the method must be specified.

Parameters
nameThe name of the method (used for calling it)
methodThe function wrapper object that implements the method, e.g. created using boost::bind
commentA comment that describes the method
paramNameOptional additional argument(s) for the names of the method's parameters
paramDescriptionOptional additional argument(s) for the descriptions of the method's parameters.
paramSampleValueOptional additional argument(s) providing a sample value for each parameter.

See above for documentation of optional parameter documentation arguments.

Example:

r.method("myMethod3", boost::bind(&MyClass::myMethod, this, 1.23, 4, _1), "a function wrapper");
static bool usesHumanReadableIDs ( )
inlinestaticinherited

Returns true, if the concrete derived Reflector supports human readable IDs.

The return value of this method is known at compile time and hence the compiler is able to optimize the code depending on that value.

ReflectState preReflect ( const char *  context = "")
inlineinherited

If a reflector requires reflection barriers, preReflect() and postReflect() should be called before/after calling an external method within reflect(), to declare these barriers (such a 'barrier' is just a declaration to the reflector, in fact).

The base implementation is empty and should not actually be called (if a reflector needs these methods, it must provide own definitions).

Parameters
contextCan be used to provide context, e.g. name of the reflected class or function that is called. How this is used depends on the reflector implementation, e.g. MetaSerializer uses it to generate comments on data elements implicitly defined by preReflect.

The complete process of calling these methods is wrapped by MIRA_REFLECT_CALL. That macro should be used to simplify handling.

See requireReflectBarriers and ReflectState.

void postReflect ( const ReflectState &  )
inlineinherited

See preReflect for documentation.

static int checkForcedVersion ( const std::string &  variable)
inlinestaticprotectedinherited

Member Data Documentation

ObjectNameToInstanceMap mObjectNameToInstance
protectedinherited

maps full id names to instance pointers

ObjectsVector mObjects
protectedinherited

maps the ids to the instance pointers

std::stack<TrackingState> mTrackingStack
protectedinherited
BoostSharedPointerMap mBoostSharedPointers
protectedinherited
StdSharedPointerMap mStdSharedPointers
protectedinherited

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