685b4297f823c7705b8cd205c459899f8ce94768
[anna.git] / 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    *    noexcept(false)
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   noexcept(false);
91 };
92
93 }
94 }
95
96 #endif