[Home]	[About]
[Screenshots]	[Download]
[News]	[Community]
[Documentation]	[Manual]
[Bugs & Requests]	[Wiki]

/home/tetron/hack/vos/libs/vos/vos/site.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, 2002 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 <http://www.interreality.org>
*/
#ifndef _SITE_HH_
#define _SITE_HH_

/** @file
    Defines Site.
*/

#include <deque>
#include <map>
#include <string>

namespace VOS
{
    class Site;
}

#include <vos/vos/vosdefs.hh>
#include <vos/vutil/refcount.hh>
#include <vos/vutil/url.hh>
#include <vos/vos/siteextension.hh>
#include <vos/vos/messageblock.hh>
#include <vos/vos/meta_cast.hh>

#define VOS_DEFAULT_PORT 4231


namespace VOS
{
    class Message;
    class MessageBlock;
    class MessageContext;
    class ChildChangeListener;
    class ParentChangeListener;
    class TypeChangeListener;
    class VobjectEvent;
    class LocalSite;
    class SiteIterator;
        class SiteExtension;

/** @class MessageFilter site.hh vos/vos/site.hh
    @ingroup libvos

    A message filter can be attached to any site to filter the
    messages passing through that site.  If you attach the filter to a
    remote site, you will filter outbound messages going to that
    remote site.  If you attach a filter to a local site, you will
    filter inbound messages being sent to the local site.
 */
class VOS_API MessageFilter
{
public:
    virtual ~MessageFilter();

    /** Do something with this message.  You are permitted to modify the message.
        @param m the message
        @return true to continue processing the message, false
        indicating the message should NOT be sent or delivered.
     */
    virtual bool checkMessage(Message* m) = 0;

    /** @copydoc VOS::MessageFilter::checkMessage(Message* m) */
    virtual bool checkMessage(MessageBlock* m);
};

/** @class ProtocolHandler site.hh vos/vos/site.hh
    @ingroup libvos

    Abstract interface that implements connecting to a remote site
    with some particular protocol.
*/
class VOS_API ProtocolHandler
{
public:
    virtual ~ProtocolHandler() { }
    virtual VUtil::vRef<Site> connectToSite(const VUtil::URL& u) = 0;
};

/** @class NoSuchMessageBlockError site.hh vos/vos/site.hh
    @ingroup libvos
    Thrown when a lookup for a stored message block fails.
*/
class VOS_API NoSuchMessageBlockError : public std::runtime_error {
public:
    NoSuchMessageBlockError(const std::string& s) : std::runtime_error(s) { };
};

/** @class NameAlreadyUsedError site.hh vos/vos/site.hh
    @ingroup libvos
    Thrown when an attempt to rename a Vobject fails due to there already being
    a Vobject with the new name.
*/
class VOS_API NameAlreadyUsedError : public std::runtime_error {
public:
    NameAlreadyUsedError(const std::string& s) : std::runtime_error(s) { };
    static const char* errorCode() { return "409"; }
};

/** @class ProtocolError site.hh vos/vos/site.hh
    @ingroup libvos
    Thrown when a critical protocol error has occurred
*/
class VOS_API ProtocolError : public std::runtime_error
{
public:
    ProtocolError(const std::string& s) : std::runtime_error(s) { };
};

/** @class ProgressMeterCallback site.hh vos/vos/site.hh
    @ingroup libvos

    Generic callback interface used to notify that progress has been
    made on some lengthy operation.
 */
class VOS_API ProgressMeterCallback {
public:
    virtual ~ProgressMeterCallback() { }

    /** Called when the some progress-monitored task is started.
        @param task a descriptor ID indicating the task that has just
        begun (the particular contents of this string should be
        documented in the API for calls that accept
        ProgressMeterCallback* as a parameter)
     */
    virtual void notifyTaskStart(const std::string& task, unsigned int total) = 0;

    /** Called to indicate current progress.  Percentage complete is
        100*(progress/total).
        @param action the action currently being taken (if an action has several stages)
        @param progress how much work has been completed
        @param total the total amount of work that needs to be done
     */
    virtual void notifyProgress(unsigned int progress) = 0;
};


/** @class Site site.hh vos/vos/site.hh
    @ingroup libvos

    A site is the root of any collection of Vobjects.  It is a normal
    Vobject in addition to having features particular to the site.  A
    site is the connection point by which a Vobject may exchange
    messages with another Vobject on another host across the Internet.
 */
class VOS_API Site :  public VobjectBase
{
public:
    typedef MetaObject* (*metaobject_extender_t)(VobjectBase* superobject, const std::string& type);
private:
    boost::mutex hostnames_mutex;
    std::set<std::string> hostnames;

