Updated license

[anna.git] / include / anna / comm / Communicator.hpp

// ANNA - Anna is Not Nothingness Anymore
//
// (c) Copyright 2005-2014 Eduardo Ramos Testillano & Francisco Ruiz Rayo
//
// https://bitbucket.org/testillano/anna
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
//
//     * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//     * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Authors: eduardo.ramos.testillano@gmail.com
//          cisco.tierra@gmail.com


#ifndef anna_comm_Communicator_hpp
#define anna_comm_Communicator_hpp

#include <vector>

#include <anna/config/defines.hpp>
#include <anna/core/DataBlock.hpp>
#include <anna/core/util/Recycler.hpp>
#include <anna/core/util/SortedVector.hpp>

#include <anna/app/Component.hpp>

#include <anna/comm/INetAddress.hpp>
#include <anna/comm/Socket.hpp>
#include <anna/comm/Status.hpp>

#include <anna/comm/internal/ConnectionRecover.hpp>

#include <anna/core/util/Millisecond.hpp>

namespace anna {

// MT
class ThreadManager;

namespace xml {
class Node;
}

namespace comm {

class Application;
class Transport;
class Message;
class ServerSocket;
class ClientSocket;
class LocalConnection;
class RemoteConnection;
class DatagramSocket;
class INetAddress;
class Handler;
class Server;
class Service;
class BinderSocket;
class ConnectionRecover;

namespace handler {
class LocalConnection;
class RemoteConnection;
class ClientSocket;
}

// ST
class Poll;

/**
   Clase que integra todos los elementos implicados en la recepcin y/o envio y tratamiento de mensajes
   de red.

   Los mensajes recibidos y/o enviados a la capa de transporte seran tratados por el protocolo asociado
   al socket cliente. Normalmente todos los socket clientes asociados a un comunicador tendran asociado
   un mismo tipo de protocolo. Ver Transport.

   Normalmente, y una vez que recibimos un mensaje (ver #eventReceiveMessage) aplicaremos algun codec (ver @ref Codec)
   para interpretar el contenido del mensaje, de forma analoga, para enviar un mensaje a la capa de transporte
   usando cualquier protocolo lo normal sera haber codificado cierta informacion usando algun codec.

   \warning Siempre que usemos un Communicator debemos establecer una clase Application heredada
   de comm::Application.
*/
class Communicator : public app::Component {
  struct SortByFileDescriptor {
    static int value(const Handler*) throw();
  };

  /**
   * Tamaño del búfer usado para leer los mensajes de la red.
   * Se puede establecer desde comm::Communicator::setReceivingChunkSize.
   */
  static Millisecond st_ReceivingChunkSize;

public:
  /**
   * Modo de aceptar peticiones en el caso de una arquitectura ST.
   * \warning Solo tiene efecto en caso de generar la libreria en modo ST.
   * \see Communicator
   */
  struct WorkMode {
    enum _v {
      /**
       * Un único proceso atiende todas las peticiones, el reparto de atención implementado asegura que todos
       * los clientes tendrán un tiempo de respuesta similar, el tratamiento de N peticiones que llegan simultáneamente
       * se realiza de forma secuencial. Es el modo usado hasta ahora en modo ST. Tiene la ventaja de ser el método que
       * origina código más simple y fácil de mantener.
       */
      Single,
      /**
       *  Cada cliente tiene su propia copia del servidor original que trata sus peticiones de forma particular.
       * De esta forma se podrían llegar a servir simultáneamente cada una de las peticiones de cada uno de los
       * clientes conectados al servidor. Puede ser una buena opción si tenemos en cuenta la relación entre el
       * rendimiento y la complejidad de desarrollo.
       *
       * Podria ser la mejor opcion para implementar un servidor de base de datos.
       *
       * \warning Solo puede usarse para implementar servidores finales, es decir, procesos que no requieran de la
       * respuesta de ningun otro proceso remoto para realizar su operacion.
       */
      Clone
    };
  };

  /**
   * Numero de mínimo milisegundos esperados para intentar la recuperacion de la conexion con los
   * servidores en caso de detectar algun error.
   */
  static const Millisecond MinRecoveryTime;

