include/anna/dbms/functions.hpp

   1 // ANNA - Anna is Not Nothingness Anymore                                                         //
   2 //                                                                                                //
   3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo                         //
   4 //                                                                                                //
   5 // See project site at http://redmine.teslayout.com/projects/anna-suite                           //
   6 // See accompanying file LICENSE or copy at http://www.teslayout.com/projects/public/anna.LICENSE //
   7
   8
   9 #ifndef anna_dbms_functions_hpp
  10 #define anna_dbms_functions_hpp
  11
  12 #include <anna/core/RuntimeException.hpp>
  13
  14 namespace anna {
  15 namespace dbms {
  16 class Connection;
  17 }
  18 }
  19
  20 namespace anna {
  21 namespace dbms {
  22
  23 using namespace anna;
  24
  25
  26 /**
  27    Métodos usados habitualmente para trabajar contra la base de datos.
  28 */
  29 struct functions {
  30 public:
  31   /**
  32    * Este metodo asegura la integridad entre el esquema de tablas instalado y el esperado por los procesos de un proyecto.
  33    * Para ello cada uno de los proyectos debe invocar a este método indicado los parámetro requeridos. Es imprescindible
  34    * que la versión esperada del esquema de base de datos esté definida en una única variable centralizada.
  35    *
  36    * La idea es que cada vez que hagamos un cambio en la estructura de tablas de una cierta entidad cambiemos la versión
  37    * del esquema, y ese cambio deberá reflejarse en la invocación a este nuevo método.
  38    *
  39    * Este método lanzará una excepción si el último parche instalado en el esquema de base de datos no coincide
  40    * con el valor de la variable \em requiredPatch.
  41    *
  42    * Cada proceso debe invocar la comprobación de esquema en cuanto la base de datos tenga una conexión disponible, de forma
  43    * que si el esquema de base de datos no coincide con el esperado el proceso mostrará un error indicado el esquema de base
  44    * de datos esperado y el esquema de base datos instalado.
  45    *
  46    * Para usar este método el esquema de base de nuestro proyecto debe disponer de una tabla  que debe contener, al menos,
  47    * la siguiente estructura:
  48    *
  49    * \code
  50    * -- Ejemplo de creación para Oracle(tm)
  51    * create table axe_dataScheme (
  52    *    id varchar(8) not null,
  53    *    installation_date date default sysdate not null
  54    * );
  55    *
  56    * alter table axe_dataScheme add constraint axe_dataScheme_pk primary key (id);
  57    *
  58    * \endcode
  59    *
  60    * \code
  61    * -- Ejemplo de creación para PostgreSQL
  62    * create table data_scheme (
  63    *    id varchar(8) not null,
  64    *    installation_date timestamp default now (),
  65    *    primary key (id)
  66    * );
  67    * \endcode
  68    *
  69    * El nombre de la tabla y los campos de las columnas podrían ser distintos ya que este método los recibe como parámetros.
  70    *
  71    * Un ejemplo de implementación podría ser:
  72    *
  73    * \code
  74    * //static
  75    * void axe::storage::functions::verifyDataScheme (dbms::Connection& connection)
  76    *    throw (RuntimeException)
  77    * {
  78    *    anna::dbms::functions::verifyDataScheme (connection, "axe_dataScheme", "v1.3");
  79    * }
  80    * \endcode
  81    *
  82    * \param connection Conexión usada para acceder a los datos.
  83    * \param tableName Nombre de la tabla que contiene las versiones instaladas.
  84    * \param requiredPatch Identificador de parche de base de base de datos requerido por los procesos de nuestro proyecto.
  85    * Este indicador debería estar definido en un único punto para todo nuestro proyecto.
  86    * \param columnID Nombre de la columna que contiene el identificador de cada uno de los parches instalados.
  87    * \param columnDate Nombre de la columna que contiene la fecha de instalación de cada parche.
  88    */
  89   static void verifyDataScheme(dbms::Connection& connection, const char* tableName, const char* requiredPatch, const char* columnID = "id", const char* columnDate = "installation_date")
  90   throw(RuntimeException);
  91 };
  92
  93 }
  94 }
  95
  96 #endif