    static boost::mutex& siteTable_mutex();
    static std::map<std::string, Site*>& siteTable();

    static boost::mutex& protocolHandlers_mutex();
    static std::map<std::string, ProtocolHandler*>& protocolHandlers();

    boost::mutex messageBlockTable_mutex;
    std::map<std::string, MessageBlock*> messageBlockTable;

    boost::mutex messagefilters_mutex;
    std::vector<MessageFilter*> messagefilters;

    VUtil::read_write_mutex site_extensions_mutex;
    std::vector< std::pair<const char*, SiteExtension*> > site_extensions;

    VUtil::vRef<Identity> myIdentity;
    VUtil::vRef<Identity> peerIdentity;

    VUtil::vRef<Site> localSite;

    static boost::mutex& localMetaObjectFactoryTable_mutex();
    static std::map<std::string, metaobject_extender_t>& localMetaObjectFactoryTable();

    static boost::mutex& remoteMetaObjectFactoryTable_mutex();
    static std::map<std::string, metaobject_extender_t>& remoteMetaObjectFactoryTable();

    static boost::mutex& classnameToVOStype_mutex();
    static std::map<std::string, std::string>& classnameToVOStype();

protected:
    virtual void msgSendImpl(boost::mutex& usehandlers_mutex, HandlerMap& usehandlers, Message* msg);

public:
    /** Constructor.
        @param islocal is this a local site or remote site.  You will probably always want
        a local site.
     */
    Site(bool islocal = true);

    /** Destructor */
    virtual ~Site();

    /** Create a new Vobject on this site.
        @param requester The object requesting this action.  If it isremote
        this will be access-control checked.  May be null.
        @param name The requested name.  This will be made unique by
        appending extra characters if there already exits an object
        with this name.  May be empty in which case a unique name will
        be generated.
        @param typelist The list of VOS types that this object should
        support.  MetaObject extensions for the supplied types will be
        added if the appropriate factories have been registered.
        @return the newly-constructed Vobject
     */
    virtual VUtil::vRef<Vobject> createVobjectT(Vobject* requester, const char* name,
                                         const std::deque<std::string>& typelist);

    /** Create a new Vobject on this site.
        @param name The requested name.  This will be made unique by
        appending extra characters if there already exits an object
        with this name.  May be empty in which case a unique name will
        be generated.
        @param typelist The list of VOS types that this object should
        support.  MetaObject extensions for the supplied types will be
        added if the appropriate factories have been registered.
        @return the newly-constructed Vobject
     */
    virtual VUtil::vRef<Vobject> createVobjectT(const char* name,
                                         const std::deque<std::string>& typelist)
        { return createVobjectT(0, name, typelist); }

    /** Create a new Vobject on this site. Use this creation method if your new
     * object will have to types, or you want to specify the types as strings
     * rather than using the template createVobject() methods.
     *
        @param name The requested name.  This will be made unique by
        appending extra characters if there already exits an object
        with this name.  May be empty in which case a unique name will
        be generated.
        @param t1...t5 The list of VOS types that this object should
        support.  MetaObject extensions for the supplied types will be
        added if the appropriate factories have been registered.
        @return the newly-constructed Vobject
     */
    VUtil::vRef<Vobject> createVobjectA(const char* name = "", const char* t1 = 0, const char* t2 = 0,
                                      const char* t3 = 0, const char* t4 = 0, const char* t5 = 0)
        {
            std::deque<std::string> typelist;
            if(t1) typelist.push_back(t1);
            if(t2) typelist.push_back(t2);
            if(t3) typelist.push_back(t3);
            if(t4) typelist.push_back(t4);
            if(t5) typelist.push_back(t5);
            return createVobjectT(name, typelist);
        }


    /** Create a new Vobject on this site.  The template parameter(s)
        are the MetaObject interfaces that you want this Vobject to
        support.
        @param name The requested name.  This will be made unique by
        appending extra characters if there already exits an object
        with this name.  May be empty in which case a unique name will
        be generated.
        @param ac an access control policy to assign to this object
        @return the newly-constructed Vobject, which has been
        meta_cast<> to the first template paramter.
     */
    template<class T>
    VUtil::vRef<T> createVobject(const std::string& name = "", const std::string& ac = "")
        {
            VUtil::vRef<T> obj = meta_cast<T>(createVobjectA(name.c_str(), typeid(T).name()));
            if(obj.isValid()) obj->setDefaultPolicy(ac);
            return obj;
    }

