PropertyNode.h

Go to the documentation of this file.

/*
 * Copyright (C) 2012 by
 *   MetraLabs GmbH (MLAB), GERMANY
 * and
 *   Neuroinformatics and Cognitive Robotics Labs (NICR) at TU Ilmenau, GERMANY
 * All rights reserved.
 *
 * Contact: info@mira-project.org
 *
 * Commercial Usage:
 *   Licensees holding valid commercial licenses may use this file in
 *   accordance with the commercial license agreement provided with the
 *   software or, alternatively, in accordance with the terms contained in
 *   a written agreement between you and MLAB or NICR.
 *
 * GNU General Public License Usage:
 *   Alternatively, this file may be used under the terms of the GNU
 *   General Public License version 3.0 as published by the Free Software
 *   Foundation and appearing in the file LICENSE.GPL3 included in the
 *   packaging of this file. Please review the following information to
 *   ensure the GNU General Public License version 3.0 requirements will be
 *   met: http://www.gnu.org/copyleft/gpl.html.
 *   Alternatively you may (at your option) use any later version of the GNU
 *   General Public License if such license has been publicly approved by
 *   MLAB and NICR (or its successors, if any).
 *
 * IN NO EVENT SHALL "MLAB" OR "NICR" BE LIABLE TO ANY PARTY FOR DIRECT,
 * INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
 * THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF "MLAB" OR
 * "NICR" HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * "MLAB" AND "NICR" SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
 * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND "MLAB" AND "NICR" HAVE NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS OR MODIFICATIONS.
 */

#ifndef _MIRA_PROPERTYNODE_H_
#define _MIRA_PROPERTYNODE_H_

#include <boost/interprocess/sync/scoped_lock.hpp>

#include <serialization/PropertyHint.h>
#include <serialization/adapters/std/pair>
#include <serialization/SplitReflect.h>
#include <serialization/JSONSerializer.h>
#include <platform/Typename.h>
#include <thread/ScopedAccess.h>
#include <utils/IsCopyAssignable.h>

namespace mira {


// forward declarations
class PropertySerializer;
class RootPropertyNode;

class PropertyNodeListener;
typedef std::set<PropertyNodeListener*> PropertyNodeListenerList;

template <typename T>
class TypedPropertyNode;

class PropertyNodeInfo
{
public:
    PropertyNodeInfo() {}
    PropertyNodeInfo(const std::string& id, const std::string& name,
                     const std::string& comment, const Typename& type,
                     bool isReadOnly, bool isVolatile) :
                        mID(id), mName(name), mComment(comment),
                        mType(type), mIsReadOnly(isReadOnly),
                        mIsVolatile(isVolatile) {}

    // special copy constructor, that clones the property hint
    PropertyNodeInfo(const PropertyNodeInfo& info) :
        mID(info.mID), mName(info.mName), mComment(info.mComment),
        mHint(info.mHint.clone()), mType(info.mType),
        mIsReadOnly(info.mIsReadOnly), mIsVolatile(info.mIsVolatile) {}

public:
    PropertyNodeInfo& operator=(const PropertyNodeInfo& info)
    {
        mID         = info.mID;
        mName       = info.mName;
        mComment    = info.mComment;
        mHint       = info.mHint.clone();
        mType       = info.mType;
        mIsReadOnly = info.mIsReadOnly;
        mIsVolatile = info.mIsVolatile;

        return *this;
    }

public:

    template<typename Reflector>
    void reflectCommon(Reflector& r)
    {
        serialization::VersionType v = r.version(2, this);
        r.member("ID", mID, "");
        r.member("Name", mName, "");
        r.member("Comment", mComment, "");
        r.member("Type", mType, "The typename");
        r.member("IsReadOnly", mIsReadOnly, "");
        if (v > 1)
            r.member("IsVolatile", mIsVolatile, "");
    }

    template<typename Reflector>
    void reflectRead(Reflector& r)
    {
        reflectCommon(r);
        PropertyHint::AttributeValueList hints = mHint.toList();
        r.member("Hint", hints, "The property hints", REFLECT_CTRLFLAG_TEMP_TRACKING);
    }

    template<typename Reflector>
    void reflectWrite(Reflector& r)
    {
        reflectCommon(r);
        PropertyHint::AttributeValueList hints;
        r.member("Hint", hints, "The property hints", REFLECT_CTRLFLAG_TEMP_TRACKING);
        mHint.fromList(hints);
    }

