FactoryDictionary.h
Go to the documentation of this file.
1 /* Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.
2 
3  This file is part of the TerraLib - a Framework for building GIS enabled applications.
4 
5  TerraLib is free software: you can redistribute it and/or modify
6  it under the terms of the GNU Lesser General Public License as published by
7  the Free Software Foundation, either version 3 of the License,
8  or (at your option) any later version.
9 
10  TerraLib is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU Lesser General Public License for more details.
14 
15  You should have received a copy of the GNU Lesser General Public License
16  along with TerraLib. See COPYING. If not, write to
17  TerraLib Team at <terralib-team@terralib.org>.
18  */
19 /*!
20  \file terralib/common/FactoryDictionary.h
21 
22  \brief A dictionary for a Factory.
23  */
24 
25 #ifndef __TERRALIB_COMMON_INTERNAL_FACTORYDICTIONARY_H
26 #define __TERRALIB_COMMON_INTERNAL_FACTORYDICTIONARY_H
27 
28 // TerraLib
29 #include "Exception.h"
30 #include "../core/translator/Translator.h"
31 
32 // STL
33 #include <map>
34 
35 namespace te
36 {
37  namespace common
38  {
39  /*!
40  \class FactoryDictionary
41 
42  \brief This class represents a dictionary of factories.
43 
44  An abstract factory will keep an internal dictionary for its
45  concrete factories. A factory is identified by a key of type TFACTORYKEY
46  that must have the less-than operator. The type TFACTORYKEY must also be copy
47  constructible.
48 
49  The abstract factory to which the dictionary will belong to
50  has the type TFACTORY.
51 
52  Note that TFACTORY is the factory type and TFACTORYKEY is the type
53  used to identify the factory.
54 
55  At destruction time, it will release the memory pointed by the registered factories.
56 
57  If you are creating a plugin that registers a factory, see the Abstract
58  and Parameterized abstract factory notes about memory management.
59 
60  You should not use this class in your code. It is for internal use only.
61 
62  \ingroup common
63 
64  \sa AbstractFactory, ParameterizedAbstractFactory
65  */
66  template<class TFACTORY, class TFACTORYKEY, class TKEYCOMPARE = std::less<TFACTORYKEY> >
68  {
69  public:
70 
71  typedef typename std::map<TFACTORYKEY, TFACTORY*, TKEYCOMPARE>::const_iterator const_iterator;
72 
73  /*! \brief It creates a new factory dictionary. */
75 
76  /*!
77  \brief Destructor.
78 
79  It will release all factories registered in it.
80  If you need to release the memory before, call remove method, it will just de-register
81  the given factory.
82  */
84 
85  /*!
86  \brief It inserts a pointer to a factory and makes it associated to the factory key.
87 
88  \param factoryKey The key that will be used to access the given factory.
89  \param factory A valid pointer to a factory.
90 
91  \exception Exception It throws an exception if it can not insert the factory.
92 
93  \note You must not release the memory pointed by factory while it is being used.
94  */
95  void insert(const TFACTORYKEY& factoryKey, TFACTORY* factory);
96 
97  /*!
98  \brief It removes the factory from the dictionary.
99 
100  It doesn't release the memory, the caller must do this when appropriated.
101 
102  \exception Exception It throws an exception if it can not unregister the factory.
103 
104  \param factoryKey The key identifying the factory.
105  */
106  void remove(const TFACTORYKEY& factoryKey);
107 
108  /*!
109  \brief It looks for a given factory identified by a key.
110 
111  \param factoryKey The key identifying the searched factory.
112 
113  \return It returns a pointer to the searched factory or NULL otherwise.
114 
115  \note You must not release the memory pointed by factory while it is being used.
116  */
117  TFACTORY* find(const TFACTORYKEY& factoryKey) const;
118 
119  /*!
120  \brief It returns an iterator to the first stored factory.
121 
122  \return An iterator to the first stored factory.
123 
124  \note Don't free the pointers!
125  */
126  typename std::map<TFACTORYKEY, TFACTORY*, TKEYCOMPARE>::const_iterator begin() const;
127 
128  /*!
129  \brief It returns an iterator to the end of the container.
130 
131  \return An iterator to the end of the container.
132  */
133  typename std::map<TFACTORYKEY, TFACTORY*, TKEYCOMPARE>::const_iterator end() const;
134 
135  /*!
136  \brief It returns the number of registered factories in the dictionary.
137 
138  \return The number of registered factories in the dictionary.
139  */
140  std::size_t size() const;
141 
142  private:
143 
144  /** @name Copy Constructor and Assignment Operator
145  * Copy constructor and assignment operator not allowed.
146  */
147  //@{
148 
149  /*!
150  \brief Copy constructor not allowed.
151 
152  \param rhs The right-hand-side copy that would be used to copy from.
153  */
155 
156  /*!
157  \brief Assignment operator not allowed.
158 
159  \param rhs The right-hand-side copy that would be used to copy from.
160 
161  \return A reference to this object.
162  */
164 
165  //@}
166 
167  private:
168 
169  std::map<TFACTORYKEY, TFACTORY*, TKEYCOMPARE> m_factoryMap; //!< The internal dictionary map: key => factory.
170  };
171 
172  template<class TFACTORY, class TFACTORYKEY, class TKEYCOMPARE> inline
174  {
175  }
176 
177  template<class TFACTORY, class TFACTORYKEY, class TKEYCOMPARE> inline
179  {
180  //typename std::map<TFACTORYKEY, TFACTORY*, TKEYCOMPARE>::const_iterator it = m_factoryMap.begin();
181 
182  //while(it != m_factoryMap.end())
183  //{
184  // TFACTORY* factory = it->second;
185  // ++it; // we need to move forward before deleting the factory, because of cross-reference
186  // delete factory;
187  //}
188 
189  m_factoryMap.clear();
190  }
191 
192  template<class TFACTORY, class TFACTORYKEY, class TKEYCOMPARE> inline
194  TFACTORY* factory)
195  {
196  if(factory == 0)
197  throw Exception(TE_TR("Could not insert the given factory into the dictionary. The factory is a NULL object!"));
198 
199  typename std::map<TFACTORYKEY, TFACTORY*, TKEYCOMPARE>::const_iterator it = m_factoryMap.find(factoryKey);
200 
201  if(it != m_factoryMap.end())
202  throw Exception(TE_TR("Could not insert the given factory into the dictionary. There is a factory already registered with the given key."));
203 
204  m_factoryMap[factoryKey] = factory;
205  }
206 
207  template<class TFACTORY, class TFACTORYKEY, class TKEYCOMPARE> inline
209  {
210  typename std::map<TFACTORYKEY, TFACTORY*, TKEYCOMPARE>::iterator it = m_factoryMap.find(factoryKey);
211 
212  if(it != m_factoryMap.end())
213  m_factoryMap.erase(it);
214  else
215  throw Exception(TE_TR("Could not unregister the informed factory. Object factory not found!"));
216  }
217 
218  template<class TFACTORY, class TFACTORYKEY, class TKEYCOMPARE> inline
219  TFACTORY* FactoryDictionary<TFACTORY, TFACTORYKEY, TKEYCOMPARE>::find(const TFACTORYKEY& factoryKey) const
220  {
221  typename std::map<TFACTORYKEY, TFACTORY*, TKEYCOMPARE>::const_iterator it = m_factoryMap.find(factoryKey);
222 
223  if(it == m_factoryMap.end())
224  return 0;
225 
226  return it->second;
227  }
228 
229  template<class TFACTORY, class TFACTORYKEY, class TKEYCOMPARE> inline
231  {
232  return m_factoryMap.begin();
233  }
234 
235  template<class TFACTORY, class TFACTORYKEY, class TKEYCOMPARE> inline
237  {
238  return m_factoryMap.end();
239  }
240 
241  template<class TFACTORY, class TFACTORYKEY, class TKEYCOMPARE> inline
243  {
244  return m_factoryMap.size();
245  }
246 
247  } // end namespace common
248 } // end namespace te
249 
250 #endif // __TERRALIB_COMMON_INTERNAL_FACTORYDICTIONARY_H
251 
std::map< TFACTORYKEY, TFACTORY *, TKEYCOMPARE > m_factoryMap
The internal dictionary map: key => factory.
void insert(const TFACTORYKEY &factoryKey, TFACTORY *factory)
It inserts a pointer to a factory and makes it associated to the factory key.
FactoryDictionary()
It creates a new factory dictionary.
#define TE_TR(message)
It marks a string in order to get translated.
Definition: Translator.h:243
std::map< TFACTORYKEY, TFACTORY *, TKEYCOMPARE >::const_iterator const_iterator
TFACTORY * find(const TFACTORYKEY &factoryKey) const
It looks for a given factory identified by a key.
FactoryDictionary & operator=(const FactoryDictionary &rhs)
Assignment operator not allowed.
URI C++ Library.
std::map< TFACTORYKEY, TFACTORY *, TKEYCOMPARE >::const_iterator end() const
It returns an iterator to the end of the container.
This class is designed to declare objects to be thrown as exceptions by TerraLib. ...
Definition: Exception.h:58
std::map< TFACTORYKEY, TFACTORY *, TKEYCOMPARE >::const_iterator begin() const
It returns an iterator to the first stored factory.
This class is designed to declare objects to be thrown as exceptions by TerraLib. ...
void remove(const TFACTORYKEY &factoryKey)
It removes the factory from the dictionary.
std::size_t size() const
It returns the number of registered factories in the dictionary.
This class represents a dictionary of factories.