interreality.org [VOS]
[Home] [About]
[Screenshots]
 [Download]
[News]
 [Community]
[Documentation] [Manual]
[Bugs & Requests] [Wiki]
VOS::Site

VOS::Site Class Reference
[libvos]

#include <vos/vos/site.hh>

Inheritance diagram for VOS::Site:

VOS::VobjectBase VOS::Vobject VUtil::RefCounted List of all members.

Detailed Description

A site is the root of any collection of Vobjects.

It is a normal Vobject in addition to having features particular to the site. A site is the connection point by which a Vobject may exchange messages with another Vobject on another host across the Internet.

Definition at line 166 of file site.hh.

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Member Typedef Documentation

typedef MetaObject*(*) VOS::Site::metaobject_extender_t(VobjectBase *superobject, const std::string &type)

Definition at line 169 of file site.hh.

Constructor & Destructor Documentation

VOS::Site::Site ( bool  islocal = true  ) 

Constructor.

Parameters:
islocal is this a local site or remote site. You will probably always want a local site.

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

Destructor.

Member Function Documentation

virtual void VOS::Site::addHostAlias ( const std::string &  h  )  [virtual]

Add a host alias to this site.

A host alias is a legal name by which this site may be refered to.

Parameters:
h the host alias in the form "proto://hostname:port"

static void VOS::Site::addLocalMetaObjectFactory ( const char *  classname,
metaobject_extender_t  newmethod 
) [static]

Add a factory for creating MetaObjects that extend remote Vobjects.

Will replace any existing factory registered to this classname.

Parameters:
classname a C++ or VOS interface this implements
newmethod the actual factory function that constructs the MetaObject

virtual void VOS::Site::addMessageBlock ( MessageBlock *  m  )  [virtual]

Save a message block template for later retrival and execution.

Parameters:
m the message block

static void VOS::Site::addProtocolHandler ( const std::string &  protocol,
ProtocolHandler &  ph 
) [static]

Add a handler for connecting to sites with some protocol.

Parameters:
protocol The protocol name. This is the first part of the URL, such as "vop" in "vop://interreality.org"
ph The protocol handler object. This will be called to do the work of connecting to a remote site using this protocol.
Note:
Actually having multiple protocols at once hasn't really been tried yet, but these hooks are a start.

static void VOS::Site::addRemoteMetaObjectFactory ( const char *  classname,
const char *  vostype,
metaobject_extender_t  newmethod 
) [static]

Add a factory for creating MetaObjects that extend remote Vobjects.

Will replace any existing factory registered to this classname.

Parameters:
classname a C++ or VOS interface this implements
vostype the VOS type this implements
newmethod the actual factory function that constructs the MetaObject

static void VOS::Site::addSite ( Site &  s  )  [static]

Add a site to the master table of known sites.

Parameters:
s the site to be added

virtual void VOS::Site::addSiteExtension ( SiteExtension *  sx  )  [virtual]

Attach a SiteExtension object which may extend the actions of various site-specific methods.

Parameters:
sx the extension object

Referenced by main().

virtual void VOS::Site::addURL ( const VUtil::URL &  u  )  [virtual]

Add a new URL for this site.

Note:
at the moment this actually replaces the old URL completely; it doesn't handle having multiple URLs properly. This exists to solve a specific problem. Don't use it.

static std::string VOS::Site::convertClassnameToVOStype ( const std::string &  n  )  [static]

Map a C++ MetaObject classname to the VOS type it implements.

For example: 

        convertClassnameToVOStype(typeid(Property).name()) == "property:property"

template<class T>
VUtil::vRef<T> VOS::Site::createVobject ( const std::string &  name = "",
const std::string &  ac = "" 
) [inline]

Create a new Vobject on this site.

The template parameter(s) are the MetaObject interfaces that you want this Vobject to support.

Parameters:
name The requested name. This will be made unique by appending extra characters if there already exits an object with this name. May be empty in which case a unique name will be generated.
ac an access control policy to assign to this object
Returns:
the newly-constructed Vobject, which has been meta_cast<> to the first template paramter.

Definition at line 283 of file site.hh.

Referenced by main().

