Loading...
Searching...
No Matches
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*/
71class 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::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::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::StartupFptr
void(* StartupFptr)(void)
This is the type for call back functions that makes the startup of a module.
Definition TerraLib.h:82
TerraLib::initialize
void initialize()
It initializes the TerraLib Platform.
TerraLib::finalize
void finalize()
It finalizes the TerraLib Platform.
TerraLib::getModuleName
const std::string & getModuleName(std::size_t i) const
It return the i-th module name.
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.
TerraLib::CleanupFptr
void(* CleanupFptr)(void)
This is the type for call back functions that makes the cleanup of a module.
Definition TerraLib.h:89
te::common::Singleton
Template support for singleton pattern.
Definition Singleton.h:101
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
Config.h
Configuration flags for the TerraLib Common Runtime module.
TECOMMONEXPORT
#define TECOMMONEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition Config.h:66