  /**
     Numero de milisegundos esperados para intentar la recuperacion de la conexion con los
     servidores en caso de detectar algun error.
  */
  static const Millisecond DefaultRecoveryTime;

  /**
   * Numero de mínimo milisegundos esperados para intentar la recuperacion de la conexion con los
   * servidores en caso de detectar algun error.
   */
  static const Millisecond MaxRecoveryTime;

  /**
   * Periodo de tiempo mínimo que estará intentando conectar con servidores cada vez que se cumpla el periodo de
   * comprobación de conexiones.
   */
  static const Millisecond MinTryingConnectionTime;

  /**
   * Periodo de tiempo usado por defectoque estará intentando conectar con servidores cada vez que se cumpla el
   * periodo de comprobación de conexiones.
   */
  static const Millisecond DefaultTryingConnectionTime;

  /**
   * Periodo de tiempo máximo que estará intentando conectar con servidores cada vez que se cumpla el periodo de
   * comprobación de conexiones.
   */
  static const Millisecond MaxTryingConnectionTime;

  /**
   * Tamaño mínimo de la cola de entrada de mensajes que se puede establecer.
   */
  static const int MinReceivingChunkSize = 2 * 1024;

  /**
   * Tamaño máximo de la cola de entrada de mensajes que se puede establecer.
   */
  static const int MaxReceivingChunkSize = 64 * 1024;

  /**
     Numero de milisegundos esperados para considerar que un cliente remoto ha abandonado
     la conexion.
  */
  static const Millisecond DefaultTimeout;

  /**
   * Tamaño máximo del búfer a tratar de forma ininterrumpida.
   */
  static const int DefaultChunkSize = 16 * 1024;

  typedef SortedVector <Handler, SortByFileDescriptor> Handlers; /**< Definicion para gestionar los controladores asociados a este comunicador */
  typedef Handlers::const_iterator const_handler_iterator; /**< Definicion para el iterador de controladores */
  typedef Handlers::iterator handler_iterator; /**< Definicion para el iterador de controladores */

  typedef std::vector <const Service*> Services; /**< Definicion para gestionar los servicios asociados a este comunicador */
  typedef Services::const_iterator const_service_iterator; /**< Definicion para el iterador de servicios */

  /**
     Constructor.
     \param acceptMode Modo en que se trata las peticiones.
  */
  Communicator(const WorkMode::_v acceptMode = WorkMode::Single);

  /**
   * Destructor
   */
  virtual ~Communicator();

  /**
     Devuelve el numero de segundos esperado para intentar recuperar las conexiones de los servidores
     con los que se han detectado errores de conexion.
     @return El numero de segundos esperado para intentar recuperar las conexiones de los servidores
     con los que se han detectado errores de conexion.
  */
  const Millisecond &getRecoveryTime() const throw() { return a_recoveryTime; }

  /**
     Devuelve el estado de este proceso con respecto al sistema de comunicaciones.
     \return El estado de este proceso con respecto al sistema de comunicaciones.
  */
  const Status& getStatus() const throw() { return a_status; }

  /**
     Devuelve el numero de milisegundos maximo que puede estar un manejador de conexion local
     sin recibir mensajes antes de ser cerrado por el nucleo.
     \return el numero de milisegundos maximo que puede estar un manejador de conexion local
     sin recibir mensajes antes de ser cerrado por el nucleo.
  */
  const Millisecond &getTimeout() const throw() { return a_timeout; }

  /**
   * Devuelve el modo de tratamiento de conexiones establecido en el constructor.
   */
  WorkMode::_v getWorkMode() const throw() { return a_workMode; }

  /**
     Devuelve \em true si este comunicador esta atendiendo peticiones como servidor o \em false en otro
     caso.
     @return \em true si este comunicador esta atendiendo peticiones como servidor o \em false en otro
     caso.
  */
  bool isServing() const throw() { return a_isServing; }

  /**
     Devuelve el estado del indicador de peticion de parada.
     \return el estado del indicador de peticion de parada.
  */
  bool hasRequestedStop() const throw() { return a_requestedStop; }