    /** @copydoc VOS::Site::createVobject */
        template<class T, class T2>
        VUtil::vRef<T> createVobject2(const std::string& name = "", const std::string& ac = "")
        {
            VUtil::vRef<T> obj = meta_cast<T>(createVobjectA(name.c_str(), typeid(T).name(),
                                                                           typeid(T2).name()));
            if(obj.isValid()) obj->setDefaultPolicy(ac);
            return obj;
    }

    /** @copydoc VOS::Site::createVobject */
        template<class T, class T2, class T3>
        VUtil::vRef<T> createVobject3(const std::string& name = "", const std::string& ac = "")
        {
            VUtil::vRef<T> obj = meta_cast<T>(createVobjectA(name.c_str(), typeid(T).name(),
                                                                           typeid(T2).name(), typeid(T3).name()));
            if(obj.isValid()) obj->setDefaultPolicy(ac);
            return obj;
    }

    /** @copydoc VOS::Site::createVobject */
        template<class T, class T2, class T3, class T4>
        VUtil::vRef<T> createVobject4(const std::string& name = "", const std::string& ac = "")
        {
            VUtil::vRef<T> obj = meta_cast<T>(createVobjectA(name.c_str(), typeid(T).name(),
                                                                           typeid(T2).name(), typeid(T3).name(), typeid(T4).name()));
            if(obj.isValid()) obj->setDefaultPolicy(ac);
            return obj;
    }

    /** @copydoc VOS::Site::createVobject */
        template<class T, class T2, class T3, class T4, class T5>
        VUtil::vRef<T> createVobject5(const std::string& name = "", const std::string& ac = "")
        {
            VUtil::vRef<T> obj = meta_cast<T>(createVobjectA(name.c_str(), typeid(T).name(),
                                                                           typeid(T2).name(), typeid(T3).name(), typeid(T4).name(),
                                                                           typeid(T5).name()));
            if(obj.isValid()) obj->setDefaultPolicy(ac);
            return obj;
    }

    /** A Vobject name unique on this site by appending characters to
        the given base as necesary.  Used by the createVobject
        methods.
        @param base the base name to start from
        @return the new name, if the name supplied in the base
        paramater was unique, then just the base name will be returned
     */
    virtual std::string uniqueName(const char* base);

    /** @return a random and unique numerical name. (Used by the createVobject methods). */
    virtual std::string generateUniqueName();

    /** Add a host alias to this site.  A host alias is a legal name
        by which this site may be refered to.
        @param h the host alias in the form "proto://hostname:port"
    */
    virtual void addHostAlias(const std::string& h);

    /** Remove a host alias of this site.
        @param h the host alias in the form "proto://hostname:port"
    */
    virtual void removeHostAlias(const std::string& h);

    /** Tests for the existance of a given host alias.
        @param h the host alias
        @return true if h is a legal host alias, false if not
    */
    virtual bool hasHostAlias(const std::string& h);

    /** Get a list of host alias.
        @return the set of host valid host aliases.
    */
    virtual StringIterator getHostAliases();

    /** Add a new URL for this site.

        @note at the moment this actually replaces the old URL
        completely; it doesn't handle having multiple URLs properly.
        This exists to solve a specific problem.  Don't use it.
     */
    virtual void addURL(const VUtil::URL& u);

    /** Add a site to the master table of known sites.
        @param s the site to be added
    */
    static void addSite(Site& s);

    /** Remove a site from the master table of known sites.
        @param s the site to remove
    */
    static void removeSite(Site& s);

    /** Find a site by its host alias.  Will contact remote sites if
        "contact" is true.
        @param s the site host alias (in the form
        "proto://host:port", such as "vop://interreality.org")
        @param contact if true, try and contact remote site, otherwise
        throw NoSuchSiteError if we are not already connected to this site
        @return the site matching that host alias.
        @throws NoSuchSiteError if the site is not found or could not be contacted
    */
    static VUtil::vRef<Site> findSite(const std::string& s, bool contact = true);

    /** Get a list of all known sites, local and remote.
        @return an iterator
    */
    static SiteIterator getAllSites();

    /** Save a message block template for later retrival and execution.
        @param m the message block
    */
    virtual void addMessageBlock(MessageBlock* m);

    /** Remove a saved message block template.
        @param m the message block
    */
    virtual void removeMessageBlock(MessageBlock* m);

    /** Retrive a saved message block template.
        @param s the name of the message block.
        @return The message block
        @throw NoSuchMessageBlockError if it was not found
    */
    virtual VUtil::vRef<MessageBlock> getMessageBlock(const std::string& s);

    virtual void sendMessage(Message* m);
    virtual void sendMessage(MessageBlock* m);

    virtual VUtil::vRef<Site> getSite() const;

