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

VOS::MetaObject Class Reference
[libvos]

#include <vos/vos/metaobject.hh>

Inheritance diagram for VOS::MetaObject:

VOS::Vobject VOS::Dispatchable VUtil::RefCounted A3DL::Actor A3DL::Light A3DL::Material A3DL::Object3D A3DL::Portal A3DL::RemoteActionListener A3DL::Sector A3DL::Texture A3DL::Viewpoint Creature Hello VOS::Avatar VOS::Factory VOS::Group VOS::Hypercard VOS::Identity VOS::IrcBridge VOS::IrcClient VOS::LocalPasswordAuth VOS::LocalSearch VOS::LocalVobject VOS::LogLevelCtrl VOS::Metadata VOS::Property VOS::RemoteListener VOS::RemotePasswordAuth VOS::RemotePropertyListener VOS::RemoteSearch VOS::Services VOS::Talkative VOS::VersionedVobject VOS::VOSPlugin List of all members.

Detailed Description

This class forwards every method in the Vobject API to the VobjectBase that it is attached to.

This is primarily useful for allowing subclasses of MetaObject to be usable as Vobjects in addition to adding their own API. It also provides a couple of methods (VOS::MetaObject::doSaveState and VOS::MetaObject::doExcise) that can be overridden to provide custom behavior for those cases.

Definition at line 55 of file metaobject.hh.

Public Member Functions

Protected Member Functions

Friends

Constructor & Destructor Documentation

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

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

destructor

Member Function Documentation

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

Note that this is for the logical Vobject and not the specific MetaObject instance, i.e.

it's forwarded to the VobjectBase just like everything else.

Reimplemented from VUtil::RefCounted.

virtual void VOS::MetaObject::addChildListener ( ChildChangeListener *  cl,
bool  refresh = true 
) [virtual]

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

The

Parameters:
cl The listener object.
refresh if true, will queue up notification callbacks on the listener fully describing the current state.

Implements VOS::Vobject.

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

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.

Parameters:
flag the flag string

Implements VOS::Vobject.

virtual void VOS::MetaObject::addParentListener ( ParentChangeListener *  pl,
bool  refresh = true 
) [virtual]

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

Parameters:
pl the listener object
refresh if true, will queue up notification callbacks on the listener fully describing the current state.

Implements VOS::Vobject.

virtual void VOS::MetaObject::addToACL ( const std::string &  ACLname,
Group *  grp 
) [virtual]

Add a group to an access control list (ACL).

If this group exists in another ACL, it will be removed from that ACL first.

Parameters:
ACLname the name of the ACL. This is a comma-separated list of the access control policies to apply for each domain. For example "core:read-only,property:accept-all". Order does not matter (it will be sorted) but this access control list name is distict from just "core:read-only"!
grp the Group to add

Implements VOS::Vobject.

virtual void VOS::MetaObject::addToACL ( const std::string &  ACLname,
Identity *  id 
) [virtual]

Add an identity to an access control list (ACL).

If this identity exists in another ACL, it will be removed from that ACL first.

Parameters:
ACLname the name of the ACL. This is a comma-separated list of the access control policies to apply for each domain. For example "core:read-only,property:accept-all". Order does not matter (it will be sorted) but this access control list name is distict from just "core:read-only"!
id the Identity to add

Implements VOS::Vobject.

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

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.

Parameters:
s the type std::string

Implements VOS::Vobject.

virtual void VOS::MetaObject::addTypeListener ( TypeChangeListener *  tl,
bool  refresh = true 
) [virtual]

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

Parameters:
tl the listener object.
refresh if true, will queue up notification callbacks on the listener fully describing the current state.

Implements VOS::Vobject.

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

Check the flag std::string.

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

Implements VOS::Vobject.

virtual void VOS::MetaObject::deleteACL ( const std::string &  policies  )  [virtual]

Completely delete an ACL.

Parameters:
policies the name of the ACL. This is a comma-separated list of the access control policies to apply for each domain. For example "core:read-only,property:accept-all". Order does not matter (it will be sorted) but this access control list name is distict from just "core:read-only"!

Implements VOS::Vobject.

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.

Reimplemented in csMetaLight, and VOS::LocalVobject.

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

Reimplemented in A3DL::Light.

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.
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.
See also:
Vobject::saveState

Reimplemented in VOS::Property.

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 VUtil::RefCounted.

virtual VUtil::vRef<ParentChildRelation> VOS::MetaObject::findChild ( int  pos  )  [virtual]

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.

Parameters:
pos the child position
Returns:
the ParentChildRelation structure representing the relation of this parent and the requested child.
Exceptions:
NoSuchObjectError if the path is illegal
AccessControlError if a remote site reported the user is not allowed that information