  /**
   * Informa al comunicador de que hay algún socket que ha solicitado el cierre de la conexión.
   */
  void notifyPendingClose() throw() { a_pendingClose = true; }

  /**
     Establece el numero de milisegundos esperado para intentar recuperar las conexiones de los servidores
     con los que se han detectado errores de conexion.

     @param recoveryTime numero de milisegundos esperado para intentar recuperar las conexiones de los
     servidores con los que se han detectado errores de conexion.

     \warning el valor indicado deberá estar entre #MinRecoveryTime y #MaxRecoveryTime
  */
  void setRecoveryTime(const Millisecond &recoveryTime) throw(RuntimeException);

  /**
     Establece el numero de milisegundos empleados en intentar conectar con los servidores caídos cada
     vez que se cumple el periodo de recuperación y hay servidores caídos.

     @param tryingConnectionTime numero de milisegundos empleados en intentar recuperar las conexiones
     de los servidores con los que se han detectado errores de conexion.

     \warning el valor indicado deberá estar entre #MinTryingConnectionTime y #MaxTryingConnectionTime
  */
  void setTryingConnectionTime(const Millisecond &tryingConnectionTime) throw(RuntimeException);

  /**
   * Devuelve el numero de milisegundos empleados en intentar conectar con los servidores caídos.
   */
  const Millisecond &getTryingConnectionTime() const throw() { return a_tryingConnectionTime; }

  /**
   * Establece el tamaño del bloque de memoria usado para procesar los mensajes entrantes. Todos
   * los mensajes completos contenidos en el chunk se procesarán de forma ininterrumpida.
   * \param receivingChunkSize Número de bytes a leer/procesar de forma ininterrumpida.
   *
   * \warning el valor indicado deberá estar entre #MinReceivingChunkSize y #MaxReceivingChunkSize
   * \warning Experimentalmente se ha comprobado que los mejores rendimientos se obtiene cuando
   * este valor y el MaxPendingBytes del control de congestión tiene valores cercanos, así que
   * cuando se cambia este valor también se invocará a CongestionController::setMaxPendingBytes para
   * establecer este mismo valor.
   */
  static void setReceivingChunkSize(const int receivingChunkSize) throw(RuntimeException);

  /**
   * Obtiene el tamaño máximo del bloque de memoria a procesar de forma ininterrumpida.
   * \return el tamaño máximo del bloque de memoria a procesar de forma ininterrumpida.
   */
  static int getReceivingChunkSize() throw() { return st_ReceivingChunkSize; }

  /**
     Establece el numero de milisegundos maximo que puede estar un manejador de conexion local
     sin recibir mensajes antes de ser cerrado por el nucleo.
     \param timeout Numero de milisegundos maximo sin recibir mensajes.
  */
  void setTimeout(const Millisecond & timeout) throw() { a_timeout = timeout; }

  /**
   * Establece el nivel de congestión global a partir del cual un servidor no aceptará nuevas conexiones. Su valor
   * por defecto será comm::CongestionController::MaxLevel.
   *
   * \param levelOfDenialService Nivel de congestión global a partir del cual no se permitirán nuevas conexiones.
   *
   * \warning Debe estar entre [comm::CongestionController::MaxLevel - 2, comm::CongestionController::MaxLevel].
   */
  void setLevelOfDenialService(const int levelOfDenialService) throw(RuntimeException);

  /**
   * Devuelve el nivel de congestión a partir del cual un servidor no aceptará nuevas conexiones.
   * \return el nivel de congestión a partir del cual un servidor no aceptará nuevas conexiones.
   */
  int getLevelOfDenialService() const throw() { return a_levelOfDenialService; }

  /**
     Registra un servidor de socket a la lista de peticiones por las que atiende peticiones este
     Communicator. Un Communicator puede atender peticiones por un numero indeterminado de direcciones
     lo que nos permite disear facilmente sistemas tolerantes a fallos.

     \param serverSocket Servidor de socket por el que vamos a atender el establecimiento de conexiones
     una vez que invoquemos al Metodo #accept.
  */
  void attach(ServerSocket* serverSocket) throw(RuntimeException);

