Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members | Related Pages | Examples

VOS::Vobject Class Reference

This is the abstract class that defines the basic API common to all virtual objects. More...

#include <vos/corelibs/vos/vobject.hh>

Inheritance diagram for VOS::Vobject:

VOS::RefCounted VOS::MetaObject VOS::VobjectImplementation VOS::LocalMetaObject VOS::RemoteMetaObject VOS::Site VOS::LocalVobject VOS::RemoteVobject VOS::LocalSite VOS::RemoteSite VOS::LocalSite VOS::RemoteSite VOS::LocalMetaObject VOS::RemoteMetaObject VOS::LocalSocketSite VOS::RemoteSocketSite VOS::RemoteStreamSite VOS::LocalSocketSite VOS::RemoteSocketSite VOS::RemoteStreamSite VOS::LocalSite VOS::RemoteSite List of all members.

Public Types

Public Member Functions

Static Public Member Functions


Detailed Description

This is the abstract class that defines the basic API common to all virtual objects.

Definition at line 55 of file vobject.hh.


Member Typedef Documentation

typedef deque<Vobject::ParentChildRelation*> VOS::Vobject::ChildList
 

Definition at line 103 of file vobject.hh.

Referenced by VOS::VobjectImplementation::addChildListener(), and VOS::RemoteSite::unlockChildNotifyOutgoing().

typedef set<Vobject::ParentChildRelation*, Vobject::ParentChildRelation::Cmp> VOS::Vobject::ParentSet
 

Definition at line 102 of file vobject.hh.

Referenced by VOS::VobjectImplementation::addParentListener(), and VOS::RemoteSite::unlockParentNotifyOutgoing().

typedef set<string> VOS::Vobject::TypeSet
 

Definition at line 104 of file vobject.hh.

Referenced by VOS::VobjectImplementation::addTypeListener(), VOS::RemoteSite::notifyChildInserted(), and VOS::RemoteSite::unlockTypeNotifyOutgoing().


Member Function Documentation

virtual void VOS::Vobject::addChildListener ChildChangeListener cl,
bool  notifyImmediately = true
[pure virtual]
 

Adds some object callback to be notified when the child list changes.

The child listener will immediately be issued a notifyChildInserted() for each child.

Parameters:
cl The listener object. If this object is also a RefCounted object, reference counting will be done correctly.
notifyImmediately if true, notify listener immediately (before returning). otherwise defer until a future update

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteVobject, and VOS::VobjectImplementation.

virtual void VOS::Vobject::addFlag const string &  flag  )  [pure virtual]
 

Add a flag string.

Mainly useful for doing tree walks, when you want to mark an object as already having been touched.

Parameters:
flag the flag string

Implemented in VOS::LocalMetaObject, VOS::RemoteMetaObject, and VOS::VobjectImplementation.

virtual void VOS::Vobject::addParentListener ParentChangeListener pl,
bool  notifyImmediately = true
[pure virtual]
 

Adds some object callback to be notified when the parent set changes.

Parameters:
pl the listener object 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.

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteVobject, and VOS::VobjectImplementation.

virtual void VOS::Vobject::addType const string &  s  )  [pure virtual]
 

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.

Parameters:
s the type string

Implemented in VOS::LocalMetaObject, VOS::LocalVobject, VOS::RemoteMetaObject, and VOS::RemoteVobject.

virtual void VOS::Vobject::addTypeListener TypeChangeListener tl,
bool  notifyImmediately = true
[pure virtual]
 

Adds some object callback to be notified when the type set changes.

Parameters:
tl the listener object.
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.

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteVobject, and VOS::VobjectImplementation.

virtual bool VOS::Vobject::checkFlag const string &  flag  )  [pure virtual]
 

Check the flag string.

Parameters:
flag the flag string
Returns:
whether the flag string is set

Implemented in VOS::LocalMetaObject, VOS::RemoteMetaObject, and VOS::VobjectImplementation.

virtual Vobject::ParentChildRelation& VOS::Vobject::findChild const string &  path  )  throw (NoSuchObjectError, AccessControlError, RemoteError) [pure virtual]
 

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.

