vos/corelibs/vos/vobject.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 _VOBJECT_HH_
#define _VOBJECT_HH_

/** @file
    Defines Vobject and VobjectImplementation.
*/

#include <vos/corelibs/vos/refcount.hh>
#include <vos/corelibs/vos/url.hh> // Need this for the exception
#include <vos/corelibs/vos/log.hh>

#include <deque>
#include <stdexcept>

/** Virtual Object System core library */

namespace VOS
{
    class Site;
    class Message;
    class MessageBlock;
    class TypeChangeListener;
    class ParentChangeListener;
    class ChildChangeListener;

/** @class Vobject vobject.hh vos/corelibs/vos/vobject.hh
 *
 * This is the abstract class that defines the basic API common to
    all virtual objects.
*/
class VOS_API Vobject : public virtual RefCounted
{
public:
    /** This structure expresses the relation between a parent vobject
        and a vobject which is a child of that parent.
    */
    class ParentChildRelation : public virtual RefCounted
    {
    public:
        ParentChildRelation(Vobject* c, Vobject* p) : child(c), parent(p) {
            child->acquire(); // released by: ParentChildRelation() destructor
            parent->acquire(); // released by: ParentChildRelation() destructor
        }
        ~ParentChildRelation() {
            if(parent && child) {
                LOG("vobject", 4, "deleting edge between child " << child->getURL().getString()
                    << " and parent " << parent->getURL().getString());
            } else if(parent) {
                LOG("vobject", 4, "deleting dangling edge from parent " << parent->getURL().getString());
            } else if(child) {
                LOG("vobject", 4, "deleting dangling edge to child " << child->getURL().getString());
            }

            if(child) child->release(); // acquired by: ParentChildRelation() constructor
            if(parent) parent->release(); // acquired by: ParentChildRelation() constructor
        }
        int position; /**< the position of the child in the parent's child list */
        string contextual_name; /**< the contextual name of the child in the parent's child list */
        Vobject* child; /**< the child object in question */
        Vobject* parent; /**< the parent object in question */
        /** This class is used internally to compare two ParentChildRelation structures
            to see if they represent the same relationship.
        */
        class Cmp {
        public:
            /** Compares two ParentChildRelation classes.
                @param p left structure
                @param q right
                @return true if "p < q"; if the two are equal then ("p < q" || "q < p") is false.
            */
            inline bool operator()(const ParentChildRelation* p, const ParentChildRelation* q) const {
                if(p->parent == q->parent) return (p->position < q->position);
                else return (p->parent < q->parent);
            };
        };
    };

    typedef set<Vobject::ParentChildRelation*, Vobject::ParentChildRelation::Cmp> ParentSet;
    typedef deque<Vobject::ParentChildRelation*> ChildList;
    typedef set<string> TypeSet;

    /** An exception class thrown when the user attempts to read
        from the receiving queue and that queue is empty. */
    class MessageQueueEmptyError : public runtime_error {
    public:
        MessageQueueEmptyError(const string& s) : runtime_error(s) { };
    };

    /** An exception class thrown when a site lookup fails. */
    class NoSuchSiteError : public runtime_error {
    public:
        NoSuchSiteError(const string& s) : runtime_error(s) { };
    };

    /** An exception class thrown when an object lookup fails. */
    class NoSuchObjectError : public runtime_error {
    public:
        NoSuchObjectError(const string& s) : runtime_error(s) { };
    };

    class AccessControlError : public runtime_error {
    public:
        AccessControlError(const string& s) : runtime_error(s) { };
    };

    /** An exception class thrown when a remote action fails. */
    class RemoteError : public runtime_error {
    public:
        RemoteError(const string& s) : runtime_error(s) { };
    };

    /** An exception class thrown when an expected reply didn't arrive in the alloted time. */
    class TimeoutError : public RemoteError {
    public:
        TimeoutError(const string& s) : RemoteError(s) { };
    };

    /** Get the site name of this object.
        @return the name string
    */
    virtual const string& getName() = 0;

    /** Get the site this object resides on.
        @return the site object.   NOTE YOU MUST CALL release() WHEN DONE OR USE A rREF() BLOCK
    */
    virtual Site& getSite() = 0;

    /** Get the URL path (in the form "vop://site/name")
        @return the URL
    */
    virtual const URL& getURL() = 0;

    /** Return true if this object is local, false if not
        @return whether it is local
    */
    virtual bool isLocal() = 0;

