apps/tutorials/vostut4.cc

Go to the documentation of this file.

/* Fourth VOS tutorial.  Linking Vobjects together.

   This tutorial covers:
   - Inserting, replacing and removing Vobjects as children of other
   Vobjects
   - Linking local and remote Vobjects
   - Finding specific a child by name
   - Vobject paths
   - Listing a Vobject's children
   - Listing a Vobject's parents

   This file (vostut4.cc) is released into the public domain.  No
   restrictions are placed on its use, distribution or inclusion into
   other works.
*/

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

void listChildren(Vobject* vobject);
void listParents(Vobject* vobject);

// The server from tutorial 3 ("vostut3server") should be run before
// running this tutorial.

int main(int argc, char** argv)
{
    cout << "VOS Tutorial 4\n\n";

    LocalSocketSite localsite(&NoAccessControl::static_);
    localsite.setTimeoutOnSelect(-1);

    /* We saw in the previous tutorial how one Vobject can access
       another.  We now look at how Vobjects may be linked together to
       create network-accessable data structures.  In this tutorial,
       we demonstrate how one might build a data structure describing
       a sphere with VOS.

       A Vobject may consist of a number of incoming "parent" links
       and outgoing "child" links.  The terms parent and child come
       from common computer science usage for describing hierarchical
       structures.  At the top level is the local site, which is a
       parent to all Vobjects it hosts (and therefore has each Vobject
       as a child).  When a Vobject is created, it is automatically
       made a child of its site.
    */

    // Create some objects to play with.
    vRef<Vobject> sphere = localsite.createMetaObject("sphere", 0);
    vRef<Vobject> tertius = localsite.createMetaObject("tertius", 0);
    vRef<Vobject> quartus = localsite.createMetaObject("quartus", 0);
    vRef<Vobject> quintus = localsite.createMetaObject("quintus", 0);
    vRef<Vobject> sextus = localsite.createMetaObject("sextus", 0);
    vRef<Vobject> septimus = localsite.createMetaObject("septimus", 0);

    listChildren(&localsite);
    cout << "\n";

    /* Each Vobject stores a list other Vobjects it links to. This is
       called the child list.  It is an ordered, associative list,
       where each position in the list consists of a string called the
       "contextual name" and a link to the Vobject it points to.

       Initially, the Vobject "sphere" does not have any children.
       The insertChild() method is used to add children.  The first
       parameter tells where in the list to insert the child, with the
       value "-1" used to append to the end of the child list.  The
       link is named "position", so in our example the the linked-to
       child vobject (tertius) describes the position of its parent
       (the sphere).
    */
    cout << "Appending tertius as \"position\"\n";
    sphere->insertChild(-1, "position", &tertius);

    /* For the moment, don't worry about how the value of position
        will be stored in the tertius Vobject. This is discussed in a
        later tutorial.  For this tutorial we are concentrating on the
        abstract structure.
     */

    /* Print out the children of the sphere and the parents of
       tertius.  Since tertius has been added as a child to sphere,
       sphere is now listed as a parent of tertius.
    */
    listChildren(&sphere);
    listParents(&tertius);
    cout << "\n";


    /* Now we add a few more vobjects to the sphere.  As demonstrated
       here, the child list can have more than one link to the same
       Vobject and you can have multiple entries with the same
       contextual name.
    */
    cout << "Appending quartus as \"orientation\"\n";
    sphere->insertChild(-1, "orientation", &quartus);

    cout << "Appending quintus as \"radius\"\n";
    sphere->insertChild(-1, "radius", &quintus);

    cout << "Appending quartus as \"position\"\n";
    sphere->insertChild(-1, "position", &quartus);

    listChildren(&sphere);
    listParents(&quartus);
    cout << "\n";


    /* Of course we can insert a new item anywhere. We'll add the
       Vobject "sextus" describing the color of our sphere so that it
       occupies position 2.  This shifts the rest of the list (from
       position 2 to the end) up one position to make room for the
       newly inserted child.  Note: position 0 inserts a child at the
       beginning of the list.
    */
    cout << "Inserting sextus as \"color\" into position 2\n";
    sphere->insertChild(2, "color", &sextus);

    listChildren(&sphere);
    cout << "\n";


    /* Oops!  We have two children named "position"!  The sphere can't
       very well be in two places at once, can it?  The setChild()
       method allows us to replace a child at one position with
       another, which is much more efficient than removing the old
       vobject and inserting the new one.  Here we replace the second
       "position" child (at list position 4 now) with a
       different object that will store our sphere's mass.
    */
    cout << "Replacing quartus in position 4 with septimus as \"mass\"\n";
    sphere->setChild(4, "mass", &septimus);

    listChildren(&sphere);
    cout << "\n";

    /* It's also sort of silly for a sphere to have an orientation,
       seeing as how it is perfectly round.  Let's remove the child
       storing the orientation.  The removeChild() method removes the
       list item at the given position and move everything above it
       down a notch to fill in the gap.
     */
    cout << "Removing quintus (\"orientation\") from position 1\n";
    sphere->removeChild(1);

    listChildren(&sphere);
    cout << "\n";


    /*  Some detail specifying a position in a child list: positive
        positions are counted from the beginning and negative
        positions are counted from the end.  The start of the list is
        always 0 and the end of the list is always -1.  This means
        that positions of -2 (second-to-last position), -3, -10 and so
        on are perfectly legal (provided the list is at least of that
        length).
     */
    cout << "Removing septimus (\"mass\") from the last position\n";
    sphere->removeChild(-1);

    listChildren(&sphere);
    cout << "\n";

    try {
        /* What makes parent-child linking of Vobjects really
           interesting is the fact that you can freely mix local and
           remote Vobjects.  Here we acquire a remote object running
           on a different site and manipulate it exactly the same way
           as if it were local.
         */
        vRef<Vobject> primus = Vobject::findObjectFromRoot("vop://localhost:4231/primus");

        cout << "Adding local vobject septimus to remote to remote vobject primus\n";
        primus->insertChild(-1, "septimus", &septimus);

        listChildren(&primus);
        listParents(&septimus);
        cout << "\n";


        cout << "Adding remote vobject primus to local vobject quartus\n";
        quartus->insertChild(-1, "primus", &primus);

        listChildren(&quartus);
        listParents(&primus);
        cout << "\n";
    } catch(runtime_error& e) {
        cerr << "An exception occured: " << e.what() << "\n";
    }

    /* Once we have created a VOS data structure, we want to be able
       to access it. One way is by iterating over the entire contents
       of the child list (which is demonstrated in the listChildren()
       function below).  The other is to use the findChild() and
       findObject() methods.

       The findChild() method returns the Vobject::ParentChildRelation
       structure describing the link with the given contextual name.
       If more than one link has the same contextual name, then the
       link with position closest to the beginning is returned. This
       simply consists of four fields, the parent, the child, and the
       position and contextual name in the parent's child list.
    */
    vRef<Vobject::ParentChildRelation> pcr = sphere->findChild("color");
    cout << "Results of findChild():\n";
    cout << " Parent: " << pcr->parent->getURL().getString() << "\n";
    cout << " Position: " << pcr->position << "\n";
    cout << " Contextual name: " << pcr->contextual_name << "\n";
    cout << " Child: " << pcr->child->getURL().getString() << "\n";

    /* The findObject() method returns just the Vobject itself, but
       can take a path going through several Vobjects.  A Vobject path
       is a slash-separated list of contextual names to follow to find
       the Vobject.  It is intended to resemble a familiar file system
       path and works essentially the same way, although the notation
       ".." is not available.  While directories in a filesystem only
       have one parent directory, Vobjects usually have two or more
       parent Vobjects!
    */
    vRef<Vobject> color = localsite.findObject("sphere/color");

    listParents(&color);

    /* One final method for accessing parent-child relationships:
       findParent() returns the parent-child relationship structure
       associated with a specific parent of this Vobject.
    */
    vRef<Vobject::ParentChildRelation> pcr2 = color->findParent(*sphere);
    cout << "Results of findParent():\n";
    cout << " Parent: " << pcr2->parent->getURL().getString() << "\n";
    cout << " Position: " << pcr2->position << "\n";
    cout << " Contextual name: " << pcr2->contextual_name << "\n";
    cout << " Child: " << pcr2->child->getURL().getString() << "\n";


    cout << "Going into runloop now.  Try connecting to " << localsite.getURL().getString() << " using \"mesh\"\n";
    cout << "to inspect the current vobject structure.\n";

    while(true) {
        localsite.flushIncomingBuffers();
    }
}