Parameters:
path either the child name or #position
Returns:
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
Exceptions:
NoSuchObjectError if the path is illegal
AccessControlError if the site reported the user is not allowed that information

Implemented in VOS::LocalMetaObject, VOS::RemoteMetaObject, VOS::RemoteVobject, and VOS::VobjectImplementation.

virtual Vobject& VOS::Vobject::findObject const string &  path  )  throw (NoSuchSiteError, NoSuchObjectError, URL::BadURLError, AccessControlError, RemoteError) [pure virtual]
 

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 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.

Parameters:
path the path to the object we want to find
Returns:
the object, if found. NOTE YOU MUST CALL release() WHEN DONE OR USE A rREF() BLOCK
Exceptions:
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.)
NoSuchObjectError if that object path does not exist on the site
URL::BadURLError if there is a syntax error in the supplied URL
AccessControlError if the site reported that the user is not allowed that information

Implemented in VOS::LocalMetaObject, VOS::RemoteMetaObject, VOS::RemoteVobject, and VOS::VobjectImplementation.

Referenced by VOS::VobjectImplementation::findObject().

Vobject & Vobject::findObjectFromRoot const string &  path  )  throw (NoSuchSiteError, NoSuchObjectError, URL::BadURLError, AccessControlError, RemoteError) [static]
 

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.

Parameters:
path the path to the object we want to find
Returns:
the object, if found. NOTE YOU MUST CALL release() WHEN DONE OR USE A rREF() BLOCK
Exceptions:
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
NoSuchObjectError if that object path does not exist on the site
URL::BadURLError if there is a syntax error in the supplied URL
AccessControlError if the site reported that the user is not allowed that information

Definition at line 124 of file vobject.cc.

Referenced by VOS::RemoteSite::createMetaObject().

virtual Vobject::ParentChildRelation& VOS::Vobject::findParent Vobject parent  )  throw (NoSuchObjectError, AccessControlError, RemoteError) [pure virtual]
 

Find a parent.

This tests to see if the supplied Vobject is marked as a parent of this Vobject.

Parameters:
parent the parent object
Returns:
the parent-child relation. NOTE YOU MUST CALL release() WHEN DONE OR USE A rREF() BLOCK
Exceptions:
NoSuchObjectError if the object is NOT a parent
AccessControlError if the site reported the user is not allowed that information

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, and VOS::VobjectImplementation.

virtual const ChildList& VOS::Vobject::getChildren  )  throw (AccessControlError, RemoteError) [pure virtual]
 

Get the set of parent-child relationships in which this object is the parent.

Returns:
a set of parent-child relations
Warning:
You should always assign the results of getChildren to a variable. Do NOT do this:
       for(Vobject::ChildList::const_iterator i = v->getChildren().begin();
            i != v->getChildren().end(); i++) {
            ...
       }
Instead, you should do this:
       const ChildList& cl = v->getChildren();
       for(Vobject::ChildList::const_iterator i = cl.begin(); i != cl.end(); i++) {
            ...
       }
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.

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteVobject, and VOS::VobjectImplementation.

Referenced by VOS::RemoteSite::unlockChildNotifyOutgoing().

virtual const string& VOS::Vobject::getName  )  [pure virtual]
 

Get the site name of this object.

Returns:
the name string

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, and VOS::VobjectImplementation.

Referenced by operator==().

virtual const ParentSet& VOS::Vobject::getParents  )  throw (AccessControlError, RemoteError) [pure virtual]
 

Get the set of parent-child relationships in which this object is the child.

Returns:
a set of parent-child relations

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteVobject, and VOS::VobjectImplementation.

Referenced by VOS::RemoteSite::unlockParentNotifyOutgoing().

virtual Site& VOS::Vobject::getSite  )  [pure virtual]
 

Get the site this object resides on.

Returns:
the site object. NOTE YOU MUST CALL release() WHEN DONE OR USE A rREF() BLOCK

Implemented in VOS::LocalMetaObject, VOS::LocalSite, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteSite, VOS::Site, and VOS::VobjectImplementation.