    /** Return true if this object is remote, false if not
        @return whether it is remote
    */
    virtual bool isRemote() = 0;

    /** Return a set of type names for the types supported by this object.
        @return the set of type names
    */
    virtual const TypeSet& getTypes() throw (AccessControlError, RemoteError) = 0;

    /** Adds a new type to this object's type set.  This only changes
        the stored set of type name strings and does not necessarily
        affect the actual code behind the object.  See the Local Site
        class for information about extending the actual functionality
        of an existing meta objects.
        @param s the type string
    */
    virtual void addType(const string& s) = 0;

    /** Get the set of parent-child relationships in which this object is the child.
        @return a set of parent-child relations
    */
    virtual const ParentSet& getParents()
        throw (AccessControlError, RemoteError) = 0;

    /** Get the set of parent-child relationships in which this object is the parent.
        @return a set of parent-child relations

       @warning You should <em>always</em> assign the results of
       getChildren to a variable. Do NOT do this:
     @code
       for(Vobject::ChildList::const_iterator i = v->getChildren().begin();
            i != v->getChildren().end(); i++) {
            ...
       }
     @endcode
        Instead, you should do this:
     @code
       const ChildList& cl = v->getChildren();
       for(Vobject::ChildList::const_iterator i = cl.begin(); i != cl.end(); i++) {
            ...
       }
     @endcode
        The reason for this is that if vobj is remote, each call to
        getChildren() may trigger a remote call.  In addition to being
        inefficient, this will wipe and replace the child list you are
        in the midst of using, which will probably invalidate the
        iterator and cause your program to crash.

    */
    virtual const ChildList& getChildren() throw (AccessControlError, RemoteError) = 0;

    /** Sends a message to the object.  This may trigger immediate
        processing of the message if the object is local.
        @param m A pointer to the message which is being sent.  Its reference count will be increased as necssary.
    */
    virtual void sendMessage(Message* m) = 0;

    /** Sends a block of messages to the object.  This may trigger immediate
        processing of the message if the object is local.
        @param m A pointer to the message which is being sent.  Its reference count will be increased as necssary.
    */
    virtual void sendMessage(MessageBlock* m) = 0;

    /** Gets the next message the object has received.
        @throws MessageQueueEmptyError If the message queue is empty.
        This may be the case if there are no messages available or if
        the user has set DoNotQueueMsgs to true in
        VobjectImplementation.
        @return the message.    NOTE YOU MUST CALL release() WHEN DONE OR USE vRef!
    */
    virtual Message* receiveMessage() throw (MessageQueueEmptyError) = 0;

    /** Returns if the object has a message available to be dequeued by receiveMessage().
        @return True if receiveMessage will succeed, false if receiveMessage will throw an exception.
    */
    virtual bool hasMessageAvailable() = 0;

    /** Gets the next message the update object has received.  Update
        messages are special in that they consist of messages sent
        from remote sites to update changes to our local cache.
        @param m A pointer to the message which is being sent.  Its reference count will be increased as necssary.
    */
    virtual void sendUpdateMessage(Message* m) = 0;

    /** Gets the next update message the object has received.
        @throws MessageQueueEmptyError If the message queue is empty.
        This may be the case if there are no messages available or if
        the user has set DoNotQueueUpdateMsgs to true in
        VobjectImplementation.
        @return the message.    NOTE YOU MUST CALL release() WHEN DONE OR USE vRef!
    */
    virtual Message* receiveUpdateMessage() throw (MessageQueueEmptyError) = 0;

    /** Returns if the object has a message available to be dequeued
        by receiveUpdateMessage().
        @return True if receiveMessage() will succeed, false if
        receiveMessage will throw an exception.
    */
    virtual bool hasUpdateMessageAvailable() = 0;

    /** Searchs and returns some object, given a rooted path (that is,
        in the form "vop://site:port/child1/child2/etc").  See
        findObject() for more information about paths.
        @param path the path to the object we want to find
        @return the object, if found.  NOTE YOU MUST CALL release() WHEN DONE OR USE A rREF() BLOCK
        @throws NoSuchSiteError The DNS lookup for the site failed,
        the site is listening on the expected port, or the site
        otherwise could not be connected to
        @throws NoSuchObjectError if that object path does not exist on the site
        @throws URL::BadURLError if there is a syntax error in the supplied URL
        @throws AccessControlError if the site reported that the user is not allowed that information
    */
    static Vobject& findObjectFromRoot(const string& path)
        throw (NoSuchSiteError, NoSuchObjectError, URL::BadURLError, AccessControlError, RemoteError);