  /**
     Registra una conexion Local entre alguno de los ServerSocket definidos en nuestra aplicacion
     y algun cliente remoto que solicita la conexion.

     Antes de pasar a gestionar esta conexion debera de haber sido acceptada en el metodo
     #eventAcceptConnection (a no ser que re-escribamos su comportamiento aceptara conexiones
     de cualquier cliente).

     \param localConnection Instancia de la conexion local que vamos a controlar.

     \warning Exclusivamente uso interno
  */
  void attach(LocalConnection* localConnection) throw(RuntimeException);

  /**
     Establece la conexion entre el comunicador y un ClientSocket recibido como parametro.
     El socket recibido se inicializa se fuera necesario.

     \param clientSocket Instancia del socket que vamos a controlar.
  */
  void attach(ClientSocket* clientSocket) throw(RuntimeException);

  /**
     Establece la conexion entre el comunicador y un DatagramSocket recibido como parametro.
     El socket recibido se inicializa se fuera necesario.

     \param datagramSocket Instancia del socket que vamos a controlar.
  */
  void attach(DatagramSocket* datagramSocket) throw(RuntimeException);

  /**
     Conecta un conector externo a este comunicador.
     \param handler Controlador de comunicaciones externas.
     \warning Debe de haber sido creado como de tipo Handler::Type::Custom.
  */
  void attach(Handler* handler) throw(RuntimeException);

  /**
     Conecta un servicio de reparto de comunicaciones con este comunicador. El estado de
     disponibilidad/indisponibilidad de este comunicador estara definido en base a la
     disponibilidad de todos los servicios definidos como criticos.
     \param service Instancia del servicio.
     \warning Todos los servicios registrados como criticos deberian estar asociados al comunicador.
  */
  void attach(Service* service) throw(RuntimeException);

  /**
     Desconecta el ServerSocket que fue previamente conectado con #attach
     \param serverSocket Instancia del socket que vamos a desconectar.
     \warning Este metodo es invocado automaticamente desde el nucleo de anna.comm y no deberia
     ser usado por el programador final.
  */
  void detach(ServerSocket* serverSocket) throw();

  /**
     Desconecta el ClientSocket que fue previamente conectado con #attach
     \param clientSocket Instancia del socket que vamos a desconectar.
     \warning Este metodo es invocado automaticamente desde el nucleo de ANNA.comm y no deberia
     ser usado por el programador final.
  */
  void detach(ClientSocket* clientSocket) throw();

  /**
     Desconecta el conector externo de este comunicador. Supone que todas las operaciones
     adicionales necesarias para liberar los recursos de este fichero seran realizadas
     externamente.

     \param handler Controlador de comunicaciones externas.

     \warning Exclusivamente uso interno
  */
  void detach(Handler* handler) throw();

  /**
     Devuelve el manejador asociado al ClientSocket recibido como parametro.
     \param clientSocket Socket cliente del que queremos obtener en handler.
     \return El manejador asociado al socket recibido como parametro. Puede ser NULL.
  */
  const Handler* getHandler(const ClientSocket& clientSocket) throw(RuntimeException);

  /**
      El thread que invoca a este Metodo entra en un proceso continuo de comprobacin/recepcin
      de mensajes, todos los eventos que pueden afectar al comportamiento de nuestro comunicador como son
      aceptacin y cierre de conexiones, caidas, recepcin de mensajes, etc, etc se notifican a
      traves de los Metodos manejadores de eventos de esta misma clase.
      El thread saldra de este bucle tras la invocacion del Metodo #requestStop.
   */
  void accept() throw(RuntimeException);

  /**
     Solicita la parada de este comunicador.
  */
  void requestStop() throw();

  /**
     Devuelve \em true si el ClientSocket recibido como parametro sigue siendo valido o \em false
     en caso de que haya dejado de ser valido debido al cierre del extremo remoto, por ejemplo.

     Si el ClientSocket recibido es NULL siempre devolvera \em false.

     \return \em true si el ClientSocket recibido como parametro sigue siendo valido o \em false
     en caso de que haya dejado de ser valido debido al cierre del extremo remoto, por ejemplo.
  */
  bool isUsable(const ClientSocket* clientSocket) throw();