Referenced by VOS::RemoteVobject::initFields(), and operator==().

virtual const TypeSet& VOS::Vobject::getTypes  )  throw (AccessControlError, RemoteError) [pure virtual]
 

Return a set of type names for the types supported by this object.

Returns:
the set of type names

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteVobject, and VOS::VobjectImplementation.

Referenced by VOS::RemoteSite::unlockTypeNotifyOutgoing().

virtual const URL& VOS::Vobject::getURL  )  [pure virtual]
 

Get the URL path (in the form "vop://site/name").

Returns:
the URL

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, and VOS::VobjectImplementation.

Referenced by VOS::RemoteVobject::initFields(), VOS::RemoteSite::notifyChildInserted(), VOS::RemoteSite::notifyChildRemoved(), VOS::RemoteSite::notifyChildReplaced(), VOS::RemoteSite::notifyParentInserted(), VOS::RemoteSite::notifyParentRemoved(), VOS::RemoteSite::notifyTypeInserted(), VOS::RemoteSite::notifyTypeRemoved(), VOS::RemoteSite::unlockChildNotifyOutgoing(), VOS::RemoteSite::unlockParentNotifyOutgoing(), and VOS::RemoteSite::unlockTypeNotifyOutgoing().

virtual bool VOS::Vobject::hasMessageAvailable  )  [pure virtual]
 

Returns if the object has a message available to be dequeued by receiveMessage().

Returns:
True if receiveMessage will succeed, false if receiveMessage will throw an exception.

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, and VOS::VobjectImplementation.

virtual bool VOS::Vobject::hasUpdateMessageAvailable  )  [pure virtual]
 

Returns if the object has a message available to be dequeued by receiveUpdateMessage().

Returns:
True if receiveMessage() will succeed, false if receiveMessage will throw an exception.

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, and VOS::VobjectImplementation.

virtual void VOS::Vobject::insertChild int  position,
const string &  contextual_name,
Vobject child
throw (AccessControlError, RemoteError) [pure virtual]
 

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.

Parameters:
position the position
contextual_name This is the name, specific to this parent-child relation, used for refering to this object by path.
child the child object, in question
Exceptions:
AccessControl if this object (when it is remote) doesn't approve of this action.

Implemented in VOS::LocalMetaObject, VOS::LocalSite, VOS::LocalVobject, VOS::RemoteMetaObject, and VOS::RemoteVobject.

virtual bool VOS::Vobject::isLocal  )  [pure virtual]
 

Return true if this object is local, false if not.

Returns:
whether it is local

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteStreamSite, and VOS::VobjectImplementation.

virtual bool VOS::Vobject::isRemote  )  [pure virtual]
 

Return true if this object is remote, false if not.

Returns:
whether it is remote

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteStreamSite, and VOS::VobjectImplementation.

bool Vobject::operator== Vobject v  ) 
 

Provide our own comparison function for objects which are logically equivilent in terms of the Vobject system.

Parameters:
s the object to compare this to
Returns:
if these objects are equivalent

Definition at line 57 of file vobject.cc.

bool Vobject::operator== Vobject v  ) 
 

Provide our own comparison function for objects which are logically equivilent in terms of the Vobject system.

Parameters:
the object to compare this to
Returns:
v if these objects are equivalent

Definition at line 47 of file vobject.cc.

virtual Message* VOS::Vobject::receiveMessage  )  throw (MessageQueueEmptyError) [pure virtual]
 

Gets the next message the object has received.

Exceptions:
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.
Returns:
the message. NOTE YOU MUST CALL release() WHEN DONE OR USE vRef!

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, and VOS::VobjectImplementation.

virtual Message* VOS::Vobject::receiveUpdateMessage  )  throw (MessageQueueEmptyError) [pure virtual]
 

Gets the next update message the object has received.

Exceptions:
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.
Returns:
the message. NOTE YOU MUST CALL release() WHEN DONE OR USE vRef!

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, and VOS::VobjectImplementation.

virtual void VOS::Vobject::removeChild int  position  )  throw (AccessControlError, RemoteError) [pure virtual]
 