    MIRA_SPLIT_REFLECT_MEMBER

public:

    const std::string& id() const { return mID; }

    const std::string& name() const { return mName; }

    const std::string& comment() const { return mComment; }

    const Typename& type() const { return mType; }

    template <typename T>
    T getHint(const std::string& attribute, const T& defaultValue = T()) const {
        return mHint.get(attribute, defaultValue);
    }

    bool hasHint(const std::string& attribute) const {
        return mHint.has(attribute);
    }

    bool isReadOnly() const {return mIsReadOnly;}

    bool isVolatile() const {return mIsVolatile;}


protected:
    friend class PropertySerializer;

    void setName(const std::string& name) {
        mName = name;
    }

    void setVolatile(bool isVolatile) {
        mIsVolatile = isVolatile;
    }

protected:
    std::string  mID;      
    std::string  mName;    
    std::string  mComment; 
    PropertyHint mHint;    
    Typename     mType;    
    bool         mIsReadOnly; 
    bool         mIsVolatile; 
};

class PropertyNode : public PropertyNodeInfo
{
    friend class PropertySerializer; // needs to call addChild, etc

public:
    typedef std::vector<PropertyNode*> NodeList;

public:
    PropertyNode(const PropertyNodeInfo& info) :
        PropertyNodeInfo(info), mParent(NULL) {}

    PropertyNode(const std::string& id, const std::string& name,
                 const std::string& comment, const Typename& type,
                 bool isReadOnly, bool isVolatile) :
        PropertyNodeInfo(id, name, comment, type, isReadOnly, isVolatile),
        mParent(NULL) {}

    virtual ~PropertyNode();

public:

    virtual PropertyNode* parent() { return mParent; }

    virtual const PropertyNode* parent() const { return mParent; }

    virtual NodeList& children() { return mChildren; }

    virtual const NodeList& children() const { return mChildren; }

    const PropertyNode* findChildNode(const std::vector<std::string>& ids,
                                      std::size_t level = 0) const;

    PropertyNode* findChildNode(const std::vector<std::string>& ids,
                                std::size_t level = 0);

    const PropertyNode* findChildNode(const std::string& id) const;

    PropertyNode* findChildNode(const std::string& id);

public:

    std::string fullID(PropertyNode* p = NULL) const
    {
        std::string s = id();
        boost::algorithm::replace_all(s, ".", "\\");
        for(const PropertyNode* n = parent(); n!=NULL && n!=p; n=n->parent())
            s = boost::algorithm::replace_all_copy(n->id(), ".", "\\") + "." + s;
        return s;
    }

public:

    virtual void setFromJSON(const json::Value& value,
                             const Duration& timeout = Duration::milliseconds(100)) = 0;

    virtual json::Value getAsJSON() const = 0;

public:

    virtual void setFromString(const std::string& value,
                               const Duration& timeout = Duration::milliseconds(100));

    virtual std::string getAsString() const;

public:

    template <typename T>
    TypedPropertyNode<T>* toTyped();

    template <typename T>
    const TypedPropertyNode<T>* toTyped() const;

public:

    virtual void synchronize() = 0;

public:

    virtual RootPropertyNode* getRootNode();
    virtual const RootPropertyNode* getRootNode() const;

protected:

    void addChild(PropertyNode* child, int index = -1);

    void removeChild(int index) { removeChild(index, std::next(mChildren.begin(), index)); }

    void removeChildren(int index, int count) { removeChildren(index, std::next(mChildren.begin(), index), count); }

    void removeChild(int index, NodeList::iterator it);

    void removeChildren(int index, NodeList::iterator it, int count);

    void removeAllChildren();

    void moveChild(int index, int destination) {
        moveChild(index, std::next(mChildren.begin(), index),
                  destination, std::next(mChildren.begin(), destination)); }

    void moveChild(int index, NodeList::iterator it, int destination, NodeList::iterator destIt);

protected:

    virtual void beginAddChildren(PropertyNodeListenerList& listeners, int index, int count);
    virtual void endAddChildren(PropertyNodeListenerList& listeners);

    virtual void beginRemoveChildren(PropertyNodeListenerList& listeners, int index, NodeList::iterator it, int count);
    virtual void endRemoveChildren(PropertyNodeListenerList& listeners);

    virtual void beginMoveChildren(PropertyNodeListenerList& listeners, int index, NodeList::iterator it, int count, int destination);
    virtual void endMoveChildren(PropertyNodeListenerList& listeners);

private:

    PropertyNode* mParent;

    NodeList mChildren;
};


class PropertyNodeListener
{
public:
    virtual ~PropertyNodeListener() {}

    virtual void beginAddChildren(const PropertyNode* node, int index, int count) = 0;
    virtual void endAddChildren() = 0;

    virtual void beginRemoveChildren(const PropertyNode* node, int index, int count) = 0;
    virtual void endRemoveChildren() = 0;

    virtual void beginMoveChildren(const PropertyNode* node, int index, int count, int destination) = 0;
    virtual void endMoveChildren() = 0;
};


class RootPropertyNode : public PropertyNode
// Deriving from PropertyNode allows to use PropertyNode's mParent to refer
// to an instance of RootPropertyNode, instead of adding another pointer in
// PropertyNode (in each instance, even though it is only required in the root).
{
public:

    RootPropertyNode();

public:

    void addChild(PropertyNode* child, int index = -1);

    void removeChild(int index, NodeList::iterator it);
    void removeChild(int index);
    void removeAllChildren();

private:

    // These are not meant to ever be called
    void setFromJSON(const json::Value& value, const Duration& timeout) override;
    json::Value getAsJSON() const override;
    void synchronize() override;

protected:

    RootPropertyNode* getRootNode() override;
    const RootPropertyNode* getRootNode() const override;

public:

    void registerListener(PropertyNodeListener* listener);
    void unregisterListener(PropertyNodeListener* listener);

protected:
    friend class PropertyNode;
    typedef ProtecteeMixin<PropertyNodeListenerList> ProtectedListenerList;

    ScopedAccess<ProtectedListenerList> getListeners(bool alreadyLocked = false);

private:
    ProtectedListenerList mListeners;

public:
    using MutexType = boost::recursive_timed_mutex;
    using LockType = boost::interprocess::scoped_lock<MutexType>;

    LockType getLock();

    LockType tryGetLock(const Duration& timeout = Duration::milliseconds(10));

private:
    MutexType mMutex;
};


template <typename T>
class TypedPropertyNode : public PropertyNode
{
public:

    typedef T value_type; // STL conform typedef

public:

    TypedPropertyNode(const PropertyNodeInfo& info) :
        PropertyNode(info) {
        assert(info.type()==typeName<value_type>());
    }

    TypedPropertyNode(const std::string& id, const std::string& name,
                      const std::string& comment, bool isReadOnly, bool isVolatile) :
        PropertyNode(id, name, comment, typeName<value_type>(), isReadOnly, isVolatile) {}

public:

    virtual void set(const value_type& value,
                     const Duration& timeout = Duration::milliseconds(100)) = 0;

    virtual value_type get() const = 0;

protected:
    RootPropertyNode::LockType getLock(RootPropertyNode* root) {
        return root ? root->getLock() : RootPropertyNode::LockType();
    }

    RootPropertyNode::LockType getLock() {
        return getLock(getRootNode());
    }

    RootPropertyNode::LockType tryGetLock(RootPropertyNode* root, const Duration& timeout) {
        return root ? root->tryGetLock(timeout) : RootPropertyNode::LockType();
    }

    RootPropertyNode::LockType tryGetLock(const Duration& timeout) {
        return tryGetLock(getRootNode(), timeout);
    }

protected:
    template<typename Type = T>
    static constexpr bool mayHaveChildNodes();
    
};


// LockedPropertyNodeAccess encapsulates locking all access to a TypedPropertyNode's
// internal reference/pointer/accessor.
// Optionally, when (const!) access is attempted but not possible (because the node is locked
// by another thread), it can return a backup of the previous value. The backup value is
// automatically updated with each successful read (const access).

template <typename NodeType, typename ValueType>
class LockedPropertyNodeAccessCommon : boost::noncopyable
{
public:
    struct NoLock{};
protected:
    LockedPropertyNodeAccessCommon(NodeType* parent, const ValueType& ref)
        : p(parent), r(ref), needLock(false)
    {
        if (p->isVolatile()) {
            if (auto root = parent->getRootNode()) {
                needLock = true;
                lock = root->tryGetLock();
            }
        }
    }

