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

VOS::MetaObject Class Reference

This class is responsible for managing a group of object extensions under a single logical Vobject. More...

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

Inheritance diagram for VOS::MetaObject:

VOS::Vobject VOS::RefCounted VOS::LocalMetaObject VOS::RemoteMetaObject VOS::Site VOS::LocalSite VOS::RemoteSite VOS::LocalSite VOS::RemoteSite VOS::LocalSocketSite VOS::RemoteSocketSite VOS::RemoteStreamSite VOS::LocalSocketSite VOS::RemoteSocketSite VOS::RemoteStreamSite List of all members.

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

This class is responsible for managing a group of object extensions under a single logical Vobject.

Messages sent to it using sendMessage() and sendUpdateMessage() are propagated to any extension plugins which have been attached to it. Metaobjects allow you to switch between multiple interfaces using meta_cast, allowing you to request a certain C++ class interface such as Property or Talkative from a given Vobject, if the Vobject has that type.

Definition at line 44 of file metaobject.hh.

Constructor & Destructor Documentation

VOS::MetaObject::MetaObject (  MetaObject *  superobject  )  [protected]
 

virtual VOS::MetaObject::~MetaObject (   )  [virtual]
 

destructor

Member Function Documentation

virtual void VOS::MetaObject::acquire (   )  [virtual]
 

Note that this means you have a handle on the entire logical object!

Reimplemented from VOS::RefCounted.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

Referenced by VOS::RemoteMetaObject::acquire(), VOS::VobjectImplementation::getSite(), VOS::Message::getSourceSite(), VOS::Message::setSourceSite(), and VOS::VobjectImplementation::VobjectImplementation().