Remove the child at some position.

See setChild() for more information on positions.

Parameters:
position the position
Exceptions:
AccessControl if this object (when it is remote) doesn't approve of this action.

Implemented in VOS::LocalMetaObject, VOS::LocalSite, VOS::LocalVobject, VOS::MetaObject, VOS::RemoteMetaObject, and VOS::RemoteVobject.

virtual void VOS::Vobject::removeChildListener ChildChangeListener cl  )  [pure virtual]
 

Removes an existing object callback, previously added with addChildListener().

Parameters:
cl the listener object If this object is also a RefCounted object, reference counting will be done correctly.

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteVobject, and VOS::VobjectImplementation.

virtual void VOS::Vobject::removeFlag const string &  flag  )  [pure virtual]
 

Remove a flag string.

Parameters:
flag the flag string

Implemented in VOS::LocalMetaObject, VOS::RemoteMetaObject, and VOS::VobjectImplementation.

virtual void VOS::Vobject::removeParentListener ParentChangeListener pl  )  [pure virtual]
 

Removes an existing object callback, previously added with addParentListener().

Parameters:
pl the listener object If this object is also a RefCounted object, reference counting will be done correctly.

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteVobject, and VOS::VobjectImplementation.

virtual void VOS::Vobject::removeTypeListener TypeChangeListener tl  )  [pure virtual]
 

Removes an existing object callback, previously added with addTypeListener().

Parameters:
tl the listener object If this object is also a RefCounted object, reference counting will be done correctly.

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteVobject, and VOS::VobjectImplementation.

virtual void VOS::Vobject::saveState MessageBlock output,
set< string > &  types,
bool  portable
[pure virtual]
 

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.
Parameters:
output messages should be appended to this message block
types the type set that should be output for this vobject
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.

Implemented in VOS::LocalMetaObject, VOS::RemoteMetaObject, and VOS::VobjectImplementation.

virtual void VOS::Vobject::sendMessage MessageBlock m  )  [pure virtual]
 

Sends a block of messages to the object.

This may trigger immediate processing of the message if the object is local.

Parameters:
m A pointer to the message which is being sent. Its reference count will be increased as necssary.

Implemented in VOS::LocalMetaObject, VOS::LocalSite, VOS::LocalVobject, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteSite, VOS::RemoteSocketSite, VOS::RemoteStreamSite, VOS::RemoteVobject, and VOS::Site.

virtual void VOS::Vobject::sendMessage Message m  )  [pure virtual]
 

Sends a message to the object.

This may trigger immediate processing of the message if the object is local.

Parameters:
m A pointer to the message which is being sent. Its reference count will be increased as necssary.

Implemented in VOS::LocalMetaObject, VOS::LocalSite, VOS::LocalSocketSite, VOS::LocalVobject, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteSite, VOS::RemoteSocketSite, VOS::RemoteStreamSite, VOS::RemoteVobject, and VOS::Site.

virtual void VOS::Vobject::sendUpdateMessage Message m  )  [pure virtual]
 

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.

Parameters:
m A pointer to the message which is being sent. Its reference count will be increased as necssary.

Implemented in VOS::LocalMetaObject, VOS::MetaObject, VOS::RemoteMetaObject, VOS::RemoteSite, VOS::RemoteVobject, and VOS::VobjectImplementation.

virtual void VOS::Vobject::setChild int  position,
const string &  contextual_name,
Vobject child
throw (AccessControlError, RemoteError) [pure virtual]
 

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.
Parameters:
position the position
contextual_name This is the name, specific to this parent-child relation, used for refering to this object by path.
child the child object, in question
Exceptions:
AccessControl if this object (when it is remote) doesn't approve of this action.

Implemented in VOS::LocalMetaObject, VOS::LocalSite, VOS::LocalVobject, VOS::RemoteMetaObject, VOS::RemoteSite, and VOS::RemoteVobject.


The documentation for this class was generated from the following files:
Generated on Tue Aug 12 03:56:07 2003 for Interreality Project - VOS by doxygen 1.3.2