template<class T, class T2>
VUtil::vRef<T> VOS::Site::createVobject2 ( const std::string &  name = "",
const std::string &  ac = "" 
) [inline]

Create a new Vobject on this site.

The template parameter(s) are the MetaObject interfaces that you want this Vobject to support.

Parameters:
name The requested name. This will be made unique by appending extra characters if there already exits an object with this name. May be empty in which case a unique name will be generated.
ac an access control policy to assign to this object
Returns:
the newly-constructed Vobject, which has been meta_cast<> to the first template paramter.

Definition at line 292 of file site.hh.

Referenced by main().

template<class T, class T2, class T3>
VUtil::vRef<T> VOS::Site::createVobject3 ( const std::string &  name = "",
const std::string &  ac = "" 
) [inline]

Create a new Vobject on this site.

The template parameter(s) are the MetaObject interfaces that you want this Vobject to support.

Parameters:
name The requested name. This will be made unique by appending extra characters if there already exits an object with this name. May be empty in which case a unique name will be generated.
ac an access control policy to assign to this object
Returns:
the newly-constructed Vobject, which has been meta_cast<> to the first template paramter.

Definition at line 302 of file site.hh.

template<class T, class T2, class T3, class T4>
VUtil::vRef<T> VOS::Site::createVobject4 ( const std::string &  name = "",
const std::string &  ac = "" 
) [inline]

Create a new Vobject on this site.

The template parameter(s) are the MetaObject interfaces that you want this Vobject to support.

Parameters:
name The requested name. This will be made unique by appending extra characters if there already exits an object with this name. May be empty in which case a unique name will be generated.
ac an access control policy to assign to this object
Returns:
the newly-constructed Vobject, which has been meta_cast<> to the first template paramter.

Definition at line 312 of file site.hh.

template<class T, class T2, class T3, class T4, class T5>
VUtil::vRef<T> VOS::Site::createVobject5 ( const std::string &  name = "",
const std::string &  ac = "" 
) [inline]

Create a new Vobject on this site.

The template parameter(s) are the MetaObject interfaces that you want this Vobject to support.

Parameters:
name The requested name. This will be made unique by appending extra characters if there already exits an object with this name. May be empty in which case a unique name will be generated.
ac an access control policy to assign to this object
Returns:
the newly-constructed Vobject, which has been meta_cast<> to the first template paramter.

Definition at line 322 of file site.hh.

VUtil::vRef<Vobject> VOS::Site::createVobjectA ( const char *  name = "",
const char *  t1 = 0,
const char *  t2 = 0,
const char *  t3 = 0,
const char *  t4 = 0,
const char *  t5 = 0 
) [inline]

Create a new Vobject on this site.

Use this creation method if your new object will have to types, or you want to specify the types as strings rather than using the template createVobject() methods.

Parameters:
name The requested name. This will be made unique by appending extra characters if there already exits an object with this name. May be empty in which case a unique name will be generated.
t1...t5 The list of VOS types that this object should support. MetaObject extensions for the supplied types will be added if the appropriate factories have been registered.
Returns:
the newly-constructed Vobject

Definition at line 258 of file site.hh.

Referenced by main().

virtual VUtil::vRef<Vobject> VOS::Site::createVobjectT ( const char *  name,
const std::deque< std::string > &  typelist 
) [inline, virtual]

Create a new Vobject on this site.

Parameters:
name The requested name. This will be made unique by appending extra characters if there already exits an object with this name. May be empty in which case a unique name will be generated.
typelist The list of VOS types that this object should support. MetaObject extensions for the supplied types will be added if the appropriate factories have been registered.
Returns:
the newly-constructed Vobject

Definition at line 241 of file site.hh.

virtual VUtil::vRef<Vobject> VOS::Site::createVobjectT ( Vobject *  requester,
const char *  name,
const std::deque< std::string > &  typelist 
) [virtual]

Create a new Vobject on this site.

Parameters:
requester The object requesting this action. If it isremote this will be access-control checked. May be null.
name The requested name. This will be made unique by appending extra characters if there already exits an object with this name. May be empty in which case a unique name will be generated.
typelist The list of VOS types that this object should support. MetaObject extensions for the supplied types will be added if the appropriate factories have been registered.
Returns:
the newly-constructed Vobject

