include/anna/dbms/Sentence.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_Sentence_hpp
  10 #define anna_dbms_Sentence_hpp
  11
  12 #include <anna/core/mt/Mutex.hpp>
  13
  14 #include <anna/dbms/ResultCode.hpp>
  15
  16 namespace anna {
  17
  18 namespace xml {
  19 class Node;
  20 }
  21
  22 namespace dbms {
  23
  24 class Database;
  25 class Connection;
  26 class Statement;
  27
  28 /**
  29    Clase que facilita la ejecucion de sentencias SQL compuestas y la comprobacion de errores ya que
  30    solo devuelve excepciones de tipo anna::RuntimeException.
  31 */
  32 class Sentence : public Mutex {
  33 public:
  34   /**
  35      Modos de actuar cuando se detecta un error en la ejecucion de las sentencias SQL.
  36      \see Sentence
  37   */
  38   struct Mode { enum _v { ExceptionWhenNotFound, SilentWhenNotFound }; };
  39
  40   /**
  41      Ejecuta la sentencia SQL asociada a este instancia. Antes de invocar a este metodo debemos
  42      activar una seccion critica sobre esta instancia.
  43      \param connection Conexion usada para ejecutar la sentencia. Debe tener activa una seccion critica.
  44   */
  45   virtual dbms::ResultCode execute(dbms::Connection& connection) throw(RuntimeException) {
  46     return execute(connection, a_dbStatement);
  47   }
  48
  49   /**
  50      Devuelve el nombre de la sentencia SQL asociada a esta instancia.
  51      \return El nombre de la sentencia SQL asociada a esta instancia.
  52      \warning Si todavia no tiene nombre asociado devolvera una cadena vacia.
  53   */
  54   const std::string& getName() const throw();
  55
  56   /**
  57      Inicializa el estado de esta instancia
  58      \param database Instancia de la base de datos usada para definir las sentencias SQL que componen esta
  59      instancia.
  60   */
  61   void initialize(dbms::Database& database) throw(RuntimeException);
  62
  63   /**
  64      Transfiere un registro desde la base de datos a las variables del entorno C++.
  65      \return \em false si no hay mas registros o \em true en caso contrario.
  66   */
  67   bool fetch() throw(RuntimeException);
  68
  69   /**
  70      Transfiere un registro desde la base de datos a las variables del entorno C++.
  71      \param resultCode Variable que contiene el resultado de invocar a anna::dbms::Sentence::execute
  72      \return \em false si no hay mas registros o \em true en caso contrario.
  73   */
  74   bool fetch(const ResultCode& resultCode) throw(RuntimeException) {
  75     return (resultCode.successful() == true) ? fetch() : false;
  76   }
  77
  78   /**
  79      Devuelve una cadena con la informacion referente a esta instancia.
  80      \return una cadena con la informacion referente a esta instancia.
  81   */
  82   virtual std::string asString() const throw();
  83
  84   /**
  85      Devuelve un documento XML con la informacion referente a esta instancia.
  86      \param parent Nodo XML del que dependerá la información referente a esta instancia.
  87      \return un documento XML con la informacion referente a esta instancia.
  88   */
  89   virtual xml::Node* asXML(xml::Node* parent) const throw();
  90
  91 protected:
  92   /**
  93      Constructor.
  94      \param mode Modo de actuacion en caso de detectar errores.
  95   */
  96   Sentence(const Mode::_v mode = Mode::ExceptionWhenNotFound) :
  97     a_mode(mode), a_dbStatement(NULL)
  98   {;}
  99
 100   /**
 101      Ejecuta la sentencia SQL asociada a este instancia.
 102      \param connection Conexion usada para ejecutar la sentencia. Debe tener activa una seccion critica.
 103      \param statement Sentencia a ejecutar.
 104   */
 105   dbms::ResultCode execute(dbms::Connection& connection, dbms::Statement* statement) throw(RuntimeException);
 106
 107   /**
 108      Metodo que debe inicializar las sentencias asociadas a esta instancia (valores de entrada y salida).
 109      \return Retorna la instancia de la sentencia asociada a esta instancia debidamente inicializada.
 110   */
 111   virtual dbms::Statement* do_initialize(dbms::Database&) throw(RuntimeException) = 0;
 112
 113 private:
 114   const Mode::_v a_mode;
 115   dbms::Statement* a_dbStatement;
 116 };
 117
 118 }
 119 }
 120
 121 #endif
 122