  /**
     Devuelve el numero handlers activos.
     \return el numero handlers activos.
  */
  int handler_size() const throw() { return a_handlers.size(); }

  /**
     Devuelve un iterador que apunta el primer controlador.
     \return un iterador que apunta el primer controlador.
  */
  handler_iterator handler_begin() throw() { return a_handlers.begin(); }

  /**
     Devuelve un iterador que apunta al final de la lista de controladores.
     \return un iterador que apunta al final de la lista de controladores.
  */
  handler_iterator handler_end() throw() { return a_handlers.end(); }

  /**
     Devuelve un iterador que apunta el primer controlador.
     \return un iterador que apunta el primer controlador.
  */
  const_handler_iterator handler_begin() const throw() { return a_handlers.begin(); }

  /**
     Devuelve un iterador que apunta al final de la lista de controladores.
     \return un iterador que apunta al final de la lista de controladores.
  */
  const_handler_iterator handler_end() const throw() { return a_handlers.end(); }

  /**
     Devuelve un iterador que apunta el primer servicio.
     \return un iterador que apunta el primer service.
  */
  const_service_iterator service_begin() const throw() { return a_services.begin(); }

  /**
     Devuelve un iterador que apunta al final de la lista de servicios.
     \return un iterador que apunta al final de la lista de servicios.
  */
  const_service_iterator service_end() const throw() { return a_services.end(); }

  /**
     Metodo manejador de evento que permite ajustar el funcionamiento de nuestro comunicador ante
     un evento generado por el propio programador.

     Sera invocado por algun Metodo del programador con el objetivo de actuar sobre su comunicador
     en una situacin indeterminada.

     La interpretacin del identificador y el contenido de este contexto sera problema exclusivo
     del programador ya que ANNA.comm no impone ninguna regla ni realiza ningn tipo de proceso
     adicional con estos datos.

     @param id Identifica el evento generado.
     @param context Contexto asociado al evento que ha generado el usuario.

     \warning Este Metodo no debera generar ningn tipo de excepcin.
  */
  virtual void eventUser(const char* id, const void* context) throw() {;}

  /**
     Metodo manejador de evento que permite ajustar el funcionamiento de nuestro comunicador cuando
     el nucleo de ANNA.comm notifica la perdida de conexion con la direccion IP indicada.

     \param address Interfaz de red que ha dejado de estar disponible.

     \warning
     \li La forma en que detectara la caida del interfaz de red no esta dentro del ambito
     del problema de ANNA.comm debera haber una capa superior que se encargue de comprobar las
     interfaces.
     \li El nucleo de ANNA.comm necesita conocer este evento por lo que cualquier implementacin
     debera invocar al Metodo eventBreakAddress de su clase base.
  */
  virtual void eventBreakAddress(const in_addr_t& address) throw();

  /**
     Metodo manejador de evento que permite ajustar el funcionamiento de nuestro comunicador cuando
     el nucleo de ANNA.comm notifica la recuperacin de conexion con la direccion IP indicada.

     \param address Interfaz de red que ha vuelto a estar disponible.

     \warning
     \li La forma en que detectara la recuperacin del interfaz de red no esta dentro del ambito
     del problema de ANNA.comm debera haber una capa superior que se encargue de comprobar las
     interfaces.
     \li El nucleo de ANNA.comm necesita conocer este evento por lo que cualquier implementacin
     debera invocar al Metodo eventRecoverAddress de su clase base.
  */
  virtual void eventRecoverAddress(const in_addr_t& address) throw();

