Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/branches/libs/src/libraries/core/class/Identifier.h @ 9671

Last change on this file since 9671 was 9667, checked in by landauf, 11 years ago

merged core6 back to trunk

  • Property svn:eol-style set to native
File size: 20.7 KB
Line 
1/*
2 *   ORXONOX - the hottest 3D action shooter ever to exist
3 *                    > www.orxonox.net <
4 *
5 *
6 *   License notice:
7 *
8 *   This program is free software; you can redistribute it and/or
9 *   modify it under the terms of the GNU General Public License
10 *   as published by the Free Software Foundation; either version 2
11 *   of the License, or (at your option) any later version.
12 *
13 *   This program is distributed in the hope that it will be useful,
14 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
15 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 *   GNU General Public License for more details.
17 *
18 *   You should have received a copy of the GNU General Public License
19 *   along with this program; if not, write to the Free Software
20 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
21 *
22 *   Author:
23 *      Fabian 'x3n' Landau
24 *   Co-authors:
25 *      ...
26 *
27 */
28
29/**
30    @defgroup Identifier Identifier
31    @ingroup Class
32*/
33
34/**
35    @file
36    @ingroup Class Identifier
37    @brief Declaration of Identifier, definition of ClassIdentifier<T>; used to identify the class of an object.
38
39    @anchor IdentifierExample
40
41    An Identifier "identifies" the class of an object. It contains different information about
42    the class: Its name and ID, a list of all instances of this class, a factory to create new
43    instances of this class, and more.
44
45    It also contains information about the inheritance of this class: It stores a list of the
46    Identifiers of all parent-classes as well as a list of all child-classes. These relationships
47    can be tested using functions like @c isA(), @c isChildOf(), @c isParentOf(), and more.
48
49    Every Identifier is in fact a ClassIdentifier<T> (where T is the class that is identified
50    by the Identifier), Identifier is just the common base-class.
51
52    Example:
53    @code
54    MyClass* object = new MyClass();                                            // create an instance of MyClass
55
56    object->getIdentifier()->getName();                                         // returns "MyClass"
57
58    Identifiable* other = object->getIdentifier()->fabricate(0);                // fabricates a new instance of MyClass
59
60
61    // test the class hierarchy
62    object->getIdentifier()->isA(Class(MyClass));                               // returns true
63    object->isA(Class(MyClass));                                                // returns true (short version)
64
65    object->isA(Class(BaseClass));                                              // returns true if MyClass is a child of BaseClass
66
67    Class(ChildClass)->isChildOf(object->getIdentifier());                      // returns true if ChildClass is a child of MyClass
68    @endcode
69*/
70
71#ifndef _Identifier_H__
72#define _Identifier_H__
73
74#include "core/CorePrereqs.h"
75
76#include <cassert>
77#include <map>
78#include <set>
79#include <string>
80#include <typeinfo>
81#include <loki/TypeTraits.h>
82
83#include "util/Output.h"
84#include "core/object/ObjectList.h"
85#include "core/object/Listable.h"
86#include "core/object/Context.h"
87#include "core/object/Destroyable.h"
88#include "core/object/WeakPtr.h"
89#include "IdentifierManager.h"
90#include "Super.h"
91
92namespace orxonox
93{
94    // ###############################
95    // ###       Identifier        ###
96    // ###############################
97    /**
98        @brief The Identifier is used to identify the class of an object and to store information about the class.
99
100        Each Identifier stores information about one class. The Identifier can then be used to identify
101        this class. On the other hand it's also possible to get the corresponding Identifier of a class,
102        for example by using the macro Class().
103
104        @see See @ref IdentifierExample "Identifier.h" for more information and some examples.
105
106        @note You can't directly create an Identifier, it's just the base-class of ClassIdentifier<T>.
107    */
108    class _CoreExport Identifier : public Destroyable
109    {
110        public:
111            Identifier();
112            Identifier(const Identifier& identifier); // don't copy
113            virtual ~Identifier();
114
115            /// Returns the name of the class the Identifier belongs to.
116            inline const std::string& getName() const { return this->name_; }
117            void setName(const std::string& name);
118
119            /// Returns the name of the class as it is returned by typeid(T).name()
120            virtual const std::string& getTypeidName() = 0;
121
122            /// Returns the network ID to identify a class through the network.
123            inline uint32_t getNetworkID() const { return this->networkID_; }
124            void setNetworkID(uint32_t id);
125
126            /// Returns the unique ID of the class.
127            ORX_FORCEINLINE unsigned int getClassID() const { return this->classID_; }
128
129            /// Sets the Factory.
130            void setFactory(Factory* factory);
131            /// Returns true if the Identifier has a Factory.
132            inline bool hasFactory() const { return (this->factory_ != 0); }
133
134            Identifiable* fabricate(Context* context);
135
136            /// Returns true if the class can be loaded through XML.
137            inline bool isLoadable() const { return this->bLoadable_; }
138            /// Set the class to be loadable through XML or not.
139            inline void setLoadable(bool bLoadable) { this->bLoadable_ = bLoadable; }
140
141            /// Returns true if the Identifier was completely initialized.
142            inline bool isInitialized() const { return this->bInitialized_; }
143
144
145            /////////////////////////////
146            ////// Class Hierarchy //////
147            /////////////////////////////
148            Identifier& inheritsFrom(Identifier* directParent);
149
150            void initializeParents(const std::set<const Identifier*>& identifiers);
151            void initializeDirectParentsOfAbstractClass();
152            void finishInitialization();
153
154            bool isA(const Identifier* identifier) const;
155            bool isExactlyA(const Identifier* identifier) const;
156            bool isChildOf(const Identifier* identifier) const;
157            bool isDirectChildOf(const Identifier* identifier) const;
158            bool isParentOf(const Identifier* identifier) const;
159            bool isDirectParentOf(const Identifier* identifier) const;
160
161            /// Returns the parents of the class the Identifier belongs to.
162            inline const std::set<const Identifier*>& getParents() const { return this->parents_; }
163            /// Returns the begin-iterator of the parents-list.
164            inline std::set<const Identifier*>::const_iterator getParentsBegin() const { return this->parents_.begin(); }
165            /// Returns the end-iterator of the parents-list.
166            inline std::set<const Identifier*>::const_iterator getParentsEnd() const { return this->parents_.end(); }
167
168            /// Returns the children of the class the Identifier belongs to.
169            inline const std::set<const Identifier*>& getChildren() const { return this->children_; }
170            /// Returns the begin-iterator of the children-list.
171            inline std::set<const Identifier*>::const_iterator getChildrenBegin() const { return this->children_.begin(); }
172            /// Returns the end-iterator of the children-list.
173            inline std::set<const Identifier*>::const_iterator getChildrenEnd() const { return this->children_.end(); }
174
175            /// Returns the direct parents of the class the Identifier belongs to.
176            inline const std::set<const Identifier*>& getDirectParents() const { return this->directParents_; }
177            /// Returns the begin-iterator of the direct-parents-list.
178            inline std::set<const Identifier*>::const_iterator getDirectParentsBegin() const { return this->directParents_.begin(); }
179            /// Returns the end-iterator of the direct-parents-list.
180            inline std::set<const Identifier*>::const_iterator getDirectParentsEnd() const { return this->directParents_.end(); }
181
182            /// Returns the direct children the class the Identifier belongs to.
183            inline const std::set<const Identifier*>& getDirectChildren() const { return this->directChildren_; }
184            /// Returns the begin-iterator of the direct-children-list.
185            inline std::set<const Identifier*>::const_iterator getDirectChildrenBegin() const { return this->directChildren_.begin(); }
186            /// Returns the end-iterator of the direct-children-list.
187            inline std::set<const Identifier*>::const_iterator getDirectChildrenEnd() const { return this->directChildren_.end(); }
188
189
190            /////////////////////////
191            ///// Config Values /////
192            /////////////////////////
193            virtual void updateConfigValues(bool updateChildren = true) const = 0;
194
195            /// Returns true if this class has at least one config value.
196            inline bool hasConfigValues() const { return this->bHasConfigValues_; }
197
198            void addConfigValueContainer(const std::string& varname, ConfigValueContainer* container);
199            ConfigValueContainer* getConfigValueContainer(const std::string& varname);
200
201
202            ///////////////////
203            ///// XMLPort /////
204            ///////////////////
205            /// Returns the map that stores all XMLPort params.
206            inline const std::map<std::string, XMLPortParamContainer*>& getXMLPortParamMap() const { return this->xmlportParamContainers_; }
207            /// Returns a const_iterator to the beginning of the map that stores all XMLPort params.
208            inline std::map<std::string, XMLPortParamContainer*>::const_iterator getXMLPortParamMapBegin() const { return this->xmlportParamContainers_.begin(); }
209            /// Returns a const_iterator to the end of the map that stores all XMLPort params.
210            inline std::map<std::string, XMLPortParamContainer*>::const_iterator getXMLPortParamMapEnd() const { return this->xmlportParamContainers_.end(); }
211
212            /// Returns the map that stores all XMLPort objects.
213            inline const std::map<std::string, XMLPortObjectContainer*>& getXMLPortObjectMap() const { return this->xmlportObjectContainers_; }
214            /// Returns a const_iterator to the beginning of the map that stores all XMLPort objects.
215            inline std::map<std::string, XMLPortObjectContainer*>::const_iterator getXMLPortObjectMapBegin() const { return this->xmlportObjectContainers_.begin(); }
216            /// Returns a const_iterator to the end of the map that stores all XMLPort objects.
217            inline std::map<std::string, XMLPortObjectContainer*>::const_iterator getXMLPortObjectMapEnd() const { return this->xmlportObjectContainers_.end(); }
218
219            void addXMLPortParamContainer(const std::string& paramname, XMLPortParamContainer* container);
220            XMLPortParamContainer* getXMLPortParamContainer(const std::string& paramname);
221
222            void addXMLPortObjectContainer(const std::string& sectionname, XMLPortObjectContainer* container);
223            XMLPortObjectContainer* getXMLPortObjectContainer(const std::string& sectionname);
224
225
226        protected:
227            virtual void createSuperFunctionCaller() const = 0;
228
229        private:
230            std::set<const Identifier*> parents_;                          //!< The parents of the class the Identifier belongs to
231            std::set<const Identifier*> children_;                         //!< The children of the class the Identifier belongs to
232
233            std::set<const Identifier*> directParents_;                    //!< The direct parents of the class the Identifier belongs to
234            std::set<const Identifier*> directChildren_;                   //!< The direct children of the class the Identifier belongs to
235
236            bool bInitialized_;                                            //!< Is true if the Identifier was completely initialized
237            bool bLoadable_;                                               //!< False = it's not permitted to load the object through XML
238            std::string name_;                                             //!< The name of the class the Identifier belongs to
239            Factory* factory_;                                             //!< The Factory, able to create new objects of the given class (if available)
240            uint32_t networkID_;                                           //!< The network ID to identify a class through the network
241            const unsigned int classID_;                                   //!< Uniquely identifies a class (might not be the same as the networkID_)
242
243            bool bHasConfigValues_;                                        //!< True if this class has at least one assigned config value
244            std::map<std::string, ConfigValueContainer*> configValues_;    //!< A map to link the string of configurable variables with their ConfigValueContainer
245
246            std::map<std::string, XMLPortParamContainer*> xmlportParamContainers_;     //!< All loadable parameters
247            std::map<std::string, XMLPortObjectContainer*> xmlportObjectContainers_;   //!< All attachable objects
248    };
249
250    _CoreExport std::ostream& operator<<(std::ostream& out, const std::set<const Identifier*>& list);
251
252
253    // ###############################
254    // ###     ClassIdentifier     ###
255    // ###############################
256    /**
257        @brief The ClassIdentifier is derived from Identifier and holds all class-specific functions and variables the Identifier cannot have.
258
259        ClassIdentifier is a Singleton, which means that only one ClassIdentifier for a given type T exists.
260        This makes it possible to store information about a class, sharing them with all
261        objects of that class without defining static variables in every class.
262
263        To be really sure that not more than exactly one object exists (even with libraries),
264        ClassIdentifiers are stored in a static map in Identifier.
265    */
266    template <class T>
267    class ClassIdentifier : public Identifier
268    {
269        #ifndef DOXYGEN_SHOULD_SKIP_THIS
270          #define SUPER_INTRUSIVE_DECLARATION_INCLUDE
271          #include "Super.h"
272        #endif
273
274        public:
275            static ClassIdentifier<T>* getIdentifier();
276            static ClassIdentifier<T>* getIdentifier(const std::string& name);
277
278            bool initializeObject(T* object);
279
280            void setConfigValues(T* object, Configurable*) const;
281            void setConfigValues(T* object, Identifiable*) const;
282
283            void addObjectToList(T* object, Listable*);
284            void addObjectToList(T* object, Identifiable*);
285
286            virtual void updateConfigValues(bool updateChildren = true) const;
287
288            virtual const std::string& getTypeidName()
289                { return this->typeidName_; }
290
291        private:
292            static void initializeIdentifier();
293
294            ClassIdentifier(const ClassIdentifier<T>& identifier) {}    // don't copy
295            ClassIdentifier()
296            {
297                this->typeidName_ = typeid(T).name();
298                SuperFunctionInitialization<0, T>::initialize(this);
299            }
300            ~ClassIdentifier()
301            {
302                SuperFunctionDestruction<0, T>::destroy(this);
303            }
304
305            void updateConfigValues(bool updateChildren, Listable*) const;
306            void updateConfigValues(bool updateChildren, Identifiable*) const;
307
308            std::string typeidName_;
309            static WeakPtr<ClassIdentifier<T> > classIdentifier_s;
310    };
311
312    template <class T>
313    WeakPtr<ClassIdentifier<T> > ClassIdentifier<T>::classIdentifier_s;
314
315    /**
316        @brief Returns the only instance of this class.
317        @return The unique Identifier
318    */
319    template <class T>
320    inline ClassIdentifier<T>* ClassIdentifier<T>::getIdentifier()
321    {
322        // check if the Identifier already exists
323        if (!ClassIdentifier<T>::classIdentifier_s)
324            ClassIdentifier<T>::initializeIdentifier();
325
326        return ClassIdentifier<T>::classIdentifier_s;
327    }
328
329    /**
330        @brief Does the same as getIdentifier() but sets the name if this wasn't done yet.
331        @param name The name of this Identifier
332        @return The Identifier
333    */
334    template <class T>
335    inline ClassIdentifier<T>* ClassIdentifier<T>::getIdentifier(const std::string& name)
336    {
337        ClassIdentifier<T>* identifier = ClassIdentifier<T>::getIdentifier();
338        identifier->setName(name);
339        return identifier;
340    }
341
342    /**
343        @brief Assigns the static field for the identifier singleton.
344    */
345    template <class T>
346    /*static */ void ClassIdentifier<T>::initializeIdentifier()
347    {
348        // create a new identifier anyway. Will be deleted if not used.
349        ClassIdentifier<T>* proposal = new ClassIdentifier<T>();
350
351        // Get the entry from the map
352        ClassIdentifier<T>::classIdentifier_s = (ClassIdentifier<T>*)IdentifierManager::getInstance().getGloballyUniqueIdentifier(proposal);
353
354        if (ClassIdentifier<T>::classIdentifier_s == proposal)
355            orxout(verbose, context::identifier) << "Requested Identifier for " << proposal->getTypeidName() << " was not yet existing and got created." << endl;
356        else
357        {
358            orxout(verbose, context::identifier) << "Requested Identifier for " << proposal->getTypeidName() << " was already existing and got assigned." << endl;
359            delete proposal; // delete proposal (it is not used anymore)
360        }
361    }
362
363    /**
364        @brief Adds an object of the given type to the ObjectList.
365        @param object The object to add
366    */
367    template <class T>
368    bool ClassIdentifier<T>::initializeObject(T* object)
369    {
370        orxout(verbose, context::object_list) << "Register Object: " << this->getName() << endl;
371
372        object->identifier_ = this;
373        if (IdentifierManager::getInstance().isCreatingHierarchy())
374        {
375            IdentifierManager::getInstance().createdObject(object);
376
377            this->setConfigValues(object, object);
378            return true;
379        }
380        else
381        {
382            this->addObjectToList(object, object);
383
384            // Add pointer of type T to the map in the Identifiable instance that enables "dynamic_casts"
385            object->objectPointers_.push_back(std::make_pair(this->getClassID(), static_cast<void*>(object)));
386            return false;
387        }
388    }
389
390    /**
391     * @brief Only configures the object if is a @ref Configurable
392     */
393    template <class T>
394    void ClassIdentifier<T>::setConfigValues(T* object, Configurable*) const
395    {
396        object->setConfigValues();
397    }
398
399    template <class T>
400    void ClassIdentifier<T>::setConfigValues(T*, Identifiable*) const
401    {
402        // no action
403    }
404
405    /**
406     * @brief Only adds the object to the object list if is a @ref Listable
407     */
408    template <class T>
409    void ClassIdentifier<T>::addObjectToList(T* object, Listable* listable)
410    {
411        if (listable->getContext())
412            listable->getContext()->addObject(object);
413    }
414
415    template <class T>
416    void ClassIdentifier<T>::addObjectToList(T*, Identifiable*)
417    {
418        // no action
419    }
420
421    /**
422        @brief Updates the config-values of all existing objects of this class by calling their setConfigValues() function.
423    */
424    template <class T>
425    void ClassIdentifier<T>::updateConfigValues(bool updateChildren) const
426    {
427        this->updateConfigValues(updateChildren, static_cast<T*>(NULL));
428    }
429
430    template <class T>
431    void ClassIdentifier<T>::updateConfigValues(bool updateChildren, Listable*) const
432    {
433        if (!this->hasConfigValues())
434            return;
435
436        for (ObjectListIterator<T> it = ObjectList<T>::begin(); it; ++it)
437            this->setConfigValues(*it, *it);
438
439        if (updateChildren)
440            for (std::set<const Identifier*>::const_iterator it = this->getChildrenBegin(); it != this->getChildrenEnd(); ++it)
441                (*it)->updateConfigValues(false);
442    }
443
444    template <class T>
445    void ClassIdentifier<T>::updateConfigValues(bool updateChildren, Identifiable*) const
446    {
447        // no action
448    }
449
450
451    // ###############################
452    // ###      orxonox_cast       ###
453    // ###############################
454    /**
455    @brief
456        Casts on object of type Identifiable to any derived type that is
457        registered in the class hierarchy.
458    @return
459        Returns NULL if the cast is not possible
460    @note
461        In case of NULL return (and using MSVC), a dynamic_cast might still be possible if
462        a class forgot to register its objects.
463        Also note that the function is implemented differently for GCC/MSVC.
464    */
465    template <class T, class U>
466    ORX_FORCEINLINE T orxonox_cast(U* source)
467    {
468#ifdef ORXONOX_COMPILER_MSVC
469        typedef Loki::TypeTraits<typename Loki::TypeTraits<T>::PointeeType>::NonConstType ClassType;
470        if (source != NULL)
471            return source->template getDerivedPointer<ClassType>(ClassIdentifier<ClassType>::getIdentifier()->getClassID());
472        else
473            return NULL;
474#else
475        return dynamic_cast<T>(source);
476#endif
477    }
478}
479
480#endif /* _Identifier_H__ */
Note: See TracBrowser for help on using the repository browser.