    LockedPropertyNodeAccessCommon(NodeType* parent, const ValueType& ref, NoLock)
        : p(parent), r(ref), needLock(false) {}

protected:
    NodeType* p;
    const ValueType& r;
    bool needLock;
    boost::interprocess::scoped_lock<RootPropertyNode::MutexType> lock;
};

template <typename NodeType, typename ValueType,
          bool ValueTypePointer = false, bool UseBackup = false>
class LockedPropertyNodeAccess : public LockedPropertyNodeAccessCommon<NodeType, ValueType>
{
public:
    using Base = LockedPropertyNodeAccessCommon<NodeType, ValueType>;
    using NoLock = typename Base::NoLock;

public:
    LockedPropertyNodeAccess(NodeType* parent, const ValueType& ref)
        : LockedPropertyNodeAccessCommon<NodeType, ValueType>(parent, ref) {}

    LockedPropertyNodeAccess(NodeType* parent, const ValueType& ref, NoLock)
        : LockedPropertyNodeAccessCommon<NodeType, ValueType>(parent, ref, NoLock()) {}

public:
    const ValueType& operator*() const {
        if (this->needLock && !this->lock.owns())
            MIRA_THROW(XIO, "Property is not available (yet?)")

        return this->r;
    }

    ValueType& operator*() {
        if (this->needLock && !this->lock.owns())
            MIRA_THROW(XIO, "PropertyNode is locked by another thread");

        return const_cast<ValueType&>(this->r);
    }
};

// specialize for ValueTypePointer=false, UseBackup=true --> invalid
template <typename NodeType, typename ValueType>
class LockedPropertyNodeAccess<NodeType, ValueType, false, true> {
    static_assert(sizeof(ValueType)==0, // assertion must depend on template parameter!
                  "LockedPropertyNodeAccess: combination ValueTypePointer=false, UseBackup=true not implemented");
};

// specialize for ValueTypePointer=true, UseBackup=false
template <typename NodeType, typename ValueType>
class LockedPropertyNodeAccess<NodeType, ValueType, true, false>
    : public LockedPropertyNodeAccessCommon<NodeType, ValueType*>
{
protected:
    typedef ValueType* PointerType;

public:
    using Base = LockedPropertyNodeAccessCommon<NodeType, ValueType*>;
    using NoLock = typename Base::NoLock;

public:
    LockedPropertyNodeAccess(NodeType* parent, const PointerType& ref)
        : LockedPropertyNodeAccessCommon<NodeType, PointerType>(parent, ref) {}

    LockedPropertyNodeAccess(NodeType* parent, const PointerType& ref, NoLock)
        : LockedPropertyNodeAccessCommon<NodeType, PointerType>(parent, ref, NoLock()) {}

public:
    const ValueType& operator*() const {
        if (this->needLock && !this->lock.owns())
            MIRA_THROW(XIO, "Property is not available (yet?)")

        return *this->r;
    }

    ValueType& operator*() {
        if (this->needLock && !this->lock.owns())
            MIRA_THROW(XIO, "PropertyNode is locked by another thread");

        return const_cast<ValueType&>(*this->r);
    }
};

// specialize for ValueTypePointer=true, UseBackup=true
template <typename NodeType, typename ValueType>
class LockedPropertyNodeAccess<NodeType, ValueType, true, true>
    : public LockedPropertyNodeAccessCommon<NodeType, ValueType*>
{
protected:
    typedef ValueType* PointerType;
public:
    using Base = LockedPropertyNodeAccessCommon<NodeType, ValueType*>;
    using NoLock = typename Base::NoLock;

public:
    LockedPropertyNodeAccess(NodeType* parent, const PointerType& ref)
        : LockedPropertyNodeAccessCommon<NodeType, PointerType>(parent, ref) {}

    LockedPropertyNodeAccess(NodeType* parent, const PointerType& ref, NoLock)
        : LockedPropertyNodeAccessCommon<NodeType, PointerType>(parent, ref, NoLock()) {}

public:
    const ValueType& operator*() const {
        if (this->needLock && !this->lock.owns()) {

            if (this->p->mBackupValue)
                return *this->p->mBackupValue;

            MIRA_THROW(XIO, "Property is not available (yet?)")
        }

        this->p->mBackupValue.reset(new ValueType(*this->r));
        return *this->r;
    }

    ValueType& operator*() {
        if (this->needLock && !this->lock.owns())
            MIRA_THROW(XIO, "PropertyNode is locked by another thread");

        return const_cast<ValueType&>(*this->r);
    }
};


template <typename T>
class TypedPropertyNodeImplGetSetMixinBase : public TypedPropertyNode<T>
{
    typedef TypedPropertyNode<T> Base;
public:
    typedef typename Base::value_type value_type;
public:
    TypedPropertyNodeImplGetSetMixinBase(const std::string& id, const std::string& name,
                                         const std::string& comment, value_type& value,
                                         bool isReadOnly, bool isVolatile) :
        Base(id, name, comment, isReadOnly, isVolatile), mValue(&value) {}

protected:
    // all access to mValue (except update()) goes through LockedAccess,
    // ensures locking the PropertyNode if required
    typedef LockedPropertyNodeAccess<TypedPropertyNodeImplGetSetMixinBase<T>, value_type, true,
                                     IsCopyAssignable<value_type>::value> LockedAccess;
    friend LockedAccess;
    using NoLock = typename LockedAccess::NoLock;