    /** Searchs and returns some object similarly to
        findObjectFromRoot().  However, if the path does not start
        with the string "vop://" the path will be intepreted as
        relative to this object.  For example, "foo/bar" will find the
        first child object named "foo" of this object, then the first
        child named "bar" of the "foo" object and return it.  If there
        is a leading slash, the path is relative to the object's site,
        so "/foo/bar" does @em not necessarily mean the same thing.
        Note that there should never be a slash at the end, so "foo/"
        is NOT a legal path.  Finally, instead of using child names,
        one may use "\#position", starting from zero.  So "\#0" refers
        to the first child of this object, "\#1" to the second etc.
        Obviously if the number in \#position is larger than the
        number of children, an exception will be raised.  See
        setChild() for more information about the possible numerical
        values of positions.
        @param path the path to the object we want to find
        @return the object, if found.  NOTE YOU MUST CALL release() WHEN DONE OR USE A rREF() BLOCK
        @throws NoSuchSiteError The DNS lookup for the site failed,
        the site is not listening on the expected port, or the site
        otherwise could not be connected to (only thrown if there is a
        site specified in the path.)
        @throws NoSuchObjectError if that object path does not exist on the site
        @throws URL::BadURLError if there is a syntax error in the supplied URL
        @throws AccessControlError if the site reported that the user is not allowed that information
    */
    virtual Vobject& findObject(const string& path)
        throw (NoSuchSiteError, NoSuchObjectError, URL::BadURLError, AccessControlError, RemoteError) = 0;

    /** Find a child.  This searchs for a single parent-child relation
        in the immediate child list of this object.  It is
        distinguished from findObject in that it returns the full
        parent-child relation structure, and that it only accepts two
        forms of input: the child name, or the \#position.  See
        setChild() for more information about the possible
        numerical values of positions.
        @param path either the child name or \#position
        @return the ParentChildRelation structure representing the
        relation of this parent and the requested child.   NOTE YOU MUST CALL release() WHEN DONE OR USE A rREF() BLOCK
        @throws NoSuchObjectError if the path is illegal
        @throws AccessControlError if the site reported the user is not allowed that information
    */
    virtual Vobject::ParentChildRelation& findChild(const string& path)
        throw (NoSuchObjectError, AccessControlError, RemoteError) = 0;

    /** Find a parent.  This tests to see if the supplied Vobject is
        marked as a parent of this Vobject.
        @param parent the parent object
        @returns the parent-child relation.   NOTE YOU MUST CALL release() WHEN DONE OR USE A rREF() BLOCK
        @throws NoSuchObjectError if the object is NOT a parent
        @throws AccessControlError if the site reported the user is not allowed that information
    */
    virtual Vobject::ParentChildRelation& findParent(Vobject& parent)
        throw (NoSuchObjectError, AccessControlError, RemoteError) = 0;

    /** Replace a child at some position with a new object.  @note On
        positions: if a position is zero or positive, its meaning is
        as you would expect, expressing the offset into an array of
        children.  However, if the position is negative, it expresses
        the offset from the end of the list.  This means for a list of
        length n, -1 is the last item in the list (equal to position
        position n - 1) and -n is the first item (equal to positive
        position 0).  This position notation is used in setChild()
        findObject(), findObjectFromRoot(), insertChild(), and
        removeChild(); it should also be available with any methods
        who make use of the previously-mentioned methods.
        @param position the position
        @param contextual_name This is the name, specific to this
        parent-child relation, used for refering to this object by
        path.
        @param child the child object, in question
        @throws AccessControl if this object (when it is remote)
        doesn't approve of this action.  */
    virtual void setChild(int position, const string& contextual_name, Vobject* child)
        throw (AccessControlError, RemoteError) = 0;

    /** Insert a child at some position with a new object.  If the
        position is positive, the object is inserted such that it now
        occupies that position, and all objects starting from the
        previous occupant of that position onward are moved up one.
        If the position in negative, the object is similarly inserted
        so that it now occupies that position.  For example, position
        -1 will append the object to the end of the list, position -2
        will insert the object in the second-to-last position, etc.  See
        setChild() for more information on positions.
        @param position the position
        @param contextual_name This is the name, specific to this
        parent-child relation, used for refering to this object by
        path.
        @param child the child object, in question
        @throws AccessControl if this object (when it is remote)
        doesn't approve of this action.
    */
    virtual void insertChild(int position,
                             const string& contextual_name,
                             Vobject* child)
        throw (AccessControlError, RemoteError) = 0;