static void VOS::Site::dumpFactoryTables (  )  [static]

Print the factory registration table to stderr.

(For debugging purposes)

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

Ask that all known references to this object to release their references so the object can be deleted, by calling ObjectExciseListener::notifyObjectExcise().

Note:
This method is virtual and objects making use of this class will probably want to supply their own additional code to detach from linking data structures. Make sure to call RefCounted::excise() in yoru override method so that the excise listeners are called back. Overriding excise() will probably be sufficient for most uses; the purpose of the ObjectExciseListener facility is for plugin/application level hooks which may be beyond the scope of your immediate code.

Reimplemented from VOS::VobjectBase.

static VUtil::vRef<Site> VOS::Site::findSite ( const std::string &  s,
bool  contact = true 
) [static]

Find a site by its host alias.

Will contact remote sites if "contact" is true.

Parameters:
s the site host alias (in the form "proto://host:port", such as "vop://interreality.org")
contact if true, try and contact remote site, otherwise throw NoSuchSiteError if we are not already connected to this site
Returns:
the site matching that host alias.
Exceptions:
NoSuchSiteError if the site is not found or could not be contacted

virtual std::string VOS::Site::generateUniqueName (  )  [virtual]

Returns:
a random and unique numerical name. (Used by the createVobject methods).

static SiteIterator VOS::Site::getAllSites (  )  [static]

Get a list of all known sites, local and remote.

Returns:
an iterator

virtual StringIterator VOS::Site::getHostAliases (  )  [virtual]

Get a list of host alias.

Returns:
the set of host valid host aliases.

static metaobject_extender_t VOS::Site::getLocalMetaObjectFactory ( const char *  classname  )  [static]

Fetch the factory function that constructs MetaObjects for the supplied class.

Parameters:
classname the C++ class name (via typeid(TheClass).name()) or VOS type
Returns:
the factory function (which can be called to construct a MetaObject) or 0 if there is no factory registered for this class.

VUtil::vRef<Site> VOS::Site::getLocalSite (  )  [inline]

For a remote site, get the local site object to which we are connected.

Definition at line 569 of file site.hh.

virtual VUtil::vRef<MessageBlock> VOS::Site::getMessageBlock ( const std::string &  s  )  [virtual]

Retrive a saved message block template.

Parameters:
s the name of the message block.
Returns:
The message block
Exceptions:
NoSuchMessageBlockError if it was not found

virtual VUtil::vRef<Identity> VOS::Site::getMyIdentity (  )  [virtual]

Returns the identity object on this remote site which we have authenticated ourselves to.

This identity object is used by the remote site to determine which access control policies to apply to us. Only meaningful if this is a remote site.

Returns:
an identity object (which should always a remote object attached to this site), or a null vRef if we have not yet established our identity to this site.

virtual VUtil::vRef<Identity> VOS::Site::getPeerIdentity (  )  [virtual]

Returns the identity of this peer.

This is used to apply access control to any commands they send.

Returns:
the Identity Vobject or a null vRef if the peer has not yet established an Identity (default access control polices are applied in this case)

static ProtocolHandler* VOS::Site::getProtocolHandler ( const std::string &  protocol  )  [static]

Returns:
the protocol handler object for this protocol

static metaobject_extender_t VOS::Site::getRemoteMetaObjectFactory ( const char *  classname  )  [static]

Fetch the factory function that constructs MetaObjects for the supplied class.

Parameters:
classname the C++ class name (via typeid(TheClass).name()) or VOS type
Returns:
the factory function (which can be called to construct a MetaObject) or 0 if there is no factory registered for this class.

virtual VUtil::vRef<Site> VOS::Site::getSite (  )  const [virtual]

Returns:
the site this object resides on.

Reimplemented from VOS::VobjectBase.

virtual bool VOS::Site::hasHostAlias ( const std::string &  h  )  [virtual]

Tests for the existance of a given host alias.

Parameters:
h the host alias
Returns:
true if h is a legal host alias, false if not

virtual void VOS::Site::insertMessageFilter ( int  pos,
MessageFilter *  mf 
) [virtual]

Add a message filter.

Bug:
is this implemented?

