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