virtual void VOS::MetaObject::addChildListener (  ChildChangeListener *  cl,
bool  notifyImmediately = true
)  [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

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

Referenced by VOS::RemoteMetaObject::addChildListener().

virtual void VOS::MetaObject::addFlag (  const std::string &  flag  )  [virtual]
 

Referenced by VOS::RemoteMetaObject::addFlag().

template<class T>
void VOS::MetaObject::addMessageHandler (  const std::string &  method,
T *  theobj,
void(T::*  MessageHandler)(Message *),
bool  addExHandler = false
)  [inline]
 

Definition at line 286 of file metaobject.hh.

virtual void VOS::MetaObject::addObjectExtension (  MetaObject *  moe  )  [virtual]
 

Add an instantiated extension object to this metaobject.

End users generally shouldn't need to do this, use MetaFactory::extendLocalObject() instead.

Note:
Extension object is deleted when the destructor for this metaobject is called.
Parameters:
moe the metaobject to be added

virtual void VOS::MetaObject::addParentListener (  ParentChangeListener *  pl,
bool  notifyImmediately = true
)  [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.

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

Referenced by VOS::RemoteMetaObject::addParentListener().

virtual void VOS::MetaObject::addType (  const std::string &  s  )  [virtual]
 

Referenced by VOS::RemoteMetaObject::addType().

virtual void VOS::MetaObject::addTypeListener (  TypeChangeListener *  tl,
bool  notifyImmediately = true
)  [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.

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

Referenced by VOS::RemoteMetaObject::addTypeListener().

template<class T>
void VOS::MetaObject::addUpdateHandler (  const std::string &  method,
T *  theobj,
void(T::*  MessageHandler)(Message *),
bool  addExHandler = false
)  [inline]
 

Definition at line 293 of file metaobject.hh.

virtual bool VOS::MetaObject::checkFlag (  const std::string &  flag  )  [virtual]
 

Referenced by VOS::RemoteMetaObject::checkFlag().

virtual void VOS::MetaObject::doExcise (   )  [protected, virtual]
 

This is where you put type-handler specific code to respond to an excise().

It will be called exactly once.

virtual void VOS::MetaObject::doSaveState (  MessageBlock &  output,
std::set< std::string > &  types,
bool  portable
)  [protected, virtual]
 

This is where you put type-handler specific save state code.

Parameters:
output The messageblock to append your messages to
types The types for the object that should be output as part of this save state. Some save state handlers may want to modify this.
See also:
Vobject::saveState

Referenced by VOS::RemoteMetaObject::saveState().

virtual void VOS::MetaObject::excise (   )  [virtual]
 

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

Reimplemented from VOS::RefCounted.

Reimplemented in VOS::LocalMetaObject, VOS::RemoteMetaObject, VOS::RemoteSite, and VOS::RemoteSocketSite.

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

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

Referenced by VOS::Vobject::findObjectFromRoot().

virtual Vobject::ParentChildRelation& VOS::MetaObject::findParent (  Vobject &  parent  )  throw (NoSuchObjectError, AccessControlError, RemoteError) [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

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

virtual const ChildList& VOS::MetaObject::getChildren (   )  throw (AccessControlError, RemoteError) [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.

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

virtual int VOS::MetaObject::getCount (   )  [virtual]
 

Note that this counts for the entire logical object!

Reimplemented from VOS::RefCounted.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

Referenced by VOS::RemoteMetaObject::getCount(), VOS::Message::~Message(), and VOS::VobjectImplementation::~VobjectImplementation().

virtual const std::string& VOS::MetaObject::getName (   )  [virtual]
 

Get the site name of this object.

Returns:
the name string

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

Referenced by VOS::RemoteMetaObject::getName().

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

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

Returns:
a set of parent-child relations

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

virtual Site& VOS::MetaObject::getSite (   )  [virtual]
 

Get the site this object resides on.

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

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, VOS::LocalSite, VOS::RemoteMetaObject, VOS::RemoteSite, and VOS::Site.

Referenced by VOS::RemoteMetaObject::getSite().

MetaObject* VOS::MetaObject::getSuperObject (   ) 
 

Get the superobject (the object immediately containing this metaobject).

Returns:
the superobject

MetaObject* VOS::MetaObject::getTopObject (   ) 
 

Get the 'top' superobject, that is, the root of the metaobject tree.

Returns:
the top superobject

virtual const std::string VOS::MetaObject::getType (   )  [virtual]
 

Returns:
the specific MOS type name that represents the MOS interface this object is supplying.

Reimplemented in VOS::Site.

const std::deque<MetaObject*>& VOS::MetaObject::getTypeHandlers (   ) 
 

Get a vector of the extension object contained in this metaobject.

Returns:
a list of extensions

Referenced by VOS::RemoteMetaObject::handleNewType().

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

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

Returns:
the set of type names

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

virtual const URL& VOS::MetaObject::getURL (   )  [virtual]
 

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

Returns:
the URL

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

Referenced by VOS::RemoteMetaObject::getURL(), VOS::VobjectImplementation::VobjectImplementation(), and VOS::VobjectImplementation::~VobjectImplementation().

virtual bool VOS::MetaObject::hasMessageAvailable (   )  [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.

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

Referenced by VOS::RemoteMetaObject::hasMessageAvailable().

virtual bool VOS::MetaObject::hasUpdateMessageAvailable (   )  [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.

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

Referenced by VOS::RemoteMetaObject::hasUpdateMessageAvailable().

virtual void VOS::MetaObject::initialize (   )  [virtual]
 

Some MetaObject subclasses provide an initialize method to create required subobjects with default values, to set a default property access control policy, etc.

Calling this method on a top level MetaObject will call initialize() on each of it's type extensions. e.g.: 

 MetaObject* foo = site->createMetaObject("foo", typeid(A3DL::Cube).name(), typeid(Hypercard).name(), 0);
 foo->initialize();
                       // calls A3DL::Cube::initialize() and  Hypercard::initialize()
 MetaObject::meta_cast<Hypercard*>(foo)->initialize();
                       // just call Hypercard::initialize().

virtual void VOS::MetaObject::initializeSecurity (  Vobject &  requester  )  [virtual]
 

Initialize the security policy of a newly created local metaobject.

Parameters:
requester the object that requested the creation of this type extension

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

virtual bool VOS::MetaObject::isLocal (   )  [virtual]
 

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

Returns:
whether it is local

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, VOS::RemoteMetaObject, and VOS::RemoteStreamSite.

Referenced by VOS::RemoteMetaObject::isLocal().

virtual bool VOS::MetaObject::isRemote (   )  [virtual]
 

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

Returns:
whether it is remote

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, VOS::RemoteMetaObject, and VOS::RemoteStreamSite.

Referenced by VOS::RemoteMetaObject::isRemote().

template<class C>
C VOS::MetaObject::meta_cast (  MetaObject &  v,
bool  fromsuper = false
)  throw (bad_cast) [inline, static]
 

A specialized cast allowing you to switch between different extension plugins in the same logical object.

It searches the metaobject type tree of this for an instance of an extension that satisfied the requested type. You can cast any member of a logical object to any other member. For example: 

        LocalMetaObject* l = MetaFactory::createLocalMetaObject(mysite, typeid(Property).name(),
                                                                typeid(World).name(), 0);
        Property& p = MetaObject::meta_cast<Property&>(*l);
        World& w = MetaObject::meta_cast<World&>(p);
Parameters:
v the object to be cast
fromsuper Whether this search invocation started from the root, to avoid backtracking. You don't (and shouldn't) need to specify this.

Definition at line 264 of file metaobject.hh.

template<class C>
C VOS::MetaObject::meta_cast (  MetaObject *  v,
bool  fromsuper = false
)  [inline, static]
 

A specialized cast allowing you to switch between different extension plugins in the same logical object.

It searches the metaobject type tree of this for an instance of an extension that satisfied the requested type. You can cast any member of a logical object to any other member. For example: 

        LocalMetaObject* l = MetaFactory::createLocalMetaObject(mysite,
                                                                typeid(Property).name(),
                                                                typeid(World).name(),
                                                                0);
        Property* p = MetaObject::meta_cast<Property*>(l);
        World* w = MetaObject::meta_cast<World*>(p);
Parameters:
v the object to be cast
fromsuper Whether this search invocation started from the root, to avoid backtracking. You don't (and shouldn't) need to specify this.

Definition at line 235 of file metaobject.hh.

template<class C>
C VOS::MetaObject::meta_cast (  Vobject &  v  )  throw (bad_cast) [inline, static]
 

A specialized cast allowing you to switch between different extension plugins in the same logical object.

It first attempts to dynamic_cast the Vobject into a MetaObject, and then searches the metaobject type tree of this for an instance of an extension that satisfied the requested type.

Parameters:
v the object to be cast

Definition at line 207 of file metaobject.hh.

template<class C>
C VOS::MetaObject::meta_cast (  Vobject *  v  )  [inline, static]
 

A specialized cast allowing you to switch between different extension plugins in the same logical object.

It first attempts to dynamic_cast the Vobject into a MetaObject, and then searches the metaobject type tree of this for an instance of an extension that satisfied the requested type.

Parameters:
v the object to be cast

Definition at line 193 of file metaobject.hh.

virtual Message* VOS::MetaObject::receiveMessage (   )  throw (MessageQueueEmptyError) [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!

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

virtual Message* VOS::MetaObject::receiveUpdateMessage (   )  throw (MessageQueueEmptyError) [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!

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

virtual void VOS::MetaObject::release (   )  [virtual]
 

Note that this means you are releasing the entire logical object!

Reimplemented from VOS::RefCounted.

Reimplemented in VOS::LocalMetaObject, VOS::RemoteMetaObject, and VOS::RemoteSite.

Referenced by VOS::Vobject::findObjectFromRoot(), VOS::RemoteMetaObject::release(), VOS::Message::setSourceSite(), VOS::Message::~Message(), and VOS::VobjectImplementation::~VobjectImplementation().

virtual void VOS::MetaObject::removeChild (  int  position  )  throw (AccessControlError, RemoteError) [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.

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, VOS::LocalSite, and VOS::RemoteMetaObject.

virtual void VOS::MetaObject::removeChildListener (  ChildChangeListener *  cl  )  [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.

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

Referenced by VOS::RemoteMetaObject::removeChildListener().

virtual void VOS::MetaObject::removeFlag (  const std::string &  flag  )  [virtual]
 

Referenced by VOS::RemoteMetaObject::removeFlag().

template<class T>
void VOS::MetaObject::removeMessageHandler (  const std::string &  method,
T *  theobj,
void(T::*  MessageHandler)(Message *)
)  [inline]
 

Definition at line 300 of file metaobject.hh.

virtual void VOS::MetaObject::removeParentListener (  ParentChangeListener *  pl  )  [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.

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

Referenced by VOS::RemoteMetaObject::removeParentListener().

virtual void VOS::MetaObject::removeTypeListener (  TypeChangeListener *  tl  )  [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.

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, and VOS::RemoteMetaObject.

Referenced by VOS::RemoteMetaObject::removeTypeListener().

template<class T>
void VOS::MetaObject::removeUpdateHandler (  const std::string &  method,
T *  theobj,
void(T::*  MessageHandler)(Message *)
)  [inline]
 

Definition at line 305 of file metaobject.hh.

virtual void VOS::MetaObject::saveState (  MessageBlock &  output,
std::set< std::string > &  types,
bool  portable
)  [virtual]
 

Referenced by VOS::RemoteMetaObject::saveState().

virtual void VOS::MetaObject::sendMessage (  MessageBlock *  m  )  [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.

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, VOS::LocalSite, VOS::RemoteMetaObject, VOS::RemoteSite, VOS::RemoteSocketSite, VOS::RemoteStreamSite, and VOS::Site.

virtual void VOS::MetaObject::sendMessage (  Message *  m  )  [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.

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, VOS::LocalSite, VOS::LocalSocketSite, VOS::RemoteMetaObject, VOS::RemoteSite, VOS::RemoteSocketSite, VOS::RemoteStreamSite, and VOS::Site.

virtual void VOS::MetaObject::sendUpdateMessage (  Message *  m  )  [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.

Implements VOS::Vobject.

Reimplemented in VOS::LocalMetaObject, VOS::RemoteMetaObject, and VOS::RemoteSite.

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

Member Data Documentation

MetaObject* VOS::MetaObject::superobject [protected]
 

Definition at line 51 of file metaobject.hh.

Referenced by VOS::RemoteMetaObject::acquire(), VOS::RemoteMetaObject::addChildListener(), VOS::RemoteMetaObject::addFlag(), VOS::RemoteMetaObject::addParentListener(), VOS::RemoteMetaObject::addType(), VOS::RemoteMetaObject::addTypeListener(), VOS::RemoteMetaObject::checkFlag(), VOS::RemoteMetaObject::getCount(), VOS::RemoteMetaObject::getName(), VOS::RemoteMetaObject::getSite(), VOS::RemoteMetaObject::getURL(), VOS::RemoteMetaObject::hasMessageAvailable(), VOS::RemoteMetaObject::hasUpdateMessageAvailable(), VOS::RemoteMetaObject::isLocal(), VOS::RemoteMetaObject::isRemote(), meta_cast(), VOS::RemoteMetaObject::release(), VOS::RemoteMetaObject::removeChildListener(), VOS::RemoteMetaObject::removeFlag(), VOS::RemoteMetaObject::removeParentListener(), VOS::RemoteMetaObject::removeTypeListener(), VOS::RemoteMetaObject::saveState(), VOS::RemoteMetaObject::sendMessage(), and VOS::RemoteMetaObject::sendUpdateMessage().

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