    /** Remove the child at some position.  See setChild() for more
        information on positions.
        @param position the position
        @throws AccessControl if this object (when it is remote)
        doesn't approve of this action.  */
    virtual void removeChild(int position)
        throw (AccessControlError, RemoteError) = 0;

    /** Adds some object callback to be notified when the type set changes.
        @param tl the listener object.
        @param notifyImmediately  if true, notify listener immediately (before returning). otherwise defer until a future update
        If this object is also a RefCounted object, reference counting will be done correctly.
    */
    virtual void addTypeListener(TypeChangeListener* tl, bool notifyImmediately = true) = 0;

    /** Adds some object callback to be notified when the parent set changes.
        @param pl the listener object
        @poram notifyImmediately  if true, notify listener immediately (before returning). otherwise defer until a future update
        If this object is also a RefCounted object, reference counting will be done correctly.
    */
    virtual void addParentListener(ParentChangeListener* pl, bool notifyImmediately = true) = 0;

    /** Adds some object callback to be notified when the child list changes.
        The child listener will immediately be issued a notifyChildInserted() for
        each child.
        @param cl The listener object. If this object is also a RefCounted object, reference counting will be done correctly.
        @param notifyImmediately  if true, notify listener immediately (before returning). otherwise defer until a future update
    */
    virtual void addChildListener(ChildChangeListener* cl, bool notifyImmediately = true) = 0;

    /** Removes an existing object callback, previously added with addTypeListener().
        @param tl the listener object
        If this object is also a RefCounted object, reference counting will be done correctly.
    */
    virtual void removeTypeListener(TypeChangeListener* tl) = 0;

    /** Removes an existing object callback, previously added with addParentListener().
        @param pl the listener object
        If this object is also a RefCounted object, reference counting will be done correctly.
    */
    virtual void removeParentListener(ParentChangeListener* pl)= 0;

    /** Removes an existing object callback, previously added with addChildListener().
        @param cl the listener object
        If this object is also a RefCounted object, reference counting will be done correctly.
    */
    virtual void removeChildListener(ChildChangeListener* cl) = 0;

    /** Provide our own comparison function for objects which are logically
        equivilent in terms of the Vobject system.
        @param the object to compare this to
        @return v if these objects are equivalent
    */
    bool operator==(Vobject& v);

    /** Provide our own comparison function for objects which are logically
        equivilent in terms of the Vobject system.
        @param s the object to compare this to
        @return if these objects are equivalent
    */
    bool operator==(Vobject* v);

    /** Create a message block which, when run, will recreate any
        non-VOS state related to this vobject (such as property
        values).  In other words, it should not emit anything related
        to parent-child relationships, but is rather is a hook for
        other arbitrary state information, encoded as messages.
        @note Save-state routines ought to work for saving remote
        objects as well, based on available state.  Also, only the
        method and the message fields themselves should be used.  "To",
        "from", "nonce" and others will be ignored.
        @param output messages should be appended to this message block
        @param types the type set that should be output for this vobject
        @param portable If true, generate a "portable" state.  This
        means that all the data required to restore state should be
        embedded in the message.  If false, fully recreating the state
        may rely on external resources such as files or databases.
     */
    virtual void saveState(MessageBlock& output, set<string>& types, bool portable) = 0;

    /** Add a flag string.  Mainly useful for doing tree walks, when
        you want to mark an object as already having been touched.
        @param flag the flag string
     */
    virtual void addFlag(const string& flag) = 0;

    /** Remove a flag string.
        @param flag the flag string
     */
    virtual void removeFlag(const string& flag) = 0;