    /** Add a message filter.
        @bug is this implemented?
    */
    virtual void insertMessageFilter(int pos, MessageFilter* mf);

    /** Add a message filter.
        @bug is this implemented?
    */
    virtual void removeMessageFilter(int pos);

    /** Add a message filter.
        @bug is this implemented?
    */
    virtual void removeMessageFilter(MessageFilter* m);

    // virtual const std::deque<MessageFilter*>& getMessageFilters();

    /** Attach a SiteExtension object which may extend the actions of
        various site-specific methods.
        @param sx the extension object
     */
    virtual void addSiteExtension(SiteExtension* sx);

    virtual void excise();

    /** Map a C++ MetaObject classname to the VOS type it implements.
        For example:
        @code
        convertClassnameToVOStype(typeid(Property).name()) == "property:property"
        @endcode
     */
    static std::string convertClassnameToVOStype(const std::string& n);

    /** Add a factory for creating MetaObjects that extend remote
        Vobjects.  Will replace any existing factory registered to this classname.
        @param classname a C++ or VOS interface this implements
        @param vostype the VOS type this implements
        @param newmethod the actual factory function that constructs the MetaObject
     */
    static void addRemoteMetaObjectFactory(const char* classname, const char* vostype, metaobject_extender_t newmethod);

    /** Fetch the factory function that constructs MetaObjects for the supplied class
        @param classname the C++ class name (via typeid(TheClass).name()) or VOS type
        @return the factory function (which can be called to construct
        a MetaObject) or 0 if there is no factory registered for this
        class.
     */
    static metaobject_extender_t getRemoteMetaObjectFactory(const char* classname);

    /** Remove the supplied factory function that is registered to this classname.
        Nothing will be removed unless both parameters match.
        @param classname the C++ class name (via
        typeid(TheClass).name()) or VOS type it was registered with
        @param oldmethod the factory function it was registered with
     */
    static void removeRemoteMetaObjectFactory(const char* classname,
                                              metaobject_extender_t oldmethod);

    /** Add a factory for creating MetaObjects that extend remote
        Vobjects.  Will replace any existing factory registered to this
        classname.
        @param classname a C++ or VOS interface this implements
        @param newmethod the actual factory function that constructs the MetaObject
     */
    static void addLocalMetaObjectFactory(const char* classname, metaobject_extender_t newmethod);

    /** Fetch the factory function that constructs MetaObjects for the supplied class
        @param classname the C++ class name (via typeid(TheClass).name()) or VOS type
        @return the factory function (which can be called to construct
        a MetaObject) or 0 if there is no factory registered for this
        class.
     */
    static metaobject_extender_t getLocalMetaObjectFactory(const char* classname);

    /** Remove the supplied factory function that is registered to this classname.
        Nothing will be removed unless both parameters match.
        @param classname the C++ class name (via
        typeid(TheClass).name()) or VOS type it was registered with
        @param oldmethod the factory function it was registered with
     */
    static void removeLocalMetaObjectFactory(const char* classname,
                                             metaobject_extender_t oldmethod);

    /** Print the factory registration table to stderr. (For debugging
        purposes) */
    static void dumpFactoryTables();

    /** Change the site name of this Vobject.
        @param requester the vobject requesting this change.  If it is
        remote, this action will be access control checked. (may be null)
        @param oldname the old Vobject
        @param newname the new name for the Vobject
        @throw NameAlreadyUsedError if there is already a Vobject with the new name
     */
    virtual void renameVobject(Vobject* requester, const std::string& oldname,
                               const std::string& newname);

    /** Change the site name of this Vobject.
        @param oldname the old Vobject
        @param newname the new name for the Vobject
        @throw NameAlreadyUsedError if there is already a Vobject with the new name
     */
    virtual void renameVobject(const std::string& oldname, const std::string& newname)
        { renameVobject(0, oldname, newname); }

    /** Returns the identity object on this remote site which we have
        authenticated ourselves to.  This identity object is used by
        the remote site to determine which access control policies to
        apply to us.  Only meaningful if this is a remote site.
        @return an identity object (which should always a remote
        object attached to this site), or a null vRef if we have not
        yet established our identity to this site.
     */
    virtual VUtil::vRef<Identity> getMyIdentity();

    /** Sets the cached value for our identity on this remote site.
        Does @em not actually change our effective identity on the
        remote site --- use an authentication mechanism such as
        RemotePasswordAuth to do that!

        @param id the identity object to use (should be a
        Identity Vobject attached to this remote site)
    */
    virtual void setMyIdentity(Identity* id);

