Common Runtime Module

The TerraLib Common Runtime module contains the foundation classes and functions that makes the basic support for other TerraLib modules. It provides portable and cross platform code not focus exclusively in the geo-spatial domain. On the contrary, the helper classes, utilitary functions, generic class templates and generic design pattern classes are domain application neutral and can be used by any application.

The TerraLib modules has made use of Boost libraries but some functionalities are not found in Boost, so the common runtime module fills this gap and add some low-level code used by TerraLib applications.

You will find in this module classes for: abstract factories, singletons, visitors, support for i18n, message logging, shared library management, threading policies and much more. Besides the classes you will find useful routines for: byte swap, hex-encoding/decoding, platform specific routines, auxiliary functions for STL containers.

This section explains not only the general design guidelines applied to the common module but also to all TerraLib modules.

Every module in TerraLib has a special singleton class called Module. These classes are responsible for making an static initialization of all the functionalities available in those modules and also for registering some special functions called at the module load time (like initializations after the statics).

There are some special modules called plugins that have different startup mechanism and are discussed in more detail in the Plugins section.

All the TerraLib code is inside th namespace te, and each module will add its own namespace. The use of namespace has several benefits, and we try to use it carefully. The rule used in TerraLib is very simple:

• each module has its own namespace;
• and all namespaces belong to the main namespace called te.

We recommend to avoid the C++ using keyword. For example, if you want to use a class called Exception located in the Common module, you can write a code like this:

te::common::Exception e("my exception text goes here...");

and if you want to call a function, like Convert2String:

std::string mystring = te::common::Convert2String(67);

There is a file called terralib.h that contains include directives for all TerraLib modules. It is located at the root of the source tree. In the Linux system this file is installed under the system include headers (typically under /usr/include or /usr/local/include). In the Windows binary distribution it is located at the root of the folder named include.

Each module will also have a particular file that includes all its files. For example, the common.h contains the includes of all files belonging to the Common Runtime module. This kind of file has also another special role, it defines and documents the namespace for the module.

Every module also provides a forward declaration file for its classes. For example, the common_fw.h contains te forward declaration of all classes defined in the Common Runtime module.

The guard macros used in TerraLib has the form: __TERRALIB_MODULE-NAME_INTERNAL_FILE-NAME_H.

For example, the Module.h file located at the Common module will have the following guard macro:

#ifndef __TERRALIB_COMMON_INTERNAL_MODULE_H
#define __TERRALIB_COMMON_INTERNAL_MODULE_H
 
// file scope
 
#endif  // __TERRALIB_COMMON_INTERNAL_MODULE_H

TerraLib modules uses double quotes (#include “../module/file.h”) with relative path when referring to other TerraLib files. When reffering to third party libraries or STL it is used <> (#include <iostream> or #include <QtGui/QWidget>).

We dont't use tabs inside source code files. Instead we use two spaces to ident the code.

TO BE DONE

• protected non-virtual destructors: some classes of TerraLib has a protected destructor to avoid the overhead added by virtual methods and to protect the programmer from deleting a pointer to the base type when the base type is not of supposed to be handled as an abstract class. See the general singleton class.
• use of policies when possible: one of the design decisions behind TerraLib was to make it extensible an plugable at runtime. This puts some restrictions on how TerraLib code can be implemented: abstract classes, no template at driver implementation, … <color gray>TO BE DONE</color>
• some base classes used a fixed policy that can be configure at build time using macros, for example the threading model.
• TerraLib 5 has adopted template meta-programming (colocar ref. para Dave Abrahams), policy design (colocar ref para Alexandrescu) and design patterns (colocar referencia para GoF).
• classes that are not copy constructible nor can be assigned must derive from boost::noncopyable.
• Static classes must derived from the base class Static.
• Singletons must be derived from Singleton class when possible.
• When you have a code dealing with STL conteiners that appears many times it is recommended to add an implementation at STLUtils.h file.
• When you have a platform specific code try to distribute the code along the files LinuxUtils and WindowsUtils.
• Factories can be created from the AbstractFatory and ParameterizedAbstractFactory when possible.
• Instead of relying on plain string when you are refereing to a resource prefer to use an URI when possible (you have to consider efficiency in some cases and a string may be prefered).

-------------------------------------------------------------------------------
Language          files     blank   comment      code    scale   3rd gen. equiv
-------------------------------------------------------------------------------
C++                  37       697       801      3313 x   1.51 =        5002.63
C/C++ Header         66      2307      4059      3113 x   1.00 =        3113.00
-------------------------------------------------------------------------------
SUM:                103      3004      4860      6426 x   1.26 =        8115.63
-------------------------------------------------------------------------------

Besides the C++ code there is also some XML schemas (xsd) and XML documents for some elements:

• Unit of measure
• Locales
• Countries