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

/home/tetron/hack/vos/libs/vos/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 <http://www.interreality.org>
*/

#ifndef _VOBJECT_HH_
#define _VOBJECT_HH_

#include <vos/vos/vosdefs.hh>
#include <vos/vutil/refcount.hh>
#include <vos/vutil/url.hh>
#include <vos/vutil/log.hh>

#include <deque>
#include <stdexcept>
#include <vector>


namespace VOS
{
    class Site;
    class Message;
    class MessageBlock;
    class TypeChangeListener;
    class ParentChangeListener;
    class ChildChangeListener;
    class ParentChildRelation;
    class MetaObject;
    class VobjectBase;
    class Identity;
    class Group;
    class ACLIterator;

    class PCRIterator;
    typedef PCRIterator ChildListIterator;
    typedef PCRIterator ParentSetIterator;
    class StringIterator;
    typedef StringIterator TypeSetIterator;

    /** @class NoSuchSiteError vobject.hh vos/vos/vobject.hh
        @ingroup libvos
        An exception class thrown when a remote site cannot be contacted.
    */
    class VOS_API NoSuchSiteError : public std::runtime_error {
    public:
        NoSuchSiteError(const std::string& s) : runtime_error(s) { };
        static const char* errorCode() { return "404"; }
    };

    /** @class NoSuchObjectError vobject.hh vos/vos/vobject.hh
        @ingroup libvos
        An exception class thrown when an object lookup fails.
    */
    class VOS_API NoSuchObjectError : public std::runtime_error {
    public:
        NoSuchObjectError(const std::string& s) : runtime_error(s) { };
        static const char* errorCode() { return "404"; }
    };

    /** @class AccessControlError vobject.hh vos/vos/vobject.hh
        @ingroup libvos
    */
    class VOS_API AccessControlError : public std::runtime_error {
    public:
        AccessControlError(const std::string& s) : runtime_error(s) { };
        static const char* errorCode() { return "403"; }
    };

    /** @class RemoteError vobject.hh vos/vos/vobject.hh
        @ingroup libvos
        An exception class thrown when a remote action fails. */
    class VOS_API RemoteError : public std::runtime_error {
    public:
        RemoteError(const std::string& s) : runtime_error(s) { };
    };

    /** @class TimeoutError vobject.hh vos/vos/vobject.hh
        @ingroup libvos

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

    /** Used by metaobject and vobject extension classes to all them to accept message dispatch (directing
        messages with a given method string to a specific method).
     */
    class VOS_API Dispatchable
    {
    public:
        virtual ~Dispatchable() { }
    };

/** @class Vobject vobject.hh vos/vos/vobject.hh
    @ingroup libvos

    This is the abstract class that defines the basic API common to
    all virtual objects.  Whether the object is local or remote, you
    should be able to use all the methods in this API (provided you
    have proper permissions).
*/
    class VOS_API Vobject : public VUtil::RefCounted
{
public:
    /** @return the site name of this object. */
    virtual const std::string& getSiteName() const = 0;

    /** @return the site this object resides on. */
    virtual VUtil::vRef<VOS::Site> getSite() const = 0;

    /** @return the URL path as a URL object */
    virtual const VUtil::URL& getURL() const = 0;

    /** @return the URL path (in the form "proto://site/name") */
    virtual std::string getURLstr() { return getURL().getString(); }

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

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

    /** @return a set of type names for the types supported by this object. */
    virtual TypeSetIterator getTypes() = 0;

    /** Adds a new type to this object's type set.  This only changes
        the stored set of type name std::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 std::string
    */
    virtual void addType(const std::string& s) = 0;