    /** Check the flag string.
        @param flag the flag string
        @return whether the flag string is set
     */
    virtual bool checkFlag(const string& flag) = 0;
};


/** A base implementation class for virtual objects.  Except for a few
    implementation-specific added methods, the API is the same as
    Vobject.

    @internal
*/
class VOS_API VobjectImplementation : public virtual Vobject, public virtual ObjectExciseListener
{
private:
    bool islocal;
    bool exciseCalled;
    Site* site;
protected:
    string name;
    URL url;
    deque<Message*> incomingMessageQueue;
    deque<Message*> incomingUpdateMessageQueue;
    set<ParentChildRelation*, Vobject::ParentChildRelation::Cmp> parents;
    deque<ParentChildRelation*> children;
    map<string, ParentChildRelation*> children_map;
    set<string> types;
    VobjectImplementation(const string& name, Site* remotesite, bool islocalobj);
    bool queueMsgs;
    bool queueUpdateMsgs;
    static bool queueMsgs_def;
    static bool queueUpdateMsgs_def;
    set<TypeChangeListener*> typeListeners;
    set<ParentChangeListener*> parentListeners;
    set<ChildChangeListener*> childListeners;

    set<string> flagstrings;

    class Dispatch
    {
    public:
        virtual ~Dispatch() {};
        virtual void sendMessage(Message* m) = 0;
        virtual bool equivalent(void*, void*) = 0;
        virtual bool holds(RefCounted* otherobj) = 0;
    };

    template<class T> class DispatchTemplate : public virtual Dispatch
    {
    private:
        T* thisobj;
        typedef void (T::* MessageHandler)(Message*);
        MessageHandler thismethod;
        bool needRelease;
    public:
        DispatchTemplate(T* theobj, MessageHandler themethod, bool doRefcount)
            : thisobj(theobj), thismethod(themethod), needRelease(doRefcount)
            {
                if(doRefcount) {
                    if(RefCounted* rc = dynamic_cast<RefCounted*>(theobj)) {
                        rc->acquire(); // released by: destructor
                    }
                }
            }
        virtual ~DispatchTemplate()
            {
                if(needRelease) {
                if(RefCounted* rc = dynamic_cast<RefCounted*>(thisobj)) {
                    rc->release(); // acquired by: constructor
                }
                }
        }

        virtual void sendMessage(Message* m) {
            (thisobj->*thismethod)(m);
        }

        virtual bool equivalent(void* otherobj, void* othermethod) {
            //return (otherobj == (void*)thisobj && othermethod == makevoid(thismethod));
            return (otherobj == (void*)thisobj);
        }

        virtual bool holds(RefCounted* otherobj) {
            return (dynamic_cast<RefCounted*>(thisobj) == otherobj);
        }
    };

    typedef multimap<string, Dispatch*> HandlerMap;
    HandlerMap msghandlers;
    HandlerMap updatehandlers;
public:
    virtual ~VobjectImplementation();

    virtual const string& getName() { return name; };
    virtual Site& getSite();
    virtual const URL& getURL() { return url; }
    virtual bool isLocal() { return islocal; };
    virtual bool isRemote() { return (!islocal); };

    template<class T> void addMessageHandler(const string& method, T* theobj,
                                             void (T::* MessageHandler)(Message*),
                                             bool addExListener = false)
        {
            Dispatch* dt = new DispatchTemplate<T>(theobj, MessageHandler, addExListener);
            msghandlers.insert(HandlerMap::value_type(method, dt));
            if(addExListener) {
                if(RefCounted* rc = dynamic_cast<RefCounted*>(theobj)) {
                    rc->addExciseListener(this);
                }
            }
        };

    template<class T> void addUpdateHandler(const string& method, T* theobj,
                                            void (T::* MessageHandler)(Message*),
                                            bool addExListener = false)
        {
            Dispatch* dt = new DispatchTemplate<T>(theobj, MessageHandler, addExListener);
            updatehandlers.insert(HandlerMap::value_type(method, dt));
            if(addExListener) {
                if(RefCounted* rc = dynamic_cast<RefCounted*>(theobj)) {
                    rc->addExciseListener(this);
                }
            }
        };

    template<class T> void removeMessageHandler(const string& method, T* theobj,
                                                void (T::* MessageHandler)(Message*))
        {
            pair<HandlerMap::iterator, HandlerMap::iterator> g = msghandlers.equal_range(method);
            for(HandlerMap::iterator it = g.first; it != g.second; it++) {
                if((*it).second->equivalent(theobj, thehandler)) {
                    if(RefCounted* rc = dynamic_cast<RefCounted*>(theobj)) {
                        rc->removeExciseListener(this);
                    }
                    delete (*i).second;
                    msghandlers.erase(it);
                    break;
                }
            }
        };