    const LockedAccess valueAccess() const {
        return LockedAccess(const_cast<TypedPropertyNodeImplGetSetMixinBase*>(this), mValue);
    }

    LockedAccess valueAccess() {
        return LockedAccess(this, mValue);
    }

    const LockedAccess valueAccess(NoLock) const {
        return LockedAccess(const_cast<TypedPropertyNodeImplGetSetMixinBase*>(this), mValue, NoLock());
    }

    LockedAccess valueAccess(NoLock) {
        return LockedAccess(this, mValue, NoLock());
    }

protected:

    void setValue(value_type& nodeValue, const value_type& newValue) {
        nodeValue = newValue;
    }

protected:
    friend class PropertySerializer;

    void update(T& value) {
        mValue = &value;
    }

private:
    value_type* mValue;
    std::unique_ptr<value_type> mBackupValue; // value_type may not be default constructible
};

template <typename T, bool /* = true */>
class TypedPropertyNodeImplGetSetMixin : public TypedPropertyNodeImplGetSetMixinBase<T>
{
    typedef TypedPropertyNodeImplGetSetMixinBase<T> Base;
public:
    typedef typename Base::value_type value_type;
public:
    TypedPropertyNodeImplGetSetMixin(const std::string& id, const std::string& name,
                                     const std::string& comment, value_type& value,
                                     bool isReadOnly, bool isVolatile) :
        Base(id, name, comment, value, isReadOnly, isVolatile) {}

protected:

    void setValue(value_type& nodeValue, const value_type& newValue) {
        Base::setValue(nodeValue, newValue);
    }

public:

    value_type get() const override {
        return *Base::valueAccess();
    }
};

template <typename T>
class TypedPropertyNodeImplGetSetMixin<T,false> : public TypedPropertyNodeImplGetSetMixinBase<T>
{
    typedef TypedPropertyNodeImplGetSetMixinBase<T> Base;
public:
    typedef typename Base::value_type value_type;
public:
    TypedPropertyNodeImplGetSetMixin(const std::string& id, const std::string& name,
                                     const std::string& comment, value_type& value,
                                     bool isReadOnly, bool isVolatile) :
        Base(id, name, comment, value, isReadOnly, isVolatile) {}

protected:

    void setValue(value_type& nodeValue, const value_type& newValue) {
        MIRA_THROW(XLogical, "Cannot set value of property, since the underlying class does not provide an assignment operator");
    }

public:

    value_type get() const override {
        MIRA_THROW(XLogical, "Cannot get value of property, since the underlying class does not provide an assignment operator");
    }
};

template <typename T>
class TypedPropertyNodeImpl : public TypedPropertyNodeImplGetSetMixin<T,IsCopyAssignable<T>::value>
{
    typedef TypedPropertyNodeImplGetSetMixin<T,IsCopyAssignable<T>::value> Base;
public:
    typedef typename Base::value_type value_type;
    using NoLock = typename Base::NoLock;
public:
    TypedPropertyNodeImpl(const std::string& id, const std::string& name,
                          const std::string& comment, value_type& value,
                          bool isReadOnly, bool isVolatile) :
        Base(id, name, comment, value, isReadOnly, isVolatile) {}
public:

    void setFromJSON(const json::Value& json, const Duration& timeout) override {
        if(this->isReadOnly())
            MIRA_THROW(XLogical, "Cannot set value of read-only property.");

        JSONDeserializer ds(json);

        // atomic types do not need to call synchronize()
        if constexpr(!Base::mayHaveChildNodes()) {
            ds.deserialize(*this->valueAccess());
            return;
        }

        auto root = this->getRootNode();
        auto lock = this->tryGetLock(root, timeout);
        if (root && !lock.owns())
            MIRA_THROW(XIO, "PropertyNode is locked by another thread");

        auto nodeValueAccess = this->valueAccess(NoLock());
        ds.deserialize(*nodeValueAccess);
        synchronize(*nodeValueAccess); // synchronizes this node and its children with the
                                       // actual underlying data representation that
                                       // might have been changed by the above deserialization
    }

    json::Value getAsJSON() const override {
        JSONSerializer s(true);
        return s.serialize(*this->valueAccess());
    }

public:

    void set(const value_type& newValue, const Duration& timeout) override{
        if(this->isReadOnly())
            MIRA_THROW(XLogical, "Cannot set value of read-only property.");

        // atomic types do not need to call synchronize()
        if constexpr(!Base::mayHaveChildNodes()) {
            Base::setValue(*this->valueAccess(), newValue);
            return;
        }

        auto root = this->getRootNode();
        auto lock = this->tryGetLock(root, timeout);
        if (root && !lock.owns())
            MIRA_THROW(XIO, "PropertyNode is locked by another thread");

        auto nodeValueAccess = this->valueAccess(NoLock());
        Base::setValue(*nodeValueAccess, newValue);
        synchronize(*nodeValueAccess); // synchronizes this node and its children with the
                                       // actual underlying data representation that
                                       // might have been changed by the above assignment
    }

    // implemented in GetSetMixin
    //value_type get() const override;

public:
    void synchronize() override
    {
        auto lock = this->getLock();
        return synchronize(*this->valueAccess(NoLock()));
    }

private:
    void synchronize(value_type& nodeValue);
};


template <typename T>
class TypedPropertyNodeImpl<T*> : public TypedPropertyNode<T*>
{
    typedef TypedPropertyNode<T*> Base;
public:
    typedef typename Base::value_type value_type;
public:
    TypedPropertyNodeImpl(const std::string& id, const std::string& name,
                          const std::string& comment, const value_type& value,
                          bool isReadOnly, bool isVolatile) :
        Base(id, name, comment, isReadOnly, isVolatile), mPointer(value) {}

protected:
    // all access to mPointer (except update()) goes through LockedAccess,
    // ensures locking if required
    typedef LockedPropertyNodeAccess<TypedPropertyNodeImpl<T*>, value_type> LockedAccess;
    using NoLock = typename LockedAccess::NoLock;

    const LockedAccess pointerAccess() const {
        return LockedAccess(const_cast<TypedPropertyNodeImpl*>(this), mPointer);
    }

    LockedAccess pointerAccess() {
        return LockedAccess(this, mPointer);
    }

    const LockedAccess pointerAccess(NoLock) const {
        return LockedAccess(const_cast<TypedPropertyNodeImpl*>(this), mPointer, NoLock());
    }

    LockedAccess pointerAccess(NoLock) {
        return LockedAccess(this, mPointer, NoLock());
    }

public:
    void setFromJSON(const json::Value& json, const Duration& timeout) override {
        if(this->isReadOnly())
            MIRA_THROW(XLogical, "Cannot set value of read-only property.");

        JSONDeserializer ds(json);

        // atomic types do not need to call synchronize()
        if constexpr(!Base::template mayHaveChildNodes<T>()) {
            ds.deserialize(*pointerAccess());
            return;
        }

        auto root = this->getRootNode();
        auto lock = this->tryGetLock(root, timeout);
        if (root && !lock.owns())
            MIRA_THROW(XIO, "PropertyNode is locked by another thread");

        auto nodePointerAccess = pointerAccess(NoLock());
        ds.deserialize(*nodePointerAccess);
        synchronize(*nodePointerAccess); // synchronizes this node and its children with the
                                         // actual underlying data representation that
                                         // might have been changed by the above deserialization
    }
    json::Value getAsJSON() const override {
        JSONSerializer s(true);
        return s.serialize(*pointerAccess());
    }
public:
    void set(const value_type& newPointer, const Duration& timeout) override {
        if(this->isReadOnly())
            MIRA_THROW(XLogical, "Cannot set value of read-only property.");

        // atomic types do not need to call synchronize()
        if constexpr(!Base::template mayHaveChildNodes<T>()) {
            *pointerAccess() = newPointer;
            return;
        }

        auto root = this->getRootNode();
        auto lock = this->tryGetLock(root, timeout);
        if (root && !lock.owns())
            MIRA_THROW(XIO, "PropertyNode is locked by another thread");

        auto nodePointerAccess = pointerAccess(NoLock());
        *nodePointerAccess = newPointer;
        synchronize(*nodePointerAccess); // synchronizes this node and its children with the
                                         // actual underlying data representation that
                                         // might have been changed by the above assignment
    }
    value_type get() const override {
        return *pointerAccess();
    }
protected:
    friend class PropertySerializer;

    void update(T* value) {
        mPointer = value;
    }
public:
    void synchronize() override
    {
        auto lock = this->getLock();
        return synchronize(*this->pointerAccess(NoLock()));
    }
private:
    void synchronize(value_type& nodePointer);
private:
    value_type mPointer;
};


template <typename Getter, typename Setter>
class TypedPropertyNodeImpl<Accessor<Getter,Setter>> :
        public TypedPropertyNode<typename Accessor<Getter,Setter>::value_type>
{
    typedef typename Accessor<Getter,Setter>::value_type T;
    typedef Accessor<Getter,Setter> AccessorType;
    typedef TypedPropertyNode<T> Base;
public:
    typedef typename Base::value_type value_type;
public:
    TypedPropertyNodeImpl(const std::string& id, const std::string& name,
                          const std::string& comment, const AccessorType& value,
                          bool isReadOnly, bool isVolatile) :
        Base(id, name, comment, isReadOnly, isVolatile), mAccessor(value) {}

protected:
    // all access to mAccessor (except update()) goes through LockedAccess,
    // ensures locking if required
    typedef LockedPropertyNodeAccess<TypedPropertyNodeImpl<Accessor<Getter,Setter>>, AccessorType> LockedAccess;
    using NoLock = typename LockedAccess::NoLock;

    const LockedAccess accessorAccess() const {
        return LockedAccess(const_cast<TypedPropertyNodeImpl*>(this), mAccessor);
    }

    LockedAccess accessorAccess() {
        return LockedAccess(this, mAccessor);
    }

    const LockedAccess accessorAccess(NoLock) const {
        return LockedAccess(const_cast<TypedPropertyNodeImpl*>(this), mAccessor, NoLock());
    }

    LockedAccess accessorAccess(NoLock) {
        return LockedAccess(this, mAccessor, NoLock());
    }

public:

    void setFromJSON(const json::Value& json, const Duration& timeout) override {
        if(this->isReadOnly())
            MIRA_THROW(XLogical, "Cannot set value of read-only property.");

        JSONDeserializer ds(json);

        // atomic types do not need to call synchronize()
        if constexpr(!Base::template mayHaveChildNodes<T>()) {
            ds.deserialize(*accessorAccess());
            return;
        }

        auto root = this->getRootNode();
        auto lock = this->tryGetLock(root, timeout);
        if (root && !lock.owns())
            MIRA_THROW(XIO, "PropertyNode is locked by another thread");

        auto nodeAccessorAccess = accessorAccess(NoLock());
        ds.deserialize(*nodeAccessorAccess);
        synchronize(*nodeAccessorAccess); // synchronizes this node and its children with the
                                          // actual underlying data representation that
                                          // might have been changed by the above deserialization
    }

    json::Value getAsJSON() const override {
        JSONSerializer s(true);
        return s.serialize(*accessorAccess());
    }

public:

    void set(const value_type& newValue, const Duration& timeout) override {
        if(this->isReadOnly())
            MIRA_THROW(XLogical, "Cannot set value of read-only property.");

        // atomic types do not need to call synchronize()
        if constexpr(!Base::template mayHaveChildNodes<T>()) {
            (*accessorAccess()).set(newValue);
            return;
        }

        auto root = this->getRootNode();
        auto lock = this->tryGetLock(root, timeout);
        if (root && !lock.owns())
            MIRA_THROW(XIO, "PropertyNode is locked by another thread");

        auto nodeAccessorAccess = accessorAccess(NoLock());
        (*nodeAccessorAccess).set(newValue);
        synchronize(*nodeAccessorAccess); // synchronizes this node and its children with the
                                          // actual underlying data representation that
                                          // might have been changed by the above assignment
    }

    value_type get() const override {
        return (*accessorAccess()).get();
    }

protected:
    friend class PropertySerializer;

    void update(AccessorType& value) {
        mAccessor = value;
    }
public:
    void synchronize() override
    {
        auto lock = this->getLock();
        return synchronize(*this->accessorAccess(NoLock()));
    }
private:
    void synchronize(AccessorType& nodeAccessor);
private:
    AccessorType mAccessor;
};


// Support for remote property management

class AbstractRemotePropertyNode : public PropertyNode
{
public:
    AbstractRemotePropertyNode(const PropertyNodeInfo& info) :
        PropertyNode(info), mTypedNode(NULL) {}

    virtual ~AbstractRemotePropertyNode() {
        delete mTypedNode;
    }

public:

    void addChild(PropertyNode* child, int index = -1) {
        PropertyNode::addChild(child, index);
    }

public:

    template <typename T>
    TypedPropertyNode<T>* toTyped();

private:

    PropertyNode* mTypedNode;
};

template <typename T>
class TypedRemotePropertyNode : public TypedPropertyNode<T>
{
public:
    typedef TypedPropertyNode<T> Base;
    typedef typename Base::value_type value_type;

public:

    TypedRemotePropertyNode(AbstractRemotePropertyNode* node) :
        Base(*node), mNode(node) {}

public:
    // implementation of PropertyNode that delegates to the "real"
    // RemotePropertyNode
    void setFromJSON(const json::Value& node, const Duration& timeout) override { mNode->setFromJSON(node, timeout); }
    json::Value getAsJSON() const override { return mNode->getAsJSON(); }

public:
    // the following methods of PropertyNode must be delegated to the "real"
    // RemotePropertyNode, that has the parent and the children.
    PropertyNode* parent() override { return mNode->parent();}
    const PropertyNode* parent() const override { return mNode->parent(); }
    PropertyNode::NodeList& children() override { return mNode->children(); }
    const PropertyNode::NodeList& children() const override { return mNode->children(); }
    void synchronize() override {
        MIRA_THROW(XNotImplemented, "TypedRemotePropertyNode::synchronize() not implemented!");
    }

public:
    // implementation of TypedPropertyNode

    void set(const value_type& value, const Duration& timeout) override
    {
        try {
            // serialize the value to json and set it remotely via setFromJSON()
            JSONSerializer s;
            json::Value jsonval = s.serialize(value);
            setFromJSON(jsonval, timeout);
        } catch(std::exception& ex) {
            MIRA_THROW(XIO, "Failed to convert value to json: " << ex.what())
        }
    }

    value_type get() const override
    {
        try {
            // get the value remotely via getAsJSON
            json::Value jsonval = getAsJSON();
            // and deserialize it into the value
            value_type value;
            JSONDeserializer ds(jsonval);
            ds.deserialize(value);
            return value;
        } catch(std::exception& ex) {
            MIRA_THROW(XIO, "Failed to obtain remote value: " << ex.what())
        }
    }

private:
    AbstractRemotePropertyNode* mNode;
};


// implementations of the PropertyNode toTyped methods
template <typename T>
inline TypedPropertyNode<T>* PropertyNode::toTyped() {

    // try a direct cast to the desired type
    TypedPropertyNode<T>* node = dynamic_cast<TypedPropertyNode<T>*>(this);
    if(node!=NULL)
        return node; // success

    // if the above cast failed, the property could still be a remote property
    AbstractRemotePropertyNode* remoteNode = dynamic_cast<AbstractRemotePropertyNode*>(this);
    if(remoteNode!=NULL)
        return remoteNode->toTyped<T>();

    // otherwise we cannot cast
    MIRA_THROW(XBadCast, "Cannot cast PropertyNode which is of "
                         "type '" << mType << "' to requested type '"
                         << typeName<T>() << "'");
}

template <typename T>
inline const TypedPropertyNode<T>* PropertyNode::toTyped() const {
    PropertyNode* This = const_cast<PropertyNode*>(this);
    return This->toTyped<T>();
}


template <typename T>
inline TypedPropertyNode<T>* AbstractRemotePropertyNode::toTyped()
{
    if(mTypedNode) {
        TypedPropertyNode<T>* node = dynamic_cast<TypedPropertyNode<T>*>(mTypedNode);
        if(node==NULL)
            MIRA_THROW(XBadCast, "Cannot cast PropertyNode which is of "
                                 "type '" << mType << "' to requested type '"
                                 << typeName<T>() << "'");
        return node;
    } else {
        if(mType != typeName<T>())
            MIRA_THROW(XBadCast, "Cannot cast remote PropertyNode which is of "
                                 "type '" << mType << "' to requested type '"
                                 << typeName<T>() << "'");

        TypedRemotePropertyNode<T>* node = new TypedRemotePropertyNode<T>(this);
        mTypedNode = node;

        return node;
    }
}


} // namespace

#endif