Implements VOS::Vobject.

virtual VUtil::vRef<ParentChildRelation> VOS::MetaObject::findChild ( const std::string &  path  )  [virtual]

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.

Parameters:
path either the child name or the position as a string
Returns:
the ParentChildRelation structure representing the relation of this parent and the requested child.
Exceptions:
NoSuchObjectError if the path is illegal
AccessControlError if a remote site reported the user is not allowed that information

Implements VOS::Vobject.

virtual VUtil::vRef<Vobject> VOS::MetaObject::findObject ( const std::string &  path  )  [virtual]

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.

Parameters:
path the path to the object we want to find
Returns:
the object, if found.
Exceptions:
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.)
NoSuchObjectError if that object path does not exist on the site
BadURLError if there is a syntax error in the supplied URL
AccessControlError if a remote site reported that the user is not allowed that information

Implements VOS::Vobject.

Referenced by LocalHello::handleHello().

virtual VUtil::vRef<ParentChildRelation> VOS::MetaObject::findParent ( Vobject *  parent  )  [virtual]

Find a parent.

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

Parameters:
parent the parent object
Returns:
the parent-child relation.
Exceptions:
NoSuchObjectError if the object is NOT a parent
AccessControlError if a remote site reported the user is not allowed that information

Implements VOS::Vobject.

virtual ACLIterator VOS::MetaObject::getAllACLs (  )  [virtual]

Returns:
all access control lists (ACL) that have been set.

Implements VOS::Vobject.

StringIterator VOS::MetaObject::getAvailablePolicies ( const std::string &  domain  )  [virtual]

Returns:
all policies in a particular policy domain that are available for use.

Implements VOS::Vobject.

virtual ChildListIterator VOS::MetaObject::getChildren ( int  start = 0,
int  end = -1 
) [virtual]

Get the children of this Vobject.

Permits fetching a "slice" of a child list by specifying starting and ending positions.

Parameters:
start the position of the first child to return (inclusive)
end the position of th elast child to return (inclusive)
Returns:
an Iterator over a list of parent-child relations

Implements VOS::Vobject.

virtual std::string VOS::MetaObject::getDefaultPolicy ( const std::string &  domain = ""  )  [virtual]

Get the policy that is applied by default if the requester's identity or groups were not found in any ACL.

This is also the policy applied to anonymous users (users with no identity.)

Parameters:
domain the policy domain you are interested in. If blank, returns a comma-separated list of the policy in each domain.

Implements VOS::Vobject.

Referenced by Creature::addPredator(), and Animal::addPrey().

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

virtual StringIterator VOS::MetaObject::getPolicy ( const std::string &  domain,
Identity *  id 
) [virtual]

Do an access control lookup; for some identity requesting access, this will return the appropriate policy in some domain based on the current access control lists.

Access control lookup works like this:

  1. Check each ACL to see if it lists this Identity. If so, we use that ACL's policy.
  2. Otherwise, check each ACL for groups that this Identity belongs to. If the Identity is a member of several Groups that are in different ACLs, then return the policy for each relevant ACL. The caller should check *every* policy to determine pass or fail -- this is up to the caller, but commonly in VOS code if any policy grants permission then permission is given. This means that groups can be used to add permissions, but not take them away! Design you access control scheme accordingly (and make the default permissions as restrictive as possible).
  3. Otherwise, because neither the Identity nor any Group it is a member of appear in any ACL, the default access control is returned.

Parameters:
domain the policy domain of interest
id the identity requesting access

Implements VOS::Vobject.

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

Note that this is for the logical Vobject and not the specific MetaObject instance, i.e.

it's forwarded to the VobjectBase just like everything else.

Reimplemented from VUtil::RefCounted.

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

Returns:
the site this object resides on.

Implements VOS::Vobject.

Referenced by Creature::addPredator(), and Animal::addPrey().

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

Returns:
the site name of this object.

Implements VOS::Vobject.

virtual TypeSetIterator VOS::MetaObject::getTypes (  )  [virtual]

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

Implements VOS::Vobject.

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

Returns:
the URL path as a URL object

Implements VOS::Vobject.

virtual VUtil::vRef<VobjectBase> VOS::MetaObject::getVobjectBase (  )  [virtual]

Returns:
the VobjectBase object that actually implements this Vobject

Implements VOS::Vobject.

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

Returns:
the specific VOS type name that represents the VOS interface this object is supplying. This should always be overridden by the subclass.

