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