void listChildren(Vobject* vobject)
{
    // getChildren() returns the child list for this Vobject.  This is
    // a list of Vobject::ParentChildRelation structures.  It is
    // intended for read only access and you should never ever modify
    // the contents of this list directly.
    const Vobject::ChildList& childlist = vobject->getChildren();

    cout << "Children of " << vobject->getURL().getString() << ":\n";

    // You can efficiently iterate over the list with an int:
    for(int i = 0; i < childlist.size(); i++) {
        Vobject::ParentChildRelation* pcr = childlist[i];
        cout << " #" << pcr->position << " " << pcr->contextual_name << " -> "
             << pcr->child->getURL().getString() << "\n";
    }
}

void listParents(Vobject* vobject)
{
    // getParents returns an STL set storing the
    // Vobject::ParentChildRelation structures describing each link to
    // this Vobject in some Vobject's child list.  As with the child
    // list, this is for read only access and you should never modify
    // this set directly.
    const Vobject::ParentSet& parentset = vobject->getParents();

    cout << "Parents of " << vobject->getURL().getString() << ":\n";

    // Use an STL const_iterator to iterate over this set.
    for(Vobject::ParentSet::const_iterator i = parentset.begin(); i != parentset.end(); i++) {
        Vobject::ParentChildRelation* pcr = *i;
        cout << " " << pcr->parent->getURL().getString() << " linked as #"
             << pcr->position << " " << pcr->contextual_name << "\n";
    }
}

---