1 // ANNA - Anna is Not 'N' Anymore
3 // (c) Copyright 2005-2014 Eduardo Ramos Testillano & Francisco Ruiz Rayo
5 // https://bitbucket.org/testillano/anna
7 // Redistribution and use in source and binary forms, with or without
8 // modification, are permitted provided that the following conditions
11 // * Redistributions of source code must retain the above copyright
12 // notice, this list of conditions and the following disclaimer.
13 // * Redistributions in binary form must reproduce the above
14 // copyright notice, this list of conditions and the following disclaimer
15 // in the documentation and/or other materials provided with the
17 // * Neither the name of Google Inc. nor the names of its
18 // contributors may be used to endorse or promote products derived from
19 // this software without specific prior written permission.
21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 // Authors: eduardo.ramos.testillano@gmail.com
34 // cisco.tierra@gmail.com
37 #ifndef anna_comm_Transport_hpp
38 #define anna_comm_Transport_hpp
40 #include <anna/core/RuntimeException.hpp>
41 #include <anna/core/DataBlock.hpp>
51 Clase generica para definir la capa de transporte de cualquier protocolo de comunicaciones.
53 Estructura basica que nos permite ordenar el proceso de analizar un mensaje recibido desde
54 cualquier medio. El protocolo conoce los detalles semanticos del mensaje que ha recibido,
55 es decir, conoce como interpretar cada uno de los bytes que componen el mensaje, cuando un
56 mensaje esta completo.
58 El principal problema de cualquier protocolo externo a la hora de recibir es conocer cual
59 es el tamao de un determinado mensaje.
61 Todos los metodos que se deberian reescribir en las clases heredadas se invocan desde un
62 metodo MT-safe que se encarga de evitar accesos simultaneos desde varios threads, lo cual,
63 evita que tengamos que preocuparnos por establecer secciones criticas en cada uno de los
66 \warning Los supuestos bajo los que se diseñó éste protocolo facilitan el desarrollo de
67 clases que ofrecen un gran rendimiento, pero imposibilitan el desarrollo del sistema de
68 re-sincronización en caso de que alguno de los mensajes no cumpla los supuestos.
69 Es decir, si nos llega un mensaje errneo nuestro proceso no sera capaz de volver a
70 sincronizarse nunca mas.
75 Numero de bytes maximo que puede mantener cada ClientSocket sin identificar
76 un mensaje propio del protocolo.
79 static const int DefaultOverQuotaSize = 2048;
82 static const int DefaultOverQuotaSize = 8192;
86 Devuelve \em true si la capa de transporte tiene activado el sistema de control
89 bool enableTimeout() const throw() { return a_enableTimeout; }
92 Activa el control de temporización para los ClientSocket que fueron creados
93 usando esta capa de transporte. Los ClientSocket creados usando esta capa
94 de transporte se cerraran automaticamente si no se detecta actividad en
95 un determinado periodo de tiempo.
96 \see Communicator::setTimeout.
98 void activateTimeout() throw() { a_enableTimeout = true; }
101 Activa el control de temporizacion para los ClientSocket que fueron creados
102 usando esta capa de transporte.
104 void deactivateTimeout() throw() { a_enableTimeout = false; }
107 Devuelve el mensaje de entrada asociado.
108 \return La instancia del mensaje de entrada asociado.
109 \warning Exclusivamente de uso interno.
111 Message* getInputMessage() throw(RuntimeException) {
112 return (a_inputMessage == NULL) ? nullInputMessage() : a_inputMessage;
116 Devuevel el numero bytes que reserva este protocolo para el buffer de memoria intermedia.
117 \return el numero bytes que reserva este protocolo para el buffer de memoria intermedia.
119 int getOverQuotaSize() const throw() { return a_overQuotaSize; }
122 Establece el numero de bytes que puede mantener este procotolo para cada uno de los
123 ClientSocket sin que se halla identificado el mensaje como propio del protocolo.
124 Si el numero de bytes guardados en la memoria intermedia sobrepasa este numero de
125 bytes se cerrara la conexion con el ClientSocket.
127 \param overQuotaSize Numero de maximo de bytes que podemos mantener en la memoria intermedia.
129 void setOverQuotaSize(const int overQuotaSize) throw() { a_overQuotaSize = (overQuotaSize >= MinOverQuotaSize) ? overQuotaSize : MinOverQuotaSize; }
132 Debe calcular el tamao previsto del mensaje actual.
134 Si se detecta una anomalia irrecuperable en el mensaje debe devolver una excepcion
135 para indicar el error.
137 @param dataBlock Bloque con la parte del mensaje disponible hasta el momento.
139 @return Si con la informacion disponible no puede establecer la longitud del
140 mensaje devolvera -1 en otro caso devolvera la longitud prevista del mensaje.
143 Si el protocolo de transporte implementado detecta problemas al calcular la
144 longitud del mensaje recibido y lanza una excepcion en este metodo el ClientSocket
145 activara los sistemas de recuperacion, si es posible.
147 virtual int calculeSize(const DataBlock& dataBlock) throw(RuntimeException) = 0;
150 Debe establecer el modo en que el protocolo va a verificar que el mensaje obtenido
151 coincide con el patrn esperado e interpretar el contenido del mensaje.
152 Este metodo slo se invoca cuando se considera que el mensaje actual esta completo.
154 Si se detecta una anomalia irrecuperable en el mensaje debe devolver una excepcion
155 para indicar el error.
157 @param message Bloque con lo que hasta el momento se considera el ltimo mensaje recibido
160 \return Un bloque de memoria que contiene el mensaje recibido codificado segn las reglas del
161 protocolo este protocolo de transporte
163 virtual const Message* decode(const DataBlock& message) throw(RuntimeException) = 0;
166 Debe establecer la forma en el protocolo va a preparar el envio a la capa de transporte.
168 @param message Bloque de datos con la codificacin obtenida mediante cualquiera de los
169 codec disponibles (Ver @ref Codec).
171 @return El bloque de memoria con el mensaje que sera enviado a la capa de transporte.
173 \warning De no indicarse ninguna otra implementacin devolvera el mensaje tal y como
176 virtual const DataBlock& code(Message& message) throw(RuntimeException) = 0;
179 Metodo que inicializa el estado de esta capa de transporte. Sera invocado automaticamente por el
182 virtual void clear() throw() { a_forCode.clear(); }
185 DataBlock a_forCode; /**< Bloque de memoria usado para guardar el contenido de la codificacion */
189 \param autoSynchronize Indica si el el protocolo instancia permite la sincronizacion automatica.
190 \param overQuotaSize Longitud maxima que puede contener el buffer intermedio antes de cerrar el socket
191 por considerar que no puede sincronizarlo.
194 a_inputMessage(NULL),
196 a_enableTimeout(false) {
197 a_overQuotaSize = DefaultOverQuotaSize;
201 Establece la instancia del mensaje asociada a este transporte.
202 \param inputMessage Instancia del mensaje a asociar.
204 void setInputMessage(Message* inputMessage) throw() { a_inputMessage = inputMessage; }
207 static const int MinOverQuotaSize = 512;
210 Message* a_inputMessage;
211 bool a_enableTimeout;
213 static Message* nullInputMessage() throw(RuntimeException);