bug in RC
[anna.git] / include / anna / comm / CompatCodec.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_CompatCodec_hpp
10 #define anna_comm_CompatCodec_hpp
11
12 #include <map>
13
14 #include <anna/core/DataBlock.hpp>
15 #include <anna/core/RuntimeException.hpp>
16 #include <anna/core/util/SortedVector.hpp>
17
18 #include <anna/comm/Message.hpp>
19 #include <anna/comm/Variable.hpp>
20
21 namespace anna {
22
23 class DataBlock;
24 class Second;
25 class Millisecond;
26 class Microsecond;
27
28 namespace comm {
29
30 /**
31    Codificador/Decodificador compatible con los mensajes
32
33    Esta clase ofrece una forma muy eficaz para codificar estructuras de datos complejas y pretende
34    sustituir los tipicos aplanadores y desaplanadores ya que permite que cualquier proceso
35    defina facilmente la forma de transferir cierta informacion sobre un bloque de memoria
36    y viceversa.
37
38    Vamos a ver un ejemplo de uso. Primero vamos a definir la clase MensajeDemo:
39
40 * \code
41 *
42 * #include <anna.comm.CompatCodec.h>
43 *
44 * class MensajeDemo : public CompatCodec {
45 * public:
46 *    static const CompatCodec::Type type = 10;
47 *
48 *    MensajeDemo () : CompatCodec (type),
49 *       a_dataBlock (true)
50 *    {
51 *       attach ("Entero", 0, a_entero);
52 *       attach ("Cadena", 1, a_cadena);
53 *       attach ("Bloque datos", 2, a_dataBlock);
54 *    }
55 *
56 *    // Accesores
57 *    const int obtenerEntero () const { return a_entero; }
58 *    const std::string& obtenerCadena () const { return a_cadena; }
59 *    const DataBlock& obtenerDataBlock () const { return a_dataBlock; }
60 *
61 *    // Modificadores
62 *    void establecerEntero (const int entero) { a_entero = entero; }
63 *    void establecerCadena (const std::string& cadena) { a_cadena = cadena; }
64 *    void establecerCadena (const char* cadena) { a_cadena = cadena; }
65 *    void establecerDataBlock (const DataBlock& dataBlock) { a_dataBlock = dataBlock; }
66 *
67 * private:
68 *    int a_entero;
69 *    std::string a_cadena;
70 *    DataBlock a_dataBlock;
71 * };
72 *
73 * \endcode
74 *
75    La clase que use esta clase para enviar un mensaje debe establecer los valores de cada uno de
76    los datos mediante los modificadores definidos y luego invocar al metodo #code que
77    transferiria el contenido de las variables asociadas a este mensaje a un bloque de memoria,
78    que normalmente seriausado como mensaje.
79
80    Por otra parte la clase que recibe el mensaje invocar�al metodo #decode que transfiere
81    el contenido del bloque de memoria a cada una de las variables asociadas al mensaje.
82    Posteriormente, podremos acceder al contenido de cada una de las variables asociadas al
83    mensaje atraves de los accesores definidos para el caso.
84
85    Estos codificadores nos dan la posibilidad de definir variables opcionales, de forma que
86    una determinada variable puede no ser transferida al bloque de memoria, y por tanto puede
87    no ser recibida en el otro extremo. Ver el metodo #isNull y #setNull para mas informacion.
88
89    \warning Esta clase no establece proteccion ante accesos concurrentes
90 */
91 class CompatCodec : public Message {
92   struct SortById {
93     static short int value(const comm::Variable* variable) throw() {
94       return variable->getId();
95     }
96   };
97
98   class VariableContainer {
99   public:
100     typedef comm::Variable* type_pointer;
101
102     typedef type_pointer* iterator;
103     typedef const type_pointer* const_iterator;
104
105     VariableContainer();
106
107     void clear() throw();
108     void add(comm::Variable* variable) throw();
109     comm::Variable* find(const int id) throw();
110     const comm::Variable* find(const int id) const throw();
111
112     int size() const throw() { return a_size; }
113
114     iterator begin() throw() { return a_variables; }
115     iterator end() throw() { return a_variables + a_size; }
116
117     const_iterator begin() const throw() { return a_variables; }
118     const_iterator end() const throw() { return a_variables + a_size; }
119
120     static comm::Variable* data(iterator ii) throw() { return *ii; }
121     static const comm::Variable* data(const_iterator ii) throw() { return *ii; }
122
123   private:
124     comm::Variable** a_variables;
125     int a_maxSize;
126     int a_size;
127   };
128
129 public:
130 //   typedef SortedVector <comm::Variable, SortById, short int> container;
131   typedef VariableContainer container;
132   typedef container::iterator iterator;
133   typedef container::const_iterator const_iterator;
134   typedef unsigned char Type;
135
136   /**
137      Constructor.
138
139      @param type Tipo por el que sera conocido este tipo de mensaje.
140      @param scramble Indica si el mensaje debe ser codificado de forma que no se pueda ver el contenido
141      del mismo con una simple herramienta de monitorizacion de mensajes de red. Por defecto esta
142      activo ya que la codificacion realizada es muy simple y rapida y el tiempo empleado es casi
143      inapreciable.
144   */
145   explicit CompatCodec(const Type type, const bool scramble = true);
146
147   /**
148      Destructor.
149   */
150   virtual ~CompatCodec();
151
152   // Accesores
153   /**
154      Devuelve el identificador del mensaje indicado en el constructor.
155     @return El identificador de este mensaje.
156   */
157   Type getType() const throw() { return a_type; }
158
159 // Metodos
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 id Identificador asignado al dato.
168      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
169      al mensaje y viceversa.
170      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
171   */
172   const Variable* attach(const char* name, const short int id, std::string& value) throw(RuntimeException);
173
174   /**
175      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
176      estapensada principalmente para comunicar entre si procesos remotos
177      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
178      de ellos le da a un determinado `id'.
179
180      \param name Nombre logico de la variable
181      @param id Identificador asignado al dato.
182      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
183      al mensaje y viceversa.
184      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
185   */
186   const Variable* attach(const char* name, const short int id, const char*& value) throw(RuntimeException);
187
188   /**
189      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
190      estapensada principalmente para comunicar entre si procesos remotos
191      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
192      de ellos le da a un determinado `id'.
193
194      \param name Nombre logico de la variable
195      @param id Identificador asignado al dato.
196      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
197      al mensaje y viceversa.
198      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
199   */
200   const Variable* attach(const char* name, const short int id, int& value) throw(RuntimeException);
201
202   /**
203      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
204      estapensada principalmente para comunicar entre si procesos remotos
205      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
206      de ellos le da a un determinado `id'.
207
208      \param name Nombre logico de la variable
209      @param id Identificador asignado al dato.
210      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
211      al mensaje y viceversa.
212      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
213   */
214   const Variable* attach(const char* name, const short int id, S64& value) throw(RuntimeException);
215
216   /**
217      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
218      estapensada principalmente para comunicar entre si procesos remotos
219      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
220      de ellos le da a un determinado `id'.
221
222      \param name Nombre logico de la variable
223      @param id Identificador asignado al dato.
224      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
225      al mensaje y viceversa.
226      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
227   */
228   const Variable* attach(const char* name, const short int id, bool& value) throw(RuntimeException);
229
230   /**
231      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
232      estapensada principalmente para comunicar entre si procesos remotos
233      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
234      de ellos le da a un determinado `id'.
235
236      \param name Nombre logico de la variable
237      @param id Identificador asignado al dato.
238      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
239      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
240      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
241   */
242   const Variable* attach(const char* name, const short int id, DataBlock& value) throw(RuntimeException);
243
244   /**
245      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
246      estapensada principalmente para comunicar entre si procesos remotos
247      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
248      de ellos le da a un determinado `id'.
249
250      \param name Nombre logico de la variable
251      @param id Identificador asignado al dato.
252      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
253      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
254      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
255   */
256   const Variable* attach(const char* name, const short int id, float& value) throw(RuntimeException);
257
258   /**
259      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
260      estapensada principalmente para comunicar entre si procesos remotos
261      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
262      de ellos le da a un determinado `id'.
263
264      \param name Nombre logico de la variable
265      @param id Identificador asignado al dato.
266      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
267      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
268      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
269   */
270   const Variable* attach(const char* name, const short int id, double& value) throw(RuntimeException);
271
272   const Variable* attach(const char* name, const short int id, Second& value) throw(RuntimeException);
273   const Variable* attach(const char* name, const short int id, Millisecond& value) throw(RuntimeException);
274   const Variable* attach(const char* name, const short int id, Microsecond& value) throw(RuntimeException);
275
276   /**
277    * Asocia el mensaje recibido como un parámetro interno especificado por \em id.
278    * \param name Nombre lógico de la variable.
279    * \param id Identificador del dato asignado.
280    * \param value Instancia del mensaje que se codificará/decodificará de forma recursiva.
281    */
282   const Variable* attach(const char* name, const short int id, comm::CompatCodec& value) throw(RuntimeException);
283
284   /**
285      Devuelve la referencia al dato interno identificado por el `id' recibido como parametro.
286
287      @param id Identificador asignado al dato que queremos obtener.
288
289      @return La referencia de la variable identificada por 'id'. Si no existe se lanzar�una excepcin.
290   */
291   const Variable& find(const short int id) const throw(RuntimeException);
292
293   /**
294      Marca el dato asociado al identificador recibido como nulo, lo cual conlleva que el dato no seria
295      transferido al bloque de memoria del mensaje en caso de invocar al metodo de codificacion.
296
297      @param id Identificador asignado al dato.
298      @param isNull Indica la nueva marca de la variable.
299   */
300   void setNull(const short int id, const bool isNull = true) throw(RuntimeException);
301
302   /**
303      Marca el dato recibido como nulo, lo cual conlleva que el dato no seria transferido al bloque
304      de memoria del mensaje en caso de invocar al metodo de codificacion.
305
306      @param variable Instancia de Varaible obtenida al invocar al método #attach
307      @param isNull Indica la nueva marca de la variable.
308   */
309   void setNull(const Variable* variable, const bool isNull = true) throw();
310
311   /**
312      @param id Identificador asignado al dato.
313   *
314      @return Devuelve @em false si el dato identificado por `id' tiene algun valor o @em true en caso de que
315      el dato haya sido marcado como nulo. Por defecto se considera que todos los datos tienen valor.
316      Un dato puede tener un value nulo, bien por que se ha invocado a la funcin @ref setNull
317      o bien porque se recibio un mensaje en el que no venia contenido el identificador del dato.
318   */
319   bool isNull(const short int id) const throw(RuntimeException);
320
321   /**
322      Devuelve un iterador al comienzo de la lista de variables asociados a este mensaje.
323      \return Un iterador al comienzo de la lista de variables asociados a este mensaje.
324   */
325   iterator begin() throw() { return a_variables.begin(); }
326
327   /**
328      Devuelve un iterador al comienzo de la lista de variables asociados a este mensaje.
329      \return Un iterador al comienzo de la lista de variables asociados a este mensaje.
330   */
331   const_iterator begin() const throw() { return a_variables.begin(); }
332
333   /**
334      Devuelve un iterador al comienzo de la lista de variables asociados a este mensaje.
335      \return Un iterador al final de la lista de variables asociados a este mensaje.
336   */
337   iterator end() throw() { return a_variables.end(); }
338
339   /**
340      Devuelve un iterador al comienzo de la lista de variables asociados a este mensaje.
341      \return Un iterador al final de la lista de variables asociados a este mensaje.
342   */
343   const_iterator end() const throw() { return a_variables.end(); }
344
345   /**
346      Devuelve el número de enginees asociados a.esta instancia.
347      \return el número de enginees asociados a.esta instancia.
348   */
349   int size() const throw() { return a_variables.size(); }
350
351   /**
352      Devuelve la instancia de la variable sobre el que esta posicionado el iterador recibido
353      como parametro.
354      \param ii Iterador que debera estar comprendido entre begin y end.
355      \return La instancia de la variable sobre el que esta posicionado el iterador recibido
356   */
357   static Variable* variable(iterator ii) throw() { return container::data(ii); }
358
359   /**
360      Devuelve la instancia de la variable sobre el que esta posicionado el iterador recibido
361      como parametro.
362      \param ii Iterador que debera estar comprendido entre begin y end.
363      \return La instancia de la variable sobre el que esta posicionado el iterador recibido
364   */
365   static const Variable* variable(const_iterator ii) throw() { return container::data(ii); }
366
367   /**
368      Transfiene los datos establecidos en este mensaje interno a un bloque de memoria cuya instancia es devuelta por este metodo.
369      @return Bloque de memoria que contiene la informacion del mensaje.
370   */
371   virtual const DataBlock& code() throw(RuntimeException);
372
373   /**
374      Transfiene la informacion contenida en el bloque de memoria recibido hacia las variables asociadas a este mensaje interno.
375      Las variables cuyo value no esta incluidas en el bloque de memoria seria marcadas como nulas.
376
377      @param dataBlock Bloque de memoria que contiene las variables codificadas.
378   */
379   virtual void decode(const DataBlock& dataBlock) throw(RuntimeException);
380
381   /**
382      Permite conocer el identificador del mensaje que viene contenido en el bloque de memoria
383      antes de realizar la decodificacion.
384
385      @param dataBlock Bloque de memoria que contiene la informacion del mensaje.
386
387      @return El tipo del mensaje contenido en el bloque de memoria.
388   */
389   static Type getType(const DataBlock& dataBlock) throw(RuntimeException);
390
391 protected:
392   bool a_scramble;
393
394 private:
395   const Type a_type;
396   container a_variables;
397   int a_nullCounter;
398
399   static bool st_initScramble;
400
401   CompatCodec(const CompatCodec&);
402   CompatCodec& operator = (const CompatCodec&);
403
404   void normalDecode(const char* data, const int size, const int maxdata) throw(RuntimeException);
405   bool optimizedDecode(const char* data, const int size) throw(RuntimeException);
406 };
407
408 }
409 }
410
411 #endif