    /** Remove a type from the type set.
        @param s the type std::string
    */
    virtual void removeType(const std::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 ParentSetIterator getParents() = 0;

    /** Get the children of this Vobject.  Permits fetching a "slice"
        of a child list by specifying starting and ending positions.

        @param start the position of the first child to return (inclusive)
        @param end the position of th elast child to return (inclusive)
        @return an Iterator over a list of parent-child relations
    */
    virtual ChildListIterator getChildren(int start = 0, int end = -1) = 0;

    /** @return the number of children that this Vobject has.  This is
        more efficient than calling getChildren().size() because if
        this is a remote object it does not actually fetch the
        children.
     */
    virtual int numChildren() = 0;

    /** Delivers 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.
    */
    virtual void sendMessage(Message* m) = 0;

    /** Delivers 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.
    */
    virtual void sendMessage(MessageBlock* m) = 0;

    /** Delivers an update message to this object -- only meaningful if
        this is a remote object.  Update messages are special in that
        they are sent by the remote site to update our local cache.

        @param m A pointer to the message which is being sent.
    */
    virtual void sendUpdateMessage(Message* m) = 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.
        @throws NoSuchSiteError The DNS lookup for the site failed,
        the site is not listening on the expected port, site peering
        failed, for whatever other reason the site could not be contacted.
        @throws NoSuchObjectError if that object path does not exist on the site
        @throws BadURLError if there is a syntax error in the supplied URL
        @throws AccessControlError if a remote site reported that the user
        is not allowed that information
    */
    static VUtil::vRef<VOS::Vobject> findObjectFromRoot(const std::string& path);

    /** Follows some path to find the Vobject.  Unlike
        findObjectFromRoot(), if the path does not start with "vop://"
        the path will be intepreted 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
        "foo" object and return that.  If there is a leading slash,
        the path is relative to the object's site, so "/foo/bar" means
        to find the Vobject with site name "foo", then find the first
        child of that object "bar" and return that.  Instead of using
        child names, one may use the position by prefixing a hash mark
        to the numerical position.  So "\#0" refers to the first child
        of this object, "\#1" to the second etc.  If this 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.
        @throws NoSuchSiteError The DNS lookup for the site failed,
        the site is not listening on the expected port, site peering
        failed, for whatever other reason the site could not be
        contacted.  Only thrown if there is a site specified in the
        path.)
        @throws NoSuchObjectError if that object path does not exist on the site
        @throws BadURLError if there is a syntax error in the supplied URL
        @throws AccessControlError if a remote site reported that the user
        is not allowed that information
    */
    virtual VUtil::vRef<VOS::Vobject> findObject(const std::string& path) = 0;

    /** Fetch 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 in the child
        list.  See setChild() for more information about the possible
        numerical values of positions.  If there are multiple children
        with the same name, the one with the lowest position is
        returned.

        @param path either the child name or the position as a string
        @return the ParentChildRelation structure representing the
        relation of this parent and the requested child.
        @throws NoSuchObjectError if the path is illegal
        @throws AccessControlError if a remote site reported the user
        is not allowed that information
    */
    virtual VUtil::vRef<VOS::ParentChildRelation> findChild(const std::string& path) = 0;

    /** Get the child at a certain position.  This searchs for a
        single parent-child relation in the immediate child list of
        this object.  See setChild() for more information about the
        possible numerical values of positions.

        @param pos the child position
        @return the ParentChildRelation structure representing the
        relation of this parent and the requested child.
        @throws NoSuchObjectError if the path is illegal
        @throws AccessControlError if a remote site reported the user
        is not allowed that information
    */
    virtual VUtil::vRef<VOS::ParentChildRelation> findChild(int pos) = 0;

    /** Find a parent.  This tests to see if the supplied Vobject is
        a parent of this Vobject.
        @param parent the parent object
        @returns the parent-child relation.
        @throws NoSuchObjectError if the object is NOT a parent
        @throws AccessControlError if a remote site reported the user
        is not allowed that information
    */

    virtual VUtil::vRef<VOS::ParentChildRelation> findParent(Vobject* parent) = 0;

    /** Replace an entry in the child list with a new entry.  This can
        be used to change the child, the contextual name, or both.

        @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 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 is a remote object and the
        remote site has denied the requsted action
    */
    virtual void setChild(int position, const std::string& contextual_name,
                          Vobject* child) = 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 discussion 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 is a remote object and the
        remote site has denied the requsted action
    */
    virtual void insertChild(int position, const std::string& contextual_name,
                             Vobject* child) = 0;

    /** Remove the child at some position.  See setChild() for more
        information on positions.

        @param pcr ParentChildRelation object describing the child
        entry to remove.
        @param strict Should the position in the supplied parent child
        relation be strictly followed?  If strict is false, then if
        the parent-child entry at the supplied position does NOT match
        the contextual name and/or child object, but there is exactly
        one other entry in the child list which does match the
        contextual name and child we want to remove, then that entry
        will be removed instead.  If strict is true, an
        AccessControlError is raised in this situation.

        @throws AccessControl if this is a remote object and the
        remote site has denied the requsted action
    */
    virtual void removeChild(ParentChildRelation* pcr, bool strict = true) = 0;

    /** Adds some object callback to be notified when the type set changes.
        @param tl the listener object.
        @param refresh if true, will queue up notification callbacks
        on the listener fully describing the current state.
    */
    virtual void addTypeListener(TypeChangeListener* tl, bool refresh = true) = 0;

    /** Adds some object callback to be notified when the parent set changes.
        @param pl the listener object
        @param refresh if true, will queue up notification callbacks
        on the listener fully describing the current state.
    */
    virtual void addParentListener(ParentChangeListener* pl, bool refresh = true) = 0;

    /** Adds some object callback to be notified when the child list
        changes.  The
        @param cl The listener object.
        @param refresh if true, will queue up notification callbacks
        on the listener fully describing the current state.
    */
    virtual void addChildListener(ChildChangeListener* cl, bool refresh = true) = 0;

    /** Removes an object callback, previously added with addTypeListener().
        @param tl the listener object
    */
    virtual void removeTypeListener(TypeChangeListener* tl) = 0;

    /** Removes an object callback, previously added with addParentListener().
        @param pl the listener object
    */
    virtual void removeParentListener(ParentChangeListener* pl) = 0;

    /** Removes an object callback, previously added with addChildListener().
        @param cl the listener object
    */
    virtual void removeChildListener(ChildChangeListener* cl) = 0;

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

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

    /** 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, std::set<std::string>& types, bool portable) = 0;

    /** Add a flag string.  Useful when doing recursive tree walks, to
        avoid cycles.  This is local-only, it is not shared with other
        sites in any way.

        @param flag the flag string
     */
    virtual void addFlag(const std::string& flag) = 0;

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

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

    /** @return the VobjectBase object that actually implements this Vobject */
    virtual VUtil::vRef<VobjectBase> getVobjectBase() = 0;

    /** @copydoc VOS::AccessControlState::getPolicy */
    virtual StringIterator getPolicy(const std::string& domain, Identity* id) = 0;

    /** @copydoc VOS::AccessControlState::getAvailablePolicies */
    virtual StringIterator getAvailablePolicies(const std::string& domain) = 0;

    /** @copydoc VOS::AccessControlState::addToACL(const std::string& ACLname, Identity* id) */
    virtual void addToACL(const std::string& ACLname, Identity* id) = 0;

    /** @copydoc VOS::AccessControlState::addToACL(const std::string& ACLname, Group* grp) */
    virtual void addToACL(const std::string& ACLname, Group* grp) = 0;

    /** @copydoc VOS::AccessControlState::removeFromACL(const std::string& ACLname, Identity* id) */
    virtual void removeFromACL(const std::string& ACLname, Identity* id) = 0;

    /** @copydoc VOS::AccessControlState::removeFromACL(const std::string& ACLname, Group* grp) */
    virtual void removeFromACL(const std::string& ACLname, Group* grp) = 0;

    /** @copydoc VOS::AccessControlState::deleteACL */
    virtual void deleteACL(const std::string& policies) = 0;

    /** @copydoc VOS::AccessControlState::getDefaultPolicy */
    virtual std::string getDefaultPolicy(const std::string& domain = "") = 0;

    /** @copydoc VOS::AccessControlState::setDefaultPolicy */
    virtual void setDefaultPolicy(const std::string& policy) = 0;

    /** @copydoc VOS::AccessControlState::getAllACLs */
    virtual ACLIterator getAllACLs() = 0;
};

}

#endif