vos/corelibs/vos/metaobject.hh

Go to the documentation of this file.

/*
    This file is part of the Virtual Object System of
    the Interreality project (http://interreality.org).

    Copyright (C) 2001-2003 Peter Amstutz

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA

    Peter Amstutz <tetron@interreality.org>
*/
#ifndef _METAOBJECT_HH_
#define _METAOBJECT_HH_

#include <stdexcept>
#include <typeinfo>
#include <vos/corelibs/vos/vosdefs.hh>
#include <vos/corelibs/vos/vobject.hh>

namespace VOS
{
/** @class MetaObject metaobject.hh vos/corelibs/vos/metaobject.hh
  
    This class is responsible for managing a group of object
    extensions under a single logical Vobject.  Messages sent to it
    using sendMessage() and sendUpdateMessage() are propagated to any
    extension plugins which have been attached to it.  Metaobjects
    allow you to switch between multiple interfaces using meta_cast,
    allowing you to request a certain C++ class interface such as
    Property or Talkative from a given Vobject, if the Vobject has
    that type.
 */
class VOS_API MetaObject : public virtual Vobject
{
private:
    std::deque<MetaObject*> typehandlers;    ///< Type extensions for this metaobject.
    std::set<std::string> touchedNonces;
protected:
    MetaObject(MetaObject* superobject);
    MetaObject* superobject;

    /** This is where you put type-handler specific save state code.
        @param output The messageblock to append your messages to
        @param types The types for the object that should be output as
        part of this save state. Some save state handlers may want to
        modify this.
        @see Vobject::saveState
    */
    virtual void doSaveState(MessageBlock& output, std::set<std::string>& types, bool portable);

    /** This is where you put type-handler specific code to respond to an excise().
        It will be called exactly once.
    */
    virtual void doExcise();

public:
    /** destructor */
    virtual ~MetaObject();

    /** Add an instantiated extension object to this metaobject.  End
        users generally shouldn't need to do this, use
        MetaFactory::extendLocalObject() instead.
        @note Extension object is @em deleted when the destructor for
        this metaobject is called.
        @param moe the metaobject to be added
    */
    virtual void addObjectExtension(MetaObject* moe);

    /** @returns the specific MOS type name that represents the MOS
        interface this object is supplying.
    */
    virtual const std::string getType();

    /** Get the superobject (the object immediately
        containing this metaobject)
        @returns the superobject
    */
    MetaObject* getSuperObject();

    /** Get the 'top' superobject, that is, the root of the metaobject tree.
        @returns the top superobject
    */
    MetaObject* getTopObject();

    /** Get a vector of the extension object contained in this metaobject.
        @returns a list of extensions
     */
    const std::deque<MetaObject*>& getTypeHandlers();

    /** Initialize the security policy of a newly created local metaobject.
        @param requester the object that requested the creation of this type extension
     */
    virtual void initializeSecurity(Vobject& requester);

    virtual const std::string& getName();
    virtual Site& getSite();
    virtual const URL& getURL();
    virtual bool isLocal();
    virtual bool isRemote();
    virtual const TypeSet& getTypes() throw (AccessControlError, RemoteError);
    virtual void addType(const std::string& s);
    virtual const ParentSet& getParents()
        throw (AccessControlError, RemoteError);
    virtual const ChildList& getChildren()
        throw (AccessControlError, RemoteError);

    virtual void sendMessage(Message* m);
    virtual void sendMessage(MessageBlock* m);
    virtual Message* receiveMessage() throw (MessageQueueEmptyError);
    virtual bool hasMessageAvailable();

    virtual void sendUpdateMessage(Message* m);
    virtual Message* receiveUpdateMessage() throw (MessageQueueEmptyError);
    virtual bool hasUpdateMessageAvailable();