    template<class T> void removeUpdateHandler(const string& method, T* theobj,
                                               void (T::* MessageHandler)(Message*))
        {
            pair<HandlerMap::iterator, HandlerMap::iterator> g = updatehandlers.equal_range(method);
            for(HandlerMap::iterator it = g.first; it != g.second; it++) {
                if((*it).second->equivalent(theobj, thehandler)) {
                    if(RefCounted* rc = dynamic_cast<RefCounted*>(theobj)) {
                        rc->removeExciseListener(this);
                    }
                    delete (*i).second;
                    updatehandlers.erase(it);
                    break;
                }
            }
        };

    /** Get the default message discard policy for new objects.
        @return true if messages, after being passed through
        sendMessage(), are queued so they may be retrieved with
        receiveMessage(); false if the messages are instead discarded.
    */
    static bool getQueueMsgsDefault() { return queueMsgs_def; }

    /** Set the default message discard policy for new objects.
        @param t If false an incoming message, after being passed
        through sendMessage(), will be discarded.  If
        true that message will be queued and may be retrived by the
        user with receiveMessage().
    */
    static void setQueueMsgsDefault(bool t) { queueMsgs_def=t; }

    /** Get the default update message discard policy for new objects.
        @return true if update messages, after being passed through
        sendUpdateMessage(), are queued so they may be retrieved with
        receiveUpdateMessage(); false if the update messages are discarded.
    */
    static bool getQueueUpdateMsgsDefault() { return queueUpdateMsgs_def; }

    /** Set the default update message discard policy for new objects.
        @param t If false an incoming update message, after being passed
        through sendUpdateMessage(), will be discarded.  If
        true that update message will be queued and may be retrived by the
        user with receiveUpdateMessage().
    */
    static void setQueueUpdateMsgsDefault(bool t) { queueUpdateMsgs_def=t; }

    /** Get the message discard policy for this object.
        @return true if messages, after being passed through
        sendMessage(), are queued so they may be retrieved with
        receiveMessage(); false if the messages are instead discarded.
    */
    virtual bool getQueueMsgs() { return queueMsgs; }

    /** Set the message discard policy for this object.
        @param t If false an incoming message, after being passed
        through sendMessage(), will be discarded.  If
        true that message will be queued and may be retrived by the
        user with receiveMessage().
    */
    virtual void setQueueMsgs(bool t) { queueMsgs=t; }

    /** Get the update message discard policy for this object.
        @return true if update messages, after being passed through
        sendUpdateMessage(), are queued so they may be retrieved with
        receiveUpdateMessage(); false if the update messages are discarded.
    */
    virtual bool getQueueUpdateMsgs() { return queueUpdateMsgs; }

    /** Set the update message discard policy for this object.
        @param t If false an incoming update message, after being passed
        through sendUpdateMessage(), will be discarded.  If
        true that update message will be queued and may be retrived by the
        user with receiveUpdateMessage().
    */
    virtual void setQueueUpdateMsgs(bool t) { queueUpdateMsgs=t; }

    virtual const TypeSet& getTypes()
        throw (AccessControlError, RemoteError);

    virtual void addType(Vobject* requester, const string& s);

    virtual const ParentSet& getParents()
        throw (AccessControlError, RemoteError);
    virtual const ChildList& getChildren()
        throw (AccessControlError, RemoteError);

    virtual Message* receiveMessage() throw (MessageQueueEmptyError);
    virtual bool hasMessageAvailable();

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

    virtual Vobject& findObject(const string& path)
        throw (NoSuchSiteError, NoSuchObjectError, URL::BadURLError, AccessControlError, RemoteError);
    virtual Vobject::ParentChildRelation& findChild(const string& path)
        throw (NoSuchObjectError, AccessControlError, RemoteError);
    virtual Vobject::ParentChildRelation& findParent(Vobject& parent)
        throw (NoSuchObjectError, AccessControlError, RemoteError);

    virtual void setChild(Vobject* requester, int position, const string& contextual_name, Vobject* child)
        throw (AccessControlError, RemoteError);
    virtual void insertChild(Vobject* requester, int position, const string& contextual_name, Vobject* child)
        throw (AccessControlError, RemoteError);
    virtual void removeChild(Vobject* requester, int position)
        throw (AccessControlError, RemoteError);

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

    virtual void notifyObjectExcise(RefCounted* rc);

    virtual void excise();

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

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

    friend class RemoteVobject;
};
}

#endif

---