  /**
     Metodo manejador de evento que permite ajustar el funcionamiento de nuestro comunicador cuando
     el nucleo de ANNA.comm notifica que ha detectado una peticion de conexion desde un
     proceso remoto a un ServerSocket asociado a este comunicador.
     Cualquier re-implementacion de este metodo debe invocar al metodo de la clase base y
     devolver \em false en caso de que este lo devuelva.

     @param clientSocket Socket cliente que solicita acceso.

     \return \em true si la conexion es acceptada a \em false en otro caso, en cuyo caso se liberaran
     automaticamente todos los recursos asociados a la peticion de conexion.

     \warning Desde ANNA.comm 1.11.18 se mide el nivel de carga del proceso y si se evalúa como
     congestionado no permitirá aceptar la nueva conexión.
  */
  virtual bool eventAcceptConnection(const ClientSocket& clientSocket) throw(RuntimeException);

  /**
      Metodo manejador de evento que permite ajustar el funcionamiento de nuestro comunicador cuando
      el nucleo de ANNA.comm notifica la creacion de una nueva conexion con el proceso servidor
      recibido como parametro.

      En la mayoria de los casos no sera necesario indicar ninguna accion ya que ANNA.comm realiza
      todas las operaciones necesarias.

      \warning Cualquier reimplementacion de este metodo debe comenzar invocando al metodo original de la
      clase Communicator de la que herede nuestra clase.

      @param server Proceso servidor con el que hemos establecido la conexion.

      \see Host::createServer
   */
  virtual void eventCreateConnection(const Server* server) throw();

  /**
      Metodo manejador de evento que permite ajustar el funcionamiento de nuestro comunicador cuando
      el nucleo de ANNA.comm notifica la creacion de una nueva conexion con el servicio de reparto
      recibido como parametro.

      En la mayoria de los casos no sera necesario indicar ninguna accion ya que ANNA.comm realiza
      todas las operaciones necesarias.

      \warning  Cualquier reimplementacion de este metodo debe comenzar invocando al metodo original de la
      clase Communicator de la que herede nuestra clase.

      @param service Servicio con el que hemos establecido la conexion.

      \see Host::createServer
   */
  virtual void eventCreateConnection(const Service* service) throw();

  /**
     Establece las acciones a realizar cuando la clase Communicator detecta la llegada de un
     mensaje completo analizado con el protocolo indicado.

     Se invocara desde el Metodo #accept cuando se detecta la llegada de un mensaje.

     En entorno MT todos los threads actuaran sobre la unica instancia del comm::Communicator
     lo que restara eficacia debido al bajo nivel de paralelismo.

     @param clientSocket Socket cliente por el que ha llegado el mensaje.
     @param message Ultimo mensaje recibido. El bloque de datos recibido ya ha sido
     decodificado aplicando las reglas establecidas por la capa de transporte asociado
     al ClientSocket por el que llega el mensaje.

     \warning Para ANNA.comm version 1.5.2 y posteriores se deberian usar el sistema de
     receiveres (anna::comm::Receiver) que ofrece mayor rendimiento y facilita la programacion
     en entorno MT.
  */
  virtual void eventReceiveMessage(ClientSocket& clientSocket, const Message& message)
  throw(RuntimeException) { ; }

  /**
     Establece las acciones a realizar cuando el nucleo de ANNA.comm notifica que ha
     cerrado un anna::comm::ClientSocket debido a un consumo excesivo de memoria.
     \param clientSocket Socket cliente que va a ser cerrado por el nucleo de ANNA.comm.
  */
  virtual void eventOverQuota(const ClientSocket& clientSocket) throw() {;}

  /**
     Establece las acciones a realizar cuando el núcleo de ANNA.comm notifica que ha
     cerrado un anna::comm::ClientSocket debido a que ha recibido un mensaje que no
     ha sido analizado correctamente.
     \param clientSocket Socket cliente que va a ser cerrado por el nucleo de ANNA.comm.
  */
  virtual void eventDiscardConnection(const ClientSocket& clientSocket) throw() {;}

  /**
   * Método manejador invocado cuando un client socket que tiene activado el indicador de ignorar los
   * mensajes entrantes recibe un mensaje.
   * \param clientSocket ClientSocket por el que se recibe el mensaje.
   * \param burst Bloque de datos que contiene la trama recibida.
   */
  virtual void eventIgnoreBurst(const ClientSocket& clientSocket, const DataBlock& burst) throw() {;}

