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
  46   static const int MinOverQuotaSize = 512;
  47
  48   int a_overQuotaSize;
  49   Message* a_inputMessage;
  50
  51   static Message* nullInputMessage() throw(RuntimeException);
  52
  53 public:
  54   /**
  55     Maximum number of bytes kept by each ClientSocket without identifying
  56     a message for the own protocol.
  57   */
  58   WHEN_SINGLETHREAD(
  59     static const int DefaultOverQuotaSize = 2048;
  60   )
  61   WHEN_MULTITHREAD(
  62     static const int DefaultOverQuotaSize = 8192;
  63   )
  64
  65   /**
  66     Returns true if the transport layer has a timming control system activated.
  67   */
  68   bool enableTimeout() const throw() { return a_enableTimeout; }
  69
  70   /**
  71     Activates the timming control system for the ClientSocket which were created
  72     through this transport layer. They will be automatically closed if no activity
  73     is detected in a time interval.
  74     \see Communicator::setTimeout.
  75   */
  76   void activateTimeout() throw() { a_enableTimeout = true; }
  77
  78   /**
  79     Deactivates the timming control system for the ClientSocket which were created
  80     through this transport layer.
  81   */
  82   void deactivateTimeout() throw() { a_enableTimeout = false; }
  83
  84
  85   // Internal use: returns associated input message
  86   Message* getInputMessage() throw(RuntimeException) {
  87     return (a_inputMessage == NULL) ? nullInputMessage() : a_inputMessage;
  88   }
  89
  90   /**
  91     Returns the number of bytes reserved by this protocol for the intermediate buffer.
  92     @return number of bytes reserved by this protocol for the intermediate buffer.
  93   */
  94   int getOverQuotaSize() const throw() { return a_overQuotaSize; }
  95
  96   /**
  97     Establece el numero de bytes que puede mantener este procotolo para cada uno de los
  98     ClientSocket sin que se halla identificado el mensaje como propio del protocolo.
  99     Si el numero de bytes guardados en la memoria intermedia sobrepasa este numero de
 100     bytes se cerrara la conexion con el ClientSocket.
 101
 102     \param overQuotaSize Numero de maximo de bytes que podemos mantener en la memoria intermedia.
 103   */
 104   void setOverQuotaSize(const int overQuotaSize) throw() { a_overQuotaSize = (overQuotaSize >= MinOverQuotaSize) ? overQuotaSize : MinOverQuotaSize; }
 105
 106   /**
 107      Debe calcular el tamao previsto del mensaje actual.
 108
 109      Si se detecta una anomalia irrecuperable en el mensaje debe devolver una excepcion
 110      para indicar el error.
 111
 112      @param dataBlock Bloque con la parte del mensaje disponible hasta el momento.
 113
 114      @return Si con la informacion disponible no puede establecer la longitud del
 115      mensaje devolvera -1 en otro caso devolvera la longitud prevista del mensaje.
 116
 117      \warning
 118         Si el protocolo de transporte implementado detecta problemas al calcular la
 119         longitud del mensaje recibido y lanza una excepcion en este metodo el ClientSocket
 120         activara los sistemas de recuperacion, si es posible.
 121   */
 122   virtual int calculeSize(const DataBlock& dataBlock) throw(RuntimeException) = 0;
 123
 124   /**
 125      Debe establecer el modo en que el protocolo va a verificar que el mensaje obtenido
 126      coincide con el patrn esperado e interpretar el contenido del mensaje.
 127      Este metodo slo se invoca cuando se considera que el mensaje actual esta completo.
 128
 129      Si se detecta una anomalia irrecuperable en el mensaje debe devolver una excepcion
 130      para indicar el error.
 131
 132      @param message Bloque con lo que hasta el momento se considera el ltimo mensaje recibido
 133      por completo.
 134
 135      \return Un bloque de memoria que contiene el mensaje recibido codificado segn las reglas del
 136      protocolo este protocolo de transporte
 137   */
 138   virtual const Message* decode(const DataBlock& message) throw(RuntimeException) = 0;
 139
 140   /**
 141      Debe establecer la forma en el protocolo va a preparar el envio a la capa de transporte.
 142
 143      @param message Bloque de datos con la codificacin obtenida mediante cualquiera de los
 144      codec disponibles (Ver @ref Codec).
 145
 146      @return El bloque de memoria con el mensaje que sera enviado a la capa de transporte.
 147
 148      \warning De no indicarse ninguna otra implementacin devolvera el mensaje tal y como
 149      sea recibido.
 150   */
 151   virtual const DataBlock& code(Message& message) throw(RuntimeException) = 0;
 152
 153   /**
 154      Metodo que inicializa el estado de esta capa de transporte. Sera invocado automaticamente por el
 155      nucleo anna.comm.
 156   */
 157   virtual void clear() throw() { a_forCode.clear(); }
 158
 159 protected:
 160   DataBlock a_forCode; /**< Bloque de memoria usado para guardar el contenido de la codificacion */
 161
 162   /**
 163      Constructor.
 164      \param autoSynchronize Indica si el el protocolo instancia permite la sincronizacion automatica.
 165      \param overQuotaSize Longitud maxima que puede contener el buffer intermedio antes de cerrar el socket
 166       por considerar que no puede sincronizarlo.
 167   */
 168   Transport() :
 169     a_inputMessage(NULL),
 170     a_forCode(true),
 171     a_enableTimeout(false) {
 172     a_overQuotaSize = DefaultOverQuotaSize;
 173   }
 174
 175   /**
 176      Establece la instancia del mensaje asociada a este transporte.
 177      \param inputMessage Instancia del mensaje a asociar.
 178   */
 179   void setInputMessage(Message* inputMessage) throw() { a_inputMessage = inputMessage; }
 180
 181 private:
 182
 183   bool a_enableTimeout;
 184 };
 185
 186 }
 187 }
 188
 189 #endif