include/anna/comm/Codec.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_comm_Codec_hpp
  10 #define anna_comm_Codec_hpp
  11
  12 #include <anna/comm/CompatCodec.hpp>
  13
  14 namespace anna {
  15
  16 class Second;
  17 class Millisecond;
  18 class Microsecond;
  19 namespace comm {
  20
  21 /**
  22    Codificador/Decodificador compatible para transporte de datos
  23
  24    Esta clase ofrece una forma muy eficaz para codificar estructuras de datos complejas y pretende
  25    sustituir los tipicos aplanadores y desaplanadores ya que permite que cualquier proceso
  26    defina facilmente la forma de transferir cierta informacion sobre un bloque de memoria
  27    y viceversa.
  28
  29    Vamos a ver un ejemplo de uso. Primero vamos a definir la clase MensajeDemo:
  30
  31 * \code
  32 *
  33 * #include <anna.comm.Codec.h>
  34 *
  35 * class MensajeDemo : public Codec {
  36 * public:
  37 *    static const Codec::Type type = 10;
  38 *
  39 *    MensajeDemo () : Codec (type),
  40 *       a_dataBlock (true)
  41 *    {
  42 *       attach ("Entero", a_entero);
  43 *       attach ("Cadena",  a_cadena);
  44 *       attach ("Bloque datos",  a_dataBlock);
  45 *    }
  46 *
  47 *    // Accesores
  48 *    const int obtenerEntero () const { return a_entero; }
  49 *    const std::string& obtenerCadena () const { return a_cadena; }
  50 *    const DataBlock& obtenerDataBlock () const { return a_dataBlock; }
  51 *
  52 *    // Modificadores
  53 *    void establecerEntero (const int entero) { a_entero = entero; }
  54 *    void establecerCadena (const std::string& cadena) { a_cadena = cadena; }
  55 *    void establecerCadena (const char* cadena) { a_cadena = cadena; }
  56 *    void establecerDataBlock (const DataBlock& dataBlock) { a_dataBlock = dataBlock; }
  57 *
  58 * private:
  59 *    int a_entero;
  60 *    std::string a_cadena;
  61 *    DataBlock a_dataBlock;
  62 * };
  63 *
  64 * \endcode
  65 *
  66    La clase que use esta clase para enviar un mensaje debe establecer los valores de cada uno de
  67    los datos mediante los modificadores definidos y luego invocar al metodo #code que
  68    transferiria el contenido de las variables asociadas a este mensaje a un bloque de memoria,
  69    que normalmente seriausado como mensaje.
  70
  71    Por otra parte la clase que recibe el mensaje invocar�al metodo #decode que transfiere
  72    el contenido del bloque de memoria a cada una de las variables asociadas al mensaje.
  73    Posteriormente, podremos acceder al contenido de cada una de las variables asociadas al
  74    mensaje atraves de los accesores definidos para el caso.
  75
  76    Estos codificadores nos dan la posibilidad de definir variables opcionales, de forma que
  77    una determinada variable puede no ser transferida al bloque de memoria, y por tanto puede
  78    no ser recibida en el otro extremo. Ver el metodo #isNull y #setNull para mas informacion.
  79
  80    \warning Esta clase no establece proteccion ante accesos concurrentes
  81 */
  82 class Codec : public CompatCodec {
  83 public:
  84   /**
  85      Constructor.
  86
  87      @param type Tipo por el que sera conocido este tipo de mensaje.
  88      @param scramble Indica si el mensaje debe ser codificado de forma que no se pueda ver el contenido
  89      del mismo con una simple herramienta de monitorizacion de mensajes de red. Por defecto esta
  90      activo ya que la codificacion realizada es muy simple y rapida y el tiempo empleado es casi
  91      inapreciable.
  92   */
  93   explicit Codec(const Type type, const bool scramble = true) : CompatCodec(type, scramble) {;}
  94
  95   /**
  96      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
  97      estapensada principalmente para comunicar entre si procesos remotos
  98      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
  99      de ellos le da a un determinado `id'.
 100
 101      \param name Nombre logico de la variable
 102      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
 103      al mensaje y viceversa.
 104      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
 105   */
 106   const Variable* attach(const char* name, std::string& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
 107
 108   /**
 109      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
 110      estapensada principalmente para comunicar entre si procesos remotos
 111      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
 112      de ellos le da a un determinado `id'.
 113
 114      \param name Nombre logico de la variable
 115      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
 116      al mensaje y viceversa.
 117      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
 118   */
 119   const Variable* attach(const char* name, const char*& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
 120
 121   /**
 122      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
 123      estapensada principalmente para comunicar entre si procesos remotos.
 124      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
 125      de ellos le da a un determinado `id'.
 126
 127      \param name Nombre logico de la variable
 128      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
 129      al mensaje y viceversa.
 130      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
 131   */
 132   const Variable* attach(const char* name, int& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
 133
 134   /**
 135      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
 136      estapensada principalmente para comunicar entre si procesos remotos.
 137      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
 138      de ellos le da a un determinado `id'.
 139
 140      \param name Nombre logico de la variable
 141      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
 142      al mensaje y viceversa.
 143      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
 144   */
 145   const Variable* attach(const char* name, S64& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
 146
 147   /**
 148      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
 149      estapensada principalmente para comunicar entre si procesos remotos.
 150      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
 151      de ellos le da a un determinado `id'.
 152
 153      \param name Nombre logico de la variable
 154      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
 155      al mensaje y viceversa.
 156      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
 157   */
 158   const Variable* attach(const char* name, bool& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
 159
 160   /**
 161      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
 162      estapensada principalmente para comunicar entre si procesos remotos.
 163      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
 164      de ellos le da a un determinado `id'.
 165
 166      \param name Nombre logico de la variable
 167      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
 168      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
 169      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
 170   */
 171   const Variable* attach(const char* name, DataBlock& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
 172
 173   /**
 174      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
 175      estapensada principalmente para comunicar entre si procesos remotos.
 176      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
 177      de ellos le da a un determinado `id'.
 178
 179      \param name Nombre logico de la variable
 180      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
 181      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
 182      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
 183   */
 184   const Variable* attach(const char* name, float& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
 185
 186   /**
 187      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
 188      estapensada principalmente para comunicar entre si procesos remotos.
 189      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
 190      de ellos le da a un determinado `id'.
 191
 192      \param name Nombre logico de la variable
 193      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
 194      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
 195      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
 196   */
 197   const Variable* attach(const char* name, double& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
 198
 199   /**
 200      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
 201      estapensada principalmente para comunicar entre si procesos remotos.
 202      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
 203      de ellos le da a un determinado `id'.
 204
 205      \param name Nombre logico de la variable
 206      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
 207      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
 208      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
 209   */
 210   const Variable* attach(const char* name, Second& value) throw(RuntimeException);
 211
 212   /**
 213      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
 214      estapensada principalmente para comunicar entre si procesos remotos.
 215      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
 216      de ellos le da a un determinado `id'.
 217
 218      \param name Nombre logico de la variable
 219      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
 220      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
 221      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
 222   */
 223   const Variable* attach(const char* name, Millisecond& value) throw(RuntimeException);
 224
 225   /**
 226      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
 227      estapensada principalmente para comunicar entre si procesos remotos
 228      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
 229      de ellos le da a un determinado `id'.
 230
 231      \param name Nombre logico de la variable
 232      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
 233      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
 234      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
 235   */
 236   const Variable* attach(const char* name, Microsecond& value) throw(RuntimeException);
 237 };
 238
 239 }
 240 }
 241
 242 #endif