    /** Returns the identity of this peer.  This is used to apply
        access control to any commands they send.

        @return the Identity Vobject or a null vRef if the peer has
        not yet established an Identity (default access control
        polices are applied in this case)
    */
    virtual VUtil::vRef<Identity> getPeerIdentity();

    /** Set the identity of this peer.  This is used to determine
        which access control policy to apply to this peer.  May be
        done manually by the application, or using an authentication
        metaobject such as LocalPasswordAuth.
        @param id the identity to use (must be a local object)
     */
    virtual void setPeerIdentity(Identity* id);

    /** For a remote site, set the local site object to which we are
        connected. */
    void setLocalSite(Site* s) { localSite.assign(s, true); }

    /** For a remote site, get the local site object to which we are
        connected. */
    VUtil::vRef<Site> getLocalSite() {
        if(isRemote()) return localSite;
        else return VUtil::vRef<Site>(this, true);
    }

    /** @return the first site extension that can be dynamic_cast<> to
        the template parameter C, or null if no extension has the
        desired type.
     */
    template<class C> C* querySiteExtension()
        {
            VUtil::scoped_read_lock lk(site_extensions_mutex);

            for(std::vector< std::pair<const char*, SiteExtension*> >::iterator i = site_extensions.begin();
                i != site_extensions.end();
                i++)
            {
                if(C* ret = dynamic_cast<C*>((*i).second)) return ret;
            }
            return 0;
        }

    /** Add a handler for connecting to sites with some protocol.

        @param protocol The protocol name.  This is the first part of
        the URL, such as "vop" in "vop://interreality.org"
        @param ph The protocol handler object.  This will be called to
        do the work of connecting to a remote site using this protocol.

        @note Actually having multiple protocols at once hasn't really been
        tried yet, but these hooks are a start.
     */
    static void addProtocolHandler(const std::string& protocol, ProtocolHandler& ph);

    /** @return the protocol handler object for this protocol */
    static ProtocolHandler* getProtocolHandler(const std::string& protocol);

    /** Remove the protocol handler object for this protocol */
    static void removeProtocolHandler(const std::string& protocol);
};

#ifndef SWIG

struct WaitingThread
{
    boost::condition cond;
    bool nonceSeen;
    bool wantProgress;
    unsigned int bytesReceived;
    unsigned int bytesTotal;
    VUtil::vRef<Site> localsite;
    VUtil::vRef<MessageBlock> msgblock;
};

#endif

}


#ifndef SWIG

namespace VUtil {
    template<> inline void iteratorReleaseItem(VOS::Site** v)
    {
        (*v)->release();
    }
}


namespace VOS {


/** @class SiteIterator site.hh vos/vos/site.hh
    @ingroup libvos
*/
    class SiteIterator : public VUtil::Iterator<Site*>
    {
    public:
        SiteIterator() : VUtil::Iterator<Site*>() { }
        SiteIterator(const SiteIterator& i) : VUtil::Iterator<Site*>(i) { }
        SiteIterator(const std::map<std::string, Site*> sites) {
            std::set<Site*> tmp;
            for(std::map<std::string, Site*>::const_iterator i = sites.begin();
                i != sites.end();
                i++)
            {
                tmp.insert((*i).second);
            }
            items->resize(tmp.size());
            int c = 0;
            for(std::set<Site*>::const_iterator i = tmp.begin();
                i != tmp.end();
                i++)
            {
                (*i)->acquire();
                (*items)[c] = (*i);
                c++;
            }
        }
        VUtil::vRef<Site> operator*() {
            if(pos < items->size()) return VUtil::vRef<Site>((*items)[pos], true);
            else return VUtil::vRef<Site>();
        }
    };

}

#endif // ifndef SWIG


#include <vos/vos/identity.hh>

namespace VOS {
template<class AccessControlType> inline std::vector<AccessControlType*>

VobjectBase::getAccessControlsFor(Vobject* requester,
                                PolicyDomain<AccessControlType>& accessControlPolicies)
        {
            VUtil::vRef<Identity> ident = requester->getSite()->getPeerIdentity();

            std::vector<AccessControlType*> accesscontrols;
            if(ident.isValid()) {
                StringIterator acs = accesscontrolstate->getPolicy(accessControlPolicies.getDomain(), ident);
                for(; acs.hasMore(); acs++) {
                    AccessControlType* act = accessControlPolicies.getPolicyImpl(*acs);
                    if(act) accesscontrols.push_back(act);
                }
            } else {
                AccessControlType* act = accessControlPolicies.getPolicyImpl(accesscontrolstate->getDefaultPolicy(accessControlPolicies.getDomain()));
                if(act) accesscontrols.push_back(act);
            }
            return accesscontrols;
        }

}

#endif