virtual void VOS::Site::msgSendImpl ( boost::mutex &  usehandlers_mutex,
HandlerMap &  usehandlers,
Message *  msg 
) [protected, virtual]

template<class C>
C* VOS::Site::querySiteExtension (  )  [inline]

Returns:
the first site extension that can be dynamic_cast<> to the template parameter C, or null if no extension has the desired type.

Definition at line 578 of file site.hh.

virtual void VOS::Site::removeHostAlias ( const std::string &  h  )  [virtual]

Remove a host alias of this site.

Parameters:
h the host alias in the form "proto://hostname:port"

static void VOS::Site::removeLocalMetaObjectFactory ( const char *  classname,
metaobject_extender_t  oldmethod 
) [static]

Remove the supplied factory function that is registered to this classname.

Nothing will be removed unless both parameters match.

Parameters:
classname the C++ class name (via typeid(TheClass).name()) or VOS type it was registered with
oldmethod the factory function it was registered with

virtual void VOS::Site::removeMessageBlock ( MessageBlock *  m  )  [virtual]

Remove a saved message block template.

Parameters:
m the message block

virtual void VOS::Site::removeMessageFilter ( MessageFilter *  m  )  [virtual]

Add a message filter.

Bug:
is this implemented?

virtual void VOS::Site::removeMessageFilter ( int  pos  )  [virtual]

Add a message filter.

Bug:
is this implemented?

static void VOS::Site::removeProtocolHandler ( const std::string &  protocol  )  [static]

Remove the protocol handler object for this protocol.

static void VOS::Site::removeRemoteMetaObjectFactory ( const char *  classname,
metaobject_extender_t  oldmethod 
) [static]

Remove the supplied factory function that is registered to this classname.

Nothing will be removed unless both parameters match.

Parameters:
classname the C++ class name (via typeid(TheClass).name()) or VOS type it was registered with
oldmethod the factory function it was registered with

static void VOS::Site::removeSite ( Site &  s  )  [static]

Remove a site from the master table of known sites.

Parameters:
s the site to remove

virtual void VOS::Site::renameVobject ( const std::string &  oldname,
const std::string &  newname 
) [inline, virtual]

Change the site name of this Vobject.

Parameters:
oldname the old Vobject
newname the new name for the Vobject
Exceptions:
NameAlreadyUsedError if there is already a Vobject with the new name

Definition at line 523 of file site.hh.

virtual void VOS::Site::renameVobject ( Vobject *  requester,
const std::string &  oldname,
const std::string &  newname 
) [virtual]

Change the site name of this Vobject.

Parameters:
requester the vobject requesting this change. If it is remote, this action will be access control checked. (may be null)
oldname the old Vobject
newname the new name for the Vobject
Exceptions:
NameAlreadyUsedError if there is already a Vobject with the new name

virtual void VOS::Site::sendMessage ( MessageBlock *  m  )  [virtual]

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

Reimplemented from VOS::VobjectBase.

virtual void VOS::Site::sendMessage ( Message *  m  )  [virtual]

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

Reimplemented from VOS::VobjectBase.

void VOS::Site::setLocalSite ( Site *  s  )  [inline]

For a remote site, set the local site object to which we are connected.

Definition at line 565 of file site.hh.

virtual void VOS::Site::setMyIdentity ( Identity *  id  )  [virtual]

Sets the cached value for our identity on this remote site.

Does not actually change our effective identity on the remote site --- use an authentication mechanism such as RemotePasswordAuth to do that!

Parameters:
id the identity object to use (should be a Identity Vobject attached to this remote site)

virtual void VOS::Site::setPeerIdentity ( Identity *  id  )  [virtual]

Set the identity of this peer.

This is used to determine which access control policy to apply to this peer. May be done manually by the application, or using an authentication metaobject such as LocalPasswordAuth.

Parameters:
id the identity to use (must be a local object)

virtual std::string VOS::Site::uniqueName ( const char *  base  )  [virtual]

A Vobject name unique on this site by appending characters to the given base as necesary.

Used by the createVobject methods.

Parameters:
base the base name to start from
Returns:
the new name, if the name supplied in the base paramater was unique, then just the base name will be returned

The documentation for this class was generated from the following file: