Revert "Remove mysql and oracle resources for anna-ericsson project"

[anna.git] / include / anna / dbms / functions.hpp

diff --git a/include/anna/dbms/functions.hpp b/include/anna/dbms/functions.hpp
new file mode 100644 (file)
index 0000000..e782d34
--- /dev/null
+++ b/include/anna/dbms/functions.hpp
@@ -0,0 +1,96 @@
+// ANNA - Anna is Not Nothingness Anymore                                                         //
+//                                                                                                //
+// (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo                         //
+//                                                                                                //
+// See project site at http://redmine.teslayout.com/projects/anna-suite                           //
+// See accompanying file LICENSE or copy at http://www.teslayout.com/projects/public/anna.LICENSE //
+
+
+#ifndef anna_dbms_functions_hpp
+#define anna_dbms_functions_hpp
+
+#include <anna/core/RuntimeException.hpp>
+
+namespace anna {
+namespace dbms {
+class Connection;
+}
+}
+
+namespace anna {
+namespace dbms {
+
+using namespace anna;
+
+
+/**
+   Métodos usados habitualmente para trabajar contra la base de datos.
+*/
+struct functions {
+public:
+  /**
+   * Este metodo asegura la integridad entre el esquema de tablas instalado y el esperado por los procesos de un proyecto.
+   * Para ello cada uno de los proyectos debe invocar a este método indicado los parámetro requeridos. Es imprescindible
+   * que la versión esperada del esquema de base de datos esté definida en una única variable centralizada.
+   *
+   * La idea es que cada vez que hagamos un cambio en la estructura de tablas de una cierta entidad cambiemos la versión
+   * del esquema, y ese cambio deberá reflejarse en la invocación a este nuevo método.
+   *
+   * Este método lanzará una excepción si el último parche instalado en el esquema de base de datos no coincide
+   * con el valor de la variable \em requiredPatch.
+   *
+   * Cada proceso debe invocar la comprobación de esquema en cuanto la base de datos tenga una conexión disponible, de forma
+   * que si el esquema de base de datos no coincide con el esperado el proceso mostrará un error indicado el esquema de base
+   * de datos esperado y el esquema de base datos instalado.
+   *
+   * Para usar este método el esquema de base de nuestro proyecto debe disponer de una tabla  que debe contener, al menos,
+   * la siguiente estructura:
+   *
+   * \code
+   * -- Ejemplo de creación para Oracle(tm)
+   * create table axe_dataScheme (
+   *    id varchar(8) not null,
+   *    installation_date date default sysdate not null
+   * );
+   *
+   * alter table axe_dataScheme add constraint axe_dataScheme_pk primary key (id);
+   *
+   * \endcode
+   *
+   * \code
+   * -- Ejemplo de creación para PostgreSQL
+   * create table data_scheme (
+   *    id varchar(8) not null,
+   *    installation_date timestamp default now (),
+   *    primary key (id)
+   * );
+   * \endcode
+   *
+   * 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.
+   *
+   * Un ejemplo de implementación podría ser:
+   *
+   * \code
+   * //static
+   * void axe::storage::functions::verifyDataScheme (dbms::Connection& connection)
+   *    throw (RuntimeException)
+   * {
+   *    anna::dbms::functions::verifyDataScheme (connection, "axe_dataScheme", "v1.3");
+   * }
+   * \endcode
+   *
+   * \param connection Conexión usada para acceder a los datos.
+   * \param tableName Nombre de la tabla que contiene las versiones instaladas.
+   * \param requiredPatch Identificador de parche de base de base de datos requerido por los procesos de nuestro proyecto.
+   * Este indicador debería estar definido en un único punto para todo nuestro proyecto.
+   * \param columnID Nombre de la columna que contiene el identificador de cada uno de los parches instalados.
+   * \param columnDate Nombre de la columna que contiene la fecha de instalación de cada parche.
+   */
+  static void verifyDataScheme(dbms::Connection& connection, const char* tableName, const char* requiredPatch, const char* columnID = "id", const char* columnDate = "installation_date")
+  throw(RuntimeException);
+};
+
+}
+}
+
+#endif