  /**
     Devuelve una cadena con la informacion mas relevante de esta instancia.
     \return Una cadena con la informacion mas relevante de esta instancia.
  */
  std::string asString() const throw();

  /**
     Devuelve un documento XML con la informacion mas relevante de esta instancia.
     \param parent Nodo XML del que colgar la informacion referente a esta instancia.
     \return Un documento XML con la informacion mas relevante de esta instancia.
  */
  virtual xml::Node* asXML(xml::Node* parent) const throw();

  /**
     Devuelve el controlador apuntado por el iterador recibido.
     \param ii Iterador con el que estamos recorriendo los controladores.
     \return el controlador apuntado por el iterador recibido.
  */
  static Handler* handler(handler_iterator& ii) throw() { return Handlers::data(ii); }

  /**
     Devuelve el controlador apuntado por el iterador recibido.
     \param ii Iterador con el que estamos recorriendo los controladores.
     \return el controlador apuntado por el iterador recibido.
  */
  static const Handler* handler(const_handler_iterator& ii) throw() { return Handlers::data(ii); }

  /**
     Devuelve el servicio apuntado por el iterador recibido.
     \param ii Iterador con el que estamos recorriendo los servicios.
     \return el servicio apuntado por el iterador recibido.
  */
  static const Service* service(const_service_iterator& ii) throw() { return *ii; }

  /**
     Devuelve la cadena por la que podemos buscar el componente.
     \return La cadena por la que podemos buscar el componente.
     \see Application::find
  */
  static const char* getClassName() { return "anna::comm::Communicator"; }

protected:
  /**
     Metodo manejador de evento que permite ajustar el funcionamiento de nuestro comunicador cuando
     el nucleo de ANNA.comm notifica la perdida de conexion con un servidor remoto.

     En la mayoria de los casos no sera necesario indicar ninguna accion ya que ANNA.comm realiza
     todas las operaciones necesarias.

     @param clientSocket Socket cliente asociado a esta rotura de conexion.

     \warning despues de llamar a este Metodo el clientSocket pasado como parametro se liberara por lo
     que despues de este Metodo esta instancia no debera utilizarse.
     \warning Estado MT: \code [Tx] -> Communicator \endcode
  */
  virtual void eventBreakConnection(const ClientSocket& clientSocket) throw() {;}

  /**
     Metodo manejador de evento que permite ajustar el funcionamiento de nuestro comunicador cuando
     el nucleo de ANNA.comm notifica la perdida de conexion de una conexion generada por un server socket.

     En la mayoria de los casos no sera necesario indicar ninguna accion ya que ANNA.comm realiza
     todas las operaciones necesarias.

     @param clientSocket Socket cliente asociado a esta rotura de conexion.
  */
  virtual void eventBreakLocalConnection(const ClientSocket& clientSocket) throw() {;}


  /**
     Metodo manejador de evento que permite ajustar el funcionamiento de nuestro comunicador cuando
     el nucleo de ANNA.comm notifica la perdida de conexion con el proceso servidor recibido como
     parametro.

     Se invocara desde #accept(ServerSocket&) cuando no se detecta la rotura de conexion con un
     socket asociado a uno de nuestros servidores.

     En la mayoria de los casos no sera necesario indicar ninguna accion ya que ANNA.comm realiza
     todas las operaciones necesarias.

     Las acciones realizadas por este metodo incluyen:
     \li Cierre del socket asociado al proceso servidor cuya conexion ha caido.
     \li Reorganizacion del sistema de reparto de carga para que marque el proceso servidor como no disponible.
     \li Activar los sistemas de recuperacion de conexion en el caso de que el servidor que ha caido
     vuelva a estar disponible.

     \warning Cualquier reimplementacion de este metodo debe comenzar invocando al metodo original de la
     clase Communicator de la que herede nuestra clase.
     \warning Estado MT: \code [Tx] -> Communicator \endcode

     @param server Proceso servidor con el que hemos perdido la conexion.
  */
  virtual void eventBreakConnection(const Server* server) throw();