Reimplemented in VOS::VersionedVobject, A3DL::Actor, A3DL::Billboard, A3DL::Clone, A3DL::Cone, A3DL::Cube, A3DL::Cylinder, A3DL::Light, A3DL::Material, A3DL::Model, A3DL::Object3D, A3DL::PolygonMesh, A3DL::Portal, A3DL::Sector, A3DL::Snow, A3DL::Sphere, A3DL::Texture, A3DL::Viewpoint, VOS::IrcBridge, VOS::IrcClient, VOS::Avatar, VOS::CODFactory, VOS::CompoundFactory, VOS::Hypercard, VOS::LogLevelCtrl, VOS::Metadata, VOS::LocalSearch, VOS::RemoteSearch, VOS::Talkative, VOS::Services, VOS::BasicLocalProperty, VOS::Identity, VOS::Group, VOS::LocalPasswordAuth, VOS::RemotePasswordAuth, VOS::Property, VOS::RemoteProperty, VOS::VOSPluginSharedObject, Hello, Creature, and Animal.

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

Implements VOS::Vobject.

Referenced by Creature::addPredator(), and Animal::addPrey().

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

Returns:
true if this object is local, false if not

Implements VOS::Vobject.

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

Returns:
true if this object is remote, false if not

Implements VOS::Vobject.

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

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

Implements VOS::Vobject.

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

Note that this is for the logical Vobject and not the specific MetaObject instance, i.e.

it's forwarded to the VobjectBase just like everything else.

Reimplemented from VUtil::RefCounted.

virtual void VOS::MetaObject::removeChild ( ParentChildRelation *  pcr,
bool  strict = true 
) [virtual]

Remove the child at some position.

See setChild() for more information on positions.

Parameters:
pcr ParentChildRelation object describing the child entry to remove.
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.
Exceptions:
AccessControl if this is a remote object and the remote site has denied the requsted action

Implements VOS::Vobject.

virtual void VOS::MetaObject::removeChildListener ( ChildChangeListener *  cl  )  [virtual]

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

Parameters:
cl the listener object

Implements VOS::Vobject.

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

Remove a flag string.

Parameters:
flag the flag string

Implements VOS::Vobject.

virtual void VOS::MetaObject::removeFromACL ( const std::string &  ACLname,
Group *  grp 
) [virtual]

Remove a Group from an access control list (ACL).

The ACL will be deleted when the last member is removed.

Parameters:
ACLname the name of the ACL. This is a comma-separated list of the access control policies to apply for each domain. For example "core:read-only,property:accept-all". Order does not matter (it will be sorted) but this access control list name is distict from just "core:read-only"!
grp the Group to add

Implements VOS::Vobject.

virtual void VOS::MetaObject::removeFromACL ( const std::string &  ACLname,
Identity *  id 
) [virtual]

Remove an Identity from an access control list (ACL).

The ACL will be deleted when the last member is removed.

Parameters:
ACLname the name of the ACL. This is a comma-separated list of the access control policies to apply for each domain. For example "core:read-only,property:accept-all". Order does not matter (it will be sorted) but this access control list name is distict from just "core:read-only"!
id the Identity to add

Implements VOS::Vobject.

virtual void VOS::MetaObject::removeParentListener ( ParentChangeListener *  pl  )  [virtual]

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

Parameters:
pl the listener object

Implements VOS::Vobject.

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

Remove a type from the type set.

Parameters:
s the type std::string

Implements VOS::Vobject.

virtual void VOS::MetaObject::removeTypeListener ( TypeChangeListener *  tl  )  [virtual]

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

Parameters:
tl the listener object

Implements VOS::Vobject.

virtual void VOS::MetaObject::saveState ( MessageBlock &  output,
std::set< std::string > &  types,
bool  portable 
) [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.

Implements VOS::Vobject.

virtual void VOS::MetaObject::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.

Implements VOS::Vobject.

virtual void VOS::MetaObject::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.

Implements VOS::Vobject.

virtual void VOS::MetaObject::sendUpdateMessage ( Message *  m  )  [virtual]

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.

Parameters:
m A pointer to the message which is being sent.

Implements VOS::Vobject.

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

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.
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 is a remote object and the remote site has denied the requsted action

Implements VOS::Vobject.

virtual void VOS::MetaObject::setDefaultPolicy ( const std::string &  policy  )  [virtual]

Set the default policy.

Parameters:
policy the policy. This only affects the domains listed. For example, if your current default policy is "core:read-only,property:accept-all" and you call setDefaultPolicy("property:read-only") the resulting default policy will be "core:read-only,property:read-only".

Implements VOS::Vobject.

Friends And Related Function Documentation

friend class VobjectBase [friend]

Definition at line 170 of file metaobject.hh.

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