    virtual Vobject& findObject(const std::string& path)
        throw (NoSuchSiteError, NoSuchObjectError, URL::BadURLError, AccessControlError, RemoteError);
    virtual ParentChildRelation& findChild(const std::string& path)
        throw (NoSuchObjectError, AccessControlError, RemoteError);
    virtual Vobject::ParentChildRelation& findParent(Vobject& parent)
        throw (NoSuchObjectError, AccessControlError, RemoteError);
    virtual void setChild(int position, const std::string& contextual_name, Vobject* child)
        throw (AccessControlError, RemoteError);
    virtual void insertChild(int position, const std::string& contextual_name, Vobject* child)
        throw (AccessControlError, RemoteError);
    virtual void removeChild(int position)
        throw (AccessControlError, RemoteError);

    virtual void addTypeListener(TypeChangeListener* tl, bool notifyImmediately = true);
    virtual void addParentListener(ParentChangeListener* pl, bool notifyImmediately = true);
    virtual void addChildListener(ChildChangeListener* cl, bool notifyImmediately = true);
    virtual void removeTypeListener(TypeChangeListener* tl);
    virtual void removeParentListener(ParentChangeListener* pl);
    virtual void removeChildListener(ChildChangeListener* cl);

    virtual void saveState(MessageBlock& output, std::set<std::string>& types, bool portable);

    virtual void addFlag(const std::string& flag);
    virtual void removeFlag(const std::string& flag);
    virtual bool checkFlag(const std::string& flag);

    /** @note Important: this is delegated to the top object, and
        means you want the entire logical Vobject to go away!  If
        called on an object with no superobject, it calls doExcise() on its type
        handlers.  Type implementation specific cleanup code (such as
        calling excise on certain children no longer needed) should
        override doExcise().
    */
    virtual void excise();

    /** Note that this means you have a handle on the entire logical object! */
    virtual void acquire();

    /** Note that this means you are releasing the entire logical object! */
    virtual void release();

    /** Note that this counts for the entire logical object! */
    virtual int getCount();

    /** Some MetaObject subclasses provide an initialize method to
     * create required subobjects with default values, to set a default
     * property access control policy, etc.
     * Calling this method on a top level MetaObject will call initialize()
     * on each of it's type extensions. e.g.:
     * @code
     * MetaObject* foo = site->createMetaObject("foo", typeid(A3DL::Cube).name(), typeid(Hypercard).name(), 0);
     * foo->initialize();
     *                       // calls A3DL::Cube::initialize() and  Hypercard::initialize()
     * MetaObject::meta_cast<Hypercard*>(foo)->initialize();
     *                       // just call Hypercard::initialize().
     * @endcode
     */
    virtual void initialize();

    /** A specialized cast allowing you to switch between different
        extension plugins in the same logical object.  It first attempts to
        dynamic_cast the Vobject into a MetaObject, and then searches the
        metaobject type tree of this for an instance of an extension
        that satisfied the requested type.
        @param v the object to be cast
    */
    template<class C> static C meta_cast(Vobject* v)
        {
            if(C ret = dynamic_cast<C>(v)) return ret;
            else if(MetaObject* m = dynamic_cast<MetaObject*>(v)) return meta_cast<C>(m);
            else return 0;
        }

    /** A specialized cast allowing you to switch between different
        extension plugins in the same logical object.  It first attempts to
        dynamic_cast the Vobject into a MetaObject, and then searches the
        metaobject type tree of this for an instance of an extension
        that satisfied the requested type.
        @param v the object to be cast
    */
    template<class C> static C meta_cast(Vobject& v) throw (bad_cast) 
    {
        try {
            C ret = dynamic_cast<C>(v);
            return ret;
        } catch(bad_cast) {
            MetaObject& m = dynamic_cast<MetaObject&>(v);
            return meta_cast<C>(m);
        }
    }

    /** A specialized cast allowing you to switch between different
        extension plugins in the same logical object. It searches the
        metaobject type tree of this for an instance of an extension
        that satisfied the requested type.  You can cast any member of
        a logical object to any other member.  For example:
        @code
        LocalMetaObject* l = MetaFactory::createLocalMetaObject(mysite,
                                                                typeid(Property).name(),
                                                                typeid(World).name(),
                                                                0);
        Property* p = MetaObject::meta_cast<Property*>(l);
        World* w = MetaObject::meta_cast<World*>(p);
        @endcode
        @param v the object to be cast
        @param fromsuper Whether this search invocation started from
        the root, to avoid backtracking.  You don't (and shouldn't) need to specify this.
    */
    template<class C> static C meta_cast(MetaObject* v, bool fromsuper=false)
        {
            if(!fromsuper && v->superobject != 0) return meta_cast<C>(v->superobject, false);
            if(C ret = dynamic_cast<C>(v)) {
                return ret;
            } else {
                for(std::deque<MetaObject*>::iterator i=v->typehandlers.begin();
                    i != v->typehandlers.end();
                    i++) {
                    if(C ret = meta_cast<C>(*i, true)) return ret;
                }
            }
            return 0;
        }

    /** A specialized cast allowing you to switch between different
        extension plugins in the same logical object.  It searches the
        metaobject type tree of this for an instance of an extension
        that satisfied the requested type.  You can cast any member of
        a logical object to any other member.  For example:
        @code
        LocalMetaObject* l = MetaFactory::createLocalMetaObject(mysite, typeid(Property).name(),
                                                                typeid(World).name(), 0);
        Property& p = MetaObject::meta_cast<Property&>(*l);
        World& w = MetaObject::meta_cast<World&>(p);
        @endcode
        @param v the object to be cast
        @param fromsuper Whether this search invocation started from
        the root, to avoid backtracking.  You don't (and shouldn't) need to specify this.  */
    template<class C> static C meta_cast(MetaObject& v, bool fromsuper=false) throw (bad_cast)
    {
        if(!fromsuper && v.superobject != 0) {
             return meta_cast<C>(*(v.superobject), false);
        }
        try {
            return dynamic_cast<C>(v);
        } catch(bad_cast) {
            for(std::deque<MetaObject*>::iterator i=v.typehandlers.begin();
                i != v.typehandlers.end();
                i++) {
                try {
                    return meta_cast<C>(**i, true);
                } catch(bad_cast){
                }
            }
        } catch(runtime_error) {
        } catch(...) {
        }
        throw bad_cast();
    }

    template<class T> void addMessageHandler(const std::string& method, T* theobj,
                                             void (T::* MessageHandler)(Message*),
                                             bool addExHandler = false)
        {
            dynamic_cast<VobjectImplementation*>(getTopObject())->addMessageHandler<T>(method, theobj,
                                                                                       MessageHandler, addExHandler);
        };
    template<class T> void addUpdateHandler(const std::string& method, T* theobj,
                                            void (T::* MessageHandler)(Message*),
                                            bool addExHandler = false)
        {
            dynamic_cast<VobjectImplementation*>(getTopObject())->addUpdateHandler<T>(method, theobj,
                                                                                      MessageHandler, addExHandler);
        };
    template<class T> void removeMessageHandler(const std::string& method, T* theobj,
                                                void (T::* MessageHandler)(Message*))
        {
            dynamic_cast<VobjectImplementation*>(getTopObject())->removeMessageHandler<T>(method, theobj, MessageHandler);
        };
    template<class T> void removeUpdateHandler(const std::string& method, T* theobj,
                                               void (T::* MessageHandler)(Message*))
        {
            dynamic_cast<VobjectImplementation*>(getTopObject())->removeUpdateHandler<T>(method, theobj, MessageHandler);
        };
};

/** This is a macro for the convenience of lazy typists. Note, it can only create
    objects with one type.  
    @deprecated Don't use this, use LocalSite::createMetaObject<TYPE>(name, ac).
    @param SITE A pointer or vRef to a Site
    @param CLASS Class to cast to and to use in creating the new object.
*/
#define CREATE_METAOBJECT(SITE, CLASS) VOS::MetaObject::meta_cast<CLASS*>((SITE)->createMetaObject(#CLASS, typeid(CLASS).name(), 0))

}

#endif

---