  /**
     Metodo manejador de evento que permite ajustar el funcionamiento de nuestro comunicador
     cuando el nucleo de anna.comm notifica la perdida de conexion con todos los procesos
     asociados al servicio recibido como parametro.

     \param service Servicio que ha dejado de estar disponible.
     \warning Estado MT: \code [Tx] -> Communicator \endcode
  */
  virtual void eventBreakConnection(const Service* service) throw();

  /**
     Establecer la configuracin de este comunicador. El cargador de configuracin se encarga de establecer
     los ServerSocket por los que este comunicador va a atender peticiones y/o los procesos servidores
     remotos con los que tenemos que establecer el canal de comunicaciones.

     \warning Este Metodo debe invocarse desde las clases heredadas.
  */
  virtual void do_initialize() throw(RuntimeException) {;}

  /**
     Solicita la parada de este comunicador. Se reimplementa para mantener el interfaz de la clase
     Component de la que hereda este Communicator.
  */
  void do_stop() throw() { requestStop(); }

  /**
     Establece el estado de este proceso con respecto al sistema de comunicaciones
     @param status Estado del sistema de comunicaciones que deseamos establecer.
  */
  virtual void setStatus(const Status& status) throw();

  /**
     Establece la conexion entre el comunicador y un socket dedicado a la comparticion de una
     determinada direccion IP:puerto.

     \param binderSocket Define un socket por el que tratar las peticiones de comparticion
     de una determinada direccion IP:puerto.

     \internal
  */
  void attach(BinderSocket* binderSocket) throw(RuntimeException);

  /**
     Desconecta el BinderSocket que fue previamente conectado con attach(BinderSocket*).
     \param binderSocket Instancia del BinderSocket a desconectar.
     \warning Exclusivamente uso interno
  */
  void detach(BinderSocket* binderSocket) throw();

  /**
     Metodo manejador de evento que permite ajustar el funcionamiento de nuestro comunicador cuando
     el nucleo de ANNA.comm notifica que este comunicador esta preparado para comenzar a
     aceptar y/o enviar mensajes.

     Se invocara desde el metodo #accept inmediatamente antes de comenzar a
     comprobar la llegada de mensajes.

     En la mayoria de los casos no sera necesario indicar ninguna accion ya que ANNA.comm realiza
     todas las operaciones necesarias.
  */
  virtual void eventStartup() throw(RuntimeException) {;}

  /**
     Metodo manejador de evento que permite ajustar el funcionamiento de nuestro comunicador cuando
     el nucleo de ANNA.comm notifica que este va a dejar de atender peticiones.

     En la mayoria de los casos no sera necesario indicar ninguna accion ya que ANNA.comm realiza
     todas las operaciones necesarias.
  */
  virtual void eventShutdown() throw();

private:
  const WorkMode::_v a_workMode;
  bool a_isServing;
  bool a_requestedStop;
  Handlers a_handlers;
  Millisecond a_recoveryTime;
  Status a_status;
  Services a_services;
  Millisecond a_timeout;
  comm::Handler* a_mainHandler;
  ConnectionRecover* a_connectionRecover;
  bool a_pendingClose;
  Millisecond a_tryingConnectionTime;
  int a_levelOfDenialService;

  // ST
  Poll* a_poll;
  Handlers a_timedouts;
  void singlethreadedAccept() throw(RuntimeException);

  // MT
  ThreadManager* a_threadManager;
  void multithreadedAccept() throw(RuntimeException);

  ConnectionRecover* getConnectionRecover() throw() { return a_connectionRecover; }

  void attach(RemoteConnection* remoteConnection) throw(RuntimeException);

  void insert(Handler*) throw(RuntimeException);
  Handler* find(const int fd) throw() { return a_handlers.find(fd); }

  // Reimplementado de app::Component
  void do_cloneParent() throw(RuntimeException);
  void do_cloneChild() throw();

  friend class Handler;

  friend class Server;
  // attach (RemoteConnection)

  friend class handler::RemoteConnection;
  // getConnectionRecover, eventBreakConnection

  friend class handler::ClientSocket;
  // eventBreakConnection

  // EDU
  friend class handler::LocalConnection;
  // eventBreakLocalConnection
};

}
}

#endif