Statistics
| Branch: | Revision:

root / include / cvisitor.h @ master

History | View | Annotate | Download (3.22 KB)

1
//==========================================================================
2
//  CVISITOR.H - part of
3
//                     OMNeT++/OMNEST
4
//            Discrete System Simulation in C++
5
//
6
//  Declaration of the following classes:
7
//    cVisitor:  enables traversing the object tree
8
//
9
//==========================================================================
10

    
11
/*--------------------------------------------------------------*
12
  Copyright (C) 1992-2008 Andras Varga
13
  Copyright (C) 2006-2008 OpenSim Ltd.
14

15
  This file is distributed WITHOUT ANY WARRANTY. See the file
16
  `license' for details on this and other legal matters.
17
*--------------------------------------------------------------*/
18

    
19
#ifndef __CVISITOR_H
20
#define __CVISITOR_H
21

    
22
#include "simkerneldefs.h"
23

    
24
NAMESPACE_BEGIN
25

    
26
class cObject;
27

    
28

    
29
/**
30
 * Enables traversing the tree of (cObject-rooted) simulation objects.
31
 * Should be subclassed and the visit() method redefined according
32
 * to your needs.
33
 *
34
 * An example: the cRecursiveObjectFinderVisitor class (internal) has been
35
 * created to find an object of the given name. The constructor accepts
36
 * the name of the object to search for, and visit() has been redefined
37
 * to perform recursive traversal, and to throw EndTraversalException
38
 * if it finds the given object. The class can be used like this:
39
 *
40
 * \code
41
 * cRecursiveObjectFinderVisitor v(objectName);
42
 * v.process(root);
43
 * cObject *result = v.getResult();
44
 * \endcode
45
 *
46
 * The above code will find the root object as well, if its name matches.
47
 * The second version (below) starts the traversal at the children,
48
 * so the root object is ignored.
49
 *
50
 * \code
51
 * cRecursiveObjectFinderVisitor v(objectName);
52
 * v.processChildrenOf(root);
53
 * cObject *result = v.getResult();
54
 * \endcode
55
 *
56
 * @ingroup SimCore
57
 * @ingroup SimSupport
58
 */
59
class SIM_API cVisitor
60
{
61
  protected:
62
    /**
63
     * Can be thrown to get out in the middle of the traversal process.
64
     */
65
     class EndTraversalException { public: EndTraversalException() {} };
66

    
67
  public:
68
    /**
69
     * Virtual destructor.
70
     */
71
    virtual ~cVisitor() {}
72

    
73
    /**
74
     * Starts the visiting process. This version simply calls visit(obj),
75
     * and catches EndTraversalException if one occurs. Return value is true if
76
     * traversal went through and false if EndTraversalException was caught.
77
     */
78
    virtual bool process(cObject *obj);
79

    
80
    /**
81
     * Similar to process(), except that it skips the object itself, i.e. it begins
82
     * with processing the children. Calls obj->forEachChild(this),
83
     * and catches EndTraversalException if one occurs. Return value is true if
84
     * traversal went through and false if EndTraversalException was caught.
85
     */
86
    virtual bool processChildrenOf(cObject *obj);
87

    
88
    /**
89
     * Method called from the forEachChild() methods of every class derived
90
     * from cObject, for each contained object. visit() should be
91
     * redefined by user to encapsulate the operation to be performed
92
     * on the object. If you want recursively traversal, call
93
     * obj->forEachChild(this) from here.
94
     *
95
     * This method should NOT be called to to initiate the traversal -- use
96
     * process() or processChildrenOf() for that.
97
     */
98
    virtual void visit(cObject *obj) = 0;
99
};
100

    
101
NAMESPACE_END
102

    
103

    
104
#endif
105

    
106