TerraLib.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 /*!
21  \file terralib/common/TerraLib.h
22 
23  \brief An utility class to control the startup and cleanup of the TerraLib Platform and its resources.
24 */
25 
26 #ifndef __TERRALIB_COMMON_INTERNAL_TERRALIB_H
27 #define __TERRALIB_COMMON_INTERNAL_TERRALIB_H
28 
29 // TerraLib
30 #include "Config.h"
31 #include "Singleton.h"
32 
33 // STL
34 #include <memory>
35 #include <string>
36 #include <vector>
37 
38 /*!
39  \class TerraLib
40 
41  \brief An utility class to control the startup and cleanup of the TerraLib Platform and its resources.
42 
43  This singleton will control the initialization and the cleanup of TerraLib
44  modules and their resources. If you are creating a C++ application you may need to
45  make an explicit initialization of the TerraLib Platform as showned in the code below:
46 
47  \code
48  #include <terralib/common/TerraLib.h>
49 
50  ...
51 
52  int main(char** argv, int argc)
53  {
54  ... // other initializations goes here!
55 
56  TerraLib::getInstance().initialize();
57 
58  ... // now you can start using TerraLib!
59 
60  TerraLib::getInstance().finalize(); // call this when you have finished using TerraLib
61 
62  return EXIT_SUCCESS;
63  }
64  \endcode
65 
66  Notice the calling to the finalize function at the end of the example program,
67  it is necessary in order to close/release any pending resource initialized by the modules.
68 
69  \ingroup common
70 */
71 class TECOMMONEXPORT TerraLib : public te::common::Singleton<TerraLib>
72 {
73  friend class te::common::Singleton<TerraLib>;
74 
75  public:
76 
77  /*!
78  \typedef void (*StartupFptr)(void);
79 
80  \brief This is the type for call back functions that makes the startup of a module.
81  */
82  typedef void (*StartupFptr)(void);
83 
84  /*!
85  \typedef void (*CleanupFptr)(void);
86 
87  \brief This is the type for call back functions that makes the cleanup of a module.
88  */
89  typedef void (*CleanupFptr)(void);
90 
91  /*!
92  \struct Module
93 
94  \brief This internal structure is used to model the basic information about a TerraLib module.
95 
96  \sa TerraLib
97  */
98  struct TECOMMONEXPORT Module
99  {
100  Module(std::string name, StartupFptr startFptr, CleanupFptr cleanupFptr)
101  {
102  m_name = name;
103  m_startFptr = startFptr;
104  m_cleanupFptr = cleanupFptr;
105  }
106 
107  std::string m_name; //!< The module name: an internal value used to identify the module in the system. Must be a unique value.
108  StartupFptr m_startFptr; //!< The module initialization routine.
109  CleanupFptr m_cleanupFptr; //!< The module finalization routine.
110  };
111 
112  /*!
113  \brief It initializes the TerraLib Platform.
114 
115  This method will perform the startup of all registered modules.
116  If there isn't modules to be initialized this method has no effect.
117 
118  \exception Exception It may throws an exception.
119 
120  \note The registered module startup functions will be invoked in a direct order of registering (the first module to be registered will be the first to be initialized).
121 
122  \warning Not thread safe!
123 
124  \warning If this method throws an exception we recommend you to
125  quit the program, don't try to resume it because you can have intermittent errors!
126  */
127  void initialize();
128 
129  /*!
130  \brief It initializes the i-th registered module in the TerraLib Platform.
131 
132  \exception Exception It may throws an exception.
133 
134  \note If there is a registered module startup function it will be invoked.
135 
136  \warning Not thread safe!
137 
138  \warning Don't call this method in your code, it is used internally by TerraLib.
139  */
140  void initialize(const std::size_t i);
141 
142  /*!
143  \brief It initializes the registered module in the TerraLib Platform.
144 
145  \exception Exception It may throws an exception.
146 
147  \note If there is a registered module startup function it will be invoked.
148 
149  \warning Not thread safe!
150 
151  \warning Don't call this method in your code, it is used internally by TerraLib.
152  */
153  void initialize(const std::string& moduleName);
154 
155  /*!
156  \brief It finalizes the TerraLib Platform.
157 
158  \exception Exception It may throws an exception.
159 
160  \note The registered module shutdown functions will be invoked in an opposite order of registering (the last module to be registered will be the first module to be finalized).
161 
162  \warning Not thread safe!
163 
164  \warning If this method throws an exception we recommend you to
165  quit the program, don't try to resume it because you can have intermittent errors!
166  */
167  void finalize();
168 
169  /*!
170  \brief It finalizes the i-th registered module in the TerraLib Platform.
171 
172  \exception Exception It may throws an exception.
173 
174  \note If there is a registered module cleaunp function it will be invoked.
175 
176  \warning Not thread safe!
177 
178  \warning Don't call this method in your code, it is used internally by TerraLib.
179  */
180  void finalize(const std::size_t i);
181 
182  /*!
183  \brief It finalizes the registered module in the TerraLib Platform.
184 
185  \exception Exception It may throws an exception.
186 
187  \note If there is a registered module cleaunp function it will be invoked.
188 
189  \warning Not thread safe!
190 
191  \warning Don't call this method in your code, it is used internally by TerraLib.
192  */
193  void finalize(const std::string& moduleName);
194 
195  /*!
196  \brief It registers the module in the TerraLib Platform.
197 
198  Each registered module will be initialized when TerraLib Platform is explicitly started
199  and then finalized when the application finalizes.
200 
201  \param m A TerraLib module.
202  */
203  void add(std::weak_ptr<Module> m);
204 
205  /*!
206  \brief It removes the module entry identified by the given name.
207 
208  \param moduleName The TerraLib module to be removed from the platform control.
209  */
210  void remove(const std::string& moduleName);
211 
212  /*!
213  \brief It removes the i-th module entry.
214 
215  \param i The i-th TerraLib module to be removed from the platform control.
216  */
217  void remove(const std::size_t i);
218 
219  /*!
220  \brief It returns the number of registered modules.
221 
222  \return The number of registered modules.
223  */
224  std::size_t getNumRegModules() const;
225 
226  /*!
227  \brief It returns the module index inside the internal data structure.
228 
229  \param moduleName The name of a valid module registered in this singleton.
230 
231  \return The module index inside the internal data structure.
232  */
233  std::size_t getModuleIdx(const std::string& moduleName) const;
234 
235  /*!
236  \brief It return the i-th module name.
237 
238  \param i The module you are looking for its name.
239 
240  \return The module name for the i-th module.
241  */
242  const std::string& getModuleName(std::size_t i) const;
243 
244  protected:
245 
246  /*! \brief The singleton constructor is not callable outside the class. */
247  TerraLib();
248 
249  /* \brief Destructor. */
250  ~TerraLib();
251 
252  private:
253 
254  /*!
255  \brief This static function is invoked automatically when the application finishes its execution.
256 
257  \exception Exception It may throws an exception.
258 
259  \note This function will be automatically called at the end of your program.
260 
261  \note The registered module shutdown functions will be invoked in an opposite order of registering (the last module to be registered will be the first module to be finalized).
262 
263  \warning Not thread safe!
264 
265  \warning If this method throws an exception we recommend you to
266  quit the program, don't try to resume it because you can have intermittent errors!
267  */
268  //static void sfinalize();
269 
270 
271  /*!
272  \brief This is a internal function that loads all translations on the default TerraLib share folder. it will be invoked after loading all plugins.
273  */
274  void initializeTranslations();
275 
276  private:
277 
278  std::vector<std::weak_ptr<Module> > m_modules; //!< The list of registered modules.
279  std::vector<bool> m_initialized; //!< The list of modules to be initialized when initialize is called.
280 };
281 
282 #endif // __TERRALIB_COMMON_INTERNAL_TERRALIB_H
283 
Singleton.h
Template support for singleton pattern.
TerraLib
An utility class to control the startup and cleanup of the TerraLib Platform and its resources.
Definition: TerraLib.h:72
TerraLib::getNumRegModules
std::size_t getNumRegModules() const
It returns the number of registered modules.
TerraLib::remove
void remove(const std::size_t i)
It removes the i-th module entry.
TerraLib::initializeTranslations
void initializeTranslations()
This static function is invoked automatically when the application finishes its execution.
TerraLib::getModuleName
const std::string & getModuleName(std::size_t i) const
It return the i-th module name.
TerraLib::TerraLib
TerraLib()
The singleton constructor is not callable outside the class.
TerraLib::m_initialized
std::vector< bool > m_initialized
The list of modules to be initialized when initialize is called.
Definition: TerraLib.h:279
TerraLib::remove
void remove(const std::string &moduleName)
It removes the module entry identified by the given name.
TerraLib::initialize
void initialize()
It initializes the TerraLib Platform.
TerraLib::finalize
void finalize()
It finalizes the TerraLib Platform.
TerraLib::add
void add(std::weak_ptr< Module > m)
It registers the module in the TerraLib Platform.
TerraLib::initialize
void initialize(const std::string &moduleName)
It initializes the registered module in the TerraLib Platform.
TerraLib::finalize
void finalize(const std::size_t i)
It finalizes the i-th registered module in the TerraLib Platform.
TerraLib::getModuleIdx
std::size_t getModuleIdx(const std::string &moduleName) const
It returns the module index inside the internal data structure.
TerraLib::m_modules
std::vector< std::weak_ptr< Module > > m_modules
The list of registered modules.
Definition: TerraLib.h:278
TerraLib::initialize
void initialize(const std::size_t i)
It initializes the i-th registered module in the TerraLib Platform.
TerraLib::finalize
void finalize(const std::string &moduleName)
It finalizes the registered module in the TerraLib Platform.
te::common::Singleton
Template support for singleton pattern.
Definition: Singleton.h:101
TerraLib::Module
This internal structure is used to model the basic information about a TerraLib module.
Definition: TerraLib.h:99
TerraLib::Module::Module
Module(std::string name, StartupFptr startFptr, CleanupFptr cleanupFptr)
Definition: TerraLib.h:100
TerraLib::Module::m_cleanupFptr
CleanupFptr m_cleanupFptr
The module finalization routine.
Definition: TerraLib.h:109
TerraLib::Module::m_startFptr
StartupFptr m_startFptr
The module initialization routine.
Definition: TerraLib.h:108
TerraLib::Module::m_name
std::string m_name
The module name: an internal value used to identify the module in the system. Must be a unique value.
Definition: TerraLib.h:107
TECOMMONEXPORT
#define TECOMMONEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:66
Config.h
Proxy configuration file for TerraView (see terraview_config.h).