bug in RC
[anna.git] / include / anna / comm / Transport.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_Transport_hpp
10 #define anna_comm_Transport_hpp
11
12 #include <anna/core/RuntimeException.hpp>
13 #include <anna/core/DataBlock.hpp>
14
15 namespace anna {
16
17 namespace comm {
18
19 class Communicator;
20 class Message;
21
22 /**
23    Clase generica para definir la capa de transporte de cualquier protocolo de comunicaciones.
24
25    Estructura basica que nos permite ordenar el proceso de analizar un mensaje recibido desde
26    cualquier medio. El protocolo conoce los detalles semanticos del mensaje que ha recibido,
27    es decir, conoce como interpretar cada uno de los bytes que componen el mensaje, cuando un
28    mensaje esta completo.
29
30    El principal problema de cualquier protocolo externo a la hora de recibir es conocer cual
31    es el tamao de un determinado mensaje.
32
33    Todos los metodos que se deberian reescribir en las clases heredadas se invocan desde un
34    metodo MT-safe que se encarga de evitar accesos simultaneos desde varios threads, lo cual,
35    evita que tengamos que preocuparnos por establecer secciones criticas en cada uno de los
36    metodos reescritos.
37
38    \warning Los supuestos bajo los que se diseñó éste protocolo facilitan el desarrollo de
39    clases que ofrecen un gran rendimiento, pero imposibilitan el desarrollo del sistema de
40    re-sincronización en caso de que alguno de los mensajes no cumpla los supuestos.
41    Es decir, si nos llega un mensaje errneo nuestro proceso no sera capaz de volver a
42    sincronizarse nunca mas.
43 */
44 class Transport {
45 public:
46   /**
47     Maximum number of bytes kept by each ClientSocket without identifying
48     a message for the own protocol.
49   */
50   WHEN_SINGLETHREAD(
51     static const int DefaultOverQuotaSize = 2048;
52   )
53   WHEN_MULTITHREAD(
54     static const int DefaultOverQuotaSize = 8192;
55   )
56
57   /**
58     Returns true if the transport layer has a timming control system activated.
59   */
60   bool enableTimeout() const throw() { return a_enableTimeout; }
61
62   /**
63     Activates the timming control system for the ClientSocket which were created
64     through this transport layer. They will be automatically closed if no activity
65     is detected in a time interval.
66     \see Communicator::setTimeout.
67   */
68   void activateTimeout() throw() { a_enableTimeout = true; }
69
70   /**
71     Deactivates the timming control system for the ClientSocket which were created
72     through this transport layer.
73   */
74   void deactivateTimeout() throw() { a_enableTimeout = false; }
75
76
77   // Internal use: returns associated input message
78   Message* getInputMessage() throw(RuntimeException) {
79     return (a_inputMessage == NULL) ? nullInputMessage() : a_inputMessage;
80   }
81
82   /**
83     Returns the number of bytes reserved by this protocol for the intermediate buffer.
84     @return number of bytes reserved by this protocol for the intermediate buffer.
85   */
86   int getOverQuotaSize() const throw() { return a_overQuotaSize; }
87
88   /**
89     Establece el numero de bytes que puede mantener este procotolo para cada uno de los
90     ClientSocket sin que se halla identificado el mensaje como propio del protocolo.
91     Si el numero de bytes guardados en la memoria intermedia sobrepasa este numero de
92     bytes se cerrara la conexion con el ClientSocket.
93
94     \param overQuotaSize Numero de maximo de bytes que podemos mantener en la memoria intermedia.
95   */
96   void setOverQuotaSize(const int overQuotaSize) throw() { a_overQuotaSize = (overQuotaSize >= MinOverQuotaSize) ? overQuotaSize : MinOverQuotaSize; }
97
98   /**
99      Debe calcular el tamao previsto del mensaje actual.
100
101      Si se detecta una anomalia irrecuperable en el mensaje debe devolver una excepcion
102      para indicar el error.
103
104      @param dataBlock Bloque con la parte del mensaje disponible hasta el momento.
105
106      @return Si con la informacion disponible no puede establecer la longitud del
107      mensaje devolvera -1 en otro caso devolvera la longitud prevista del mensaje.
108
109      \warning
110         Si el protocolo de transporte implementado detecta problemas al calcular la
111         longitud del mensaje recibido y lanza una excepcion en este metodo el ClientSocket
112         activara los sistemas de recuperacion, si es posible.
113   */
114   virtual int calculeSize(const DataBlock& dataBlock) throw(RuntimeException) = 0;
115
116   /**
117      Debe establecer el modo en que el protocolo va a verificar que el mensaje obtenido
118      coincide con el patrn esperado e interpretar el contenido del mensaje.
119      Este metodo slo se invoca cuando se considera que el mensaje actual esta completo.
120
121      Si se detecta una anomalia irrecuperable en el mensaje debe devolver una excepcion
122      para indicar el error.
123
124      @param message Bloque con lo que hasta el momento se considera el ltimo mensaje recibido
125      por completo.
126
127      \return Un bloque de memoria que contiene el mensaje recibido codificado segn las reglas del
128      protocolo este protocolo de transporte
129   */
130   virtual const Message* decode(const DataBlock& message) throw(RuntimeException) = 0;
131
132   /**
133      Debe establecer la forma en el protocolo va a preparar el envio a la capa de transporte.
134
135      @param message Bloque de datos con la codificacin obtenida mediante cualquiera de los
136      codec disponibles (Ver @ref Codec).
137
138      @return El bloque de memoria con el mensaje que sera enviado a la capa de transporte.
139
140      \warning De no indicarse ninguna otra implementacin devolvera el mensaje tal y como
141      sea recibido.
142   */
143   virtual const DataBlock& code(Message& message) throw(RuntimeException) = 0;
144
145   /**
146      Metodo que inicializa el estado de esta capa de transporte. Sera invocado automaticamente por el
147      nucleo anna.comm.
148   */
149   virtual void clear() throw() { a_forCode.clear(); }
150
151 protected:
152   DataBlock a_forCode; /**< Bloque de memoria usado para guardar el contenido de la codificacion */
153
154   /**
155      Constructor.
156      \param autoSynchronize Indica si el el protocolo instancia permite la sincronizacion automatica.
157      \param overQuotaSize Longitud maxima que puede contener el buffer intermedio antes de cerrar el socket
158       por considerar que no puede sincronizarlo.
159   */
160   Transport() :
161     a_inputMessage(NULL),
162     a_forCode(true),
163     a_enableTimeout(false) {
164     a_overQuotaSize = DefaultOverQuotaSize;
165   }
166
167   /**
168      Establece la instancia del mensaje asociada a este transporte.
169      \param inputMessage Instancia del mensaje a asociar.
170   */
171   void setInputMessage(Message* inputMessage) throw() { a_inputMessage = inputMessage; }
172
173 private:
174   static const int MinOverQuotaSize = 512;
175
176   int a_overQuotaSize;
177   Message* a_inputMessage;
178   bool a_enableTimeout;
179
180   static Message* nullInputMessage() throw(RuntimeException);
181 };
182
183 }
184 }
185
186 #endif