include/anna/diameter.comm/Engine.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_diameter_comm_Engine_hpp
  10 #define anna_diameter_comm_Engine_hpp
  11
  12
  13 // STL
  14 #include <map>
  15 #include <string>
  16 #include <algorithm>
  17
  18 #include <anna/app/Component.hpp>
  19 #include <anna/core/util/Recycler.hpp>
  20
  21 #include <anna/diameter.comm/Server.hpp>
  22 #include <anna/diameter.comm/ServerSession.hpp>
  23 #include <anna/config/defines.hpp>
  24 #include <anna/diameter.comm/ClientSession.hpp>
  25 #include <anna/diameter.comm/ServerSession.hpp>
  26
  27 // Standard
  28 #include <time.h>
  29
  30
  31 //------------------------------------------------------------------------------
  32 //---------------------------------------------------------------------- #define
  33 //------------------------------------------------------------------------------
  34
  35 namespace anna {
  36 class DataBlock;
  37 class Millisecond;
  38 }
  39
  40
  41
  42 namespace anna {
  43
  44 namespace diameter {
  45
  46 namespace codec {
  47 class Engine;
  48 }
  49
  50 namespace comm {
  51
  52
  53 class Entity;
  54 class Server;
  55 class LocalServer;
  56
  57 /**
  58  *  General manager for connections to several diameter servers and from diameter clients.
  59  *
  60  *  Optimizes creation, finding and releasing of established client-sessions to a certain number of
  61  *  diameter servers through entities.
  62  *  Optimizes creation, finding and releasing of established server-sessions from a certain number of
  63  *  diameter clients through local servers.
  64  *
  65  *  Implementation example:
  66  *
  67  *  \code
  68  *
  69  *     class MyEngine : public diameter::comm::Engine {
  70  *     public:
  71  *        MyEngine () {;}
  72  *
  73  *     private:
  74  *        anna::Recycler<MyEntity> a_entities;
  75  *
  76  *        anna::diameter::comm::Entity* allocateEntity () throw () { return a_entities.create (); }
  77  *
  78  *        void releaseEntity (anna::diameter::comm::Entity* entity) throw () {
  79  *           MyEntity* aux = static_cast <MyEntity*> (entity);
  80  *           a_entities.release (aux);
  81  *        }
  82  *
  83  *
  84  *        anna::diameter::comm::LocalServer* allocateLocalServer () throw () { return a_localServers.create (); }
  85  *
  86  *        void releaseLocalServer (anna::diameter::comm::LocalServer* localServer) throw () {
  87  *           MyLocalServer* aux = static_cast <MyLocalServer*> (localServer);
  88  *           a_localServers.release (aux);
  89  *        }
  90  *     };
  91  *
  92  *  \endcode
  93  */
  94 class Engine : public anna::app::Component {
  95 public:
  96
  97   /**
  98      Logical name for this anna::app::Component.
  99      \return Logical name for this anna::app::Component.
 100   */
 101   static const char* getClassName() throw() { return "anna::diameter::comm::Engine"; }
 102
 103   /**
 104      Diameter application node realm name (used to be the site domain name).
 105
 106      @param name Diameter application node realm name. Used in order to configure the Origin-Realm for outgoing messages.
 107      If not configured or empty string provided, host domainname will be set.
 108   */
 109   void setRealm(const std::string & name) throw();
 110
 111
 112   /**
 113      Gets the configured diameter application node realm name.
 114
 115      @return Diameter application node realm name.
 116   */
 117   const std::string & getRealm() const throw() { return a_realm; }
 118
 119
 120   /**
 121      Diameter application host name as solved by #anna::functions::getHostname()
 122
 123      @param name Host name. Used in order to configure the Origin-Host for outgoing messages.
 124      If not configured or empty string provided, hostname (system name) will be set.
 125   */
 126   void setHost(const std::string & name) throw();
 127
 128
 129   /**
 130      Gets the configured diameter application host name.
 131
 132      @return Diameter application host name.
 133   */
 134   const std::string & getHost() const throw() { return a_host; }
 135
 136
 137   /**
 138    * Propagate auto recovery configuration to entities within engine. Recovery period is configured at
 139    * #anna::comm::Communicator::setRecoveryTime. All the client client-sessions created throught #createEntity,
 140    * will be created based on the engine auto-recovery value (enable by default). But you could access entities,
 141    * servers or client-sessions independently to change this behaviour.
 142    *
 143    * @param autoRecovery Auto recovery indicator. True by default.
 144    */
 145   void raiseAutoRecovery(bool autoRecovery = true) throw(anna::RuntimeException);
 146
 147   /**
 148    * Returns automatic bind indicator for client-sessions. By default \em true will be used.
 149    * \return Value for automatic connection bind.
 150    */
 151   bool getAutoBind() const throw() { return a_autoBind; }
 152
 153   /**
 154    * Sets automatic connection bind indicator for client-sessions. If not asigned, it will be \em true.
 155    * \param autoBind Value for automatic connection bind.
 156    *
 157    * In order to change bind timer, first client-session must be created without autobind, modify time
 158    * parameter and then invoking bind.
 159    */
 160   void setAutoBind(const bool autoBind) throw() { a_autoBind = autoBind; }
 161
 162   /**
 163      Sets the milliseconds wait to achieve a client connection to server by mean connect primitive.
 164      This is a general value for born client-sessions over engine. Particular configuration could be done
 165      through #ClientSession::setMaxConnectionDelay.
 166
 167      \param maxConnectionDelay Milliseconds wait to get connection
 168   */
 169   void setMaxConnectionDelay(const anna::Millisecond & maxConnectionDelay) throw() { a_maxConnectionDelay = maxConnectionDelay; }
 170
 171   /**
 172      Gets the milliseconds wait to achieve a client connection to server by mean connect primitive.
 173      Returns the global engine value, but it could be overwritten through each client session (#ClientSession::setMaxConnectionDelay).
 174      Default value is 'anna::comm::ClientSocket::DefaultMaxConnectionDelay'.
 175
 176      \return Milliseconds wait to get connection
 177   */
 178   const anna::Millisecond & getMaxConnectionDelay() throw() { return a_maxConnectionDelay; }
 179
 180   /**
 181    * Binds engine entities.
 182    *
 183    * @return Returns true if all client-session were successfully bound
 184    */
 185   bool bind() throw(anna::RuntimeException);
 186
 187   /**
 188    * Sets CER and DWR diameter messages to be used over created client-sessions.
 189    * Its recommended to set this global configuration although it is possible to configure each client-session separately.
 190    *
 191    * @param cer Capabilities-Exchange-Request message (encoded) for the client-sessions bind.
 192    * @param dwr Device-Watchdog-Request message (encoded) for the client-sessions keep-alive.
 193    */
 194   void setCERandDWR(const anna::DataBlock & cer, const anna::DataBlock & dwr) throw(anna::RuntimeException);
 195
 196
 197   /**
 198    * Sets the watchdog period (DWR) for client-sessions.
 199    * Its recommended to set this global configuration although it is possible to configure each client-session separately.
 200    *
 201    * @param wp Watchdog period.
 202    */
 203   void setWatchdogPeriod(const anna::Millisecond & wp) throw(anna::RuntimeException);
 204
 205   /**
 206    * Gets the number of client-sessions per server.
 207    * \return numberOfClientSessionsPerServer Number of client-sessions per server.
 208    */
 209   int getNumberOfClientSessionsPerServer() const throw() { return a_numberOfClientSessionsPerServer; }
 210
 211   /**
 212    * Sets the number of client-sessions per server.
 213    * Its recommended to set this global configuration although it is possible to configure each client-session separately.
 214    * \param numberOfClientSessionsPerServer Number of client-sessions per server.
 215    */
 216   void setNumberOfClientSessionsPerServer(int numberOfClientSessionsPerServer) throw() { a_numberOfClientSessionsPerServer = numberOfClientSessionsPerServer; }
 217
 218
 219   /**
 220    * Returns client-session instance identified by (address, port, socketId) provided.
 221    *
 222    * \param addr Diameter server address (ip or hostname).
 223    * \param port Diameter server port.
 224    * @param socketId Diameter server socket id.
 225    * \param emode Action when no client-session is found with provided parameters (Throw/Ignore).
 226    *
 227    * \return The client-session instance identified by (address, port, socketId) provided.
 228    *
 229    * \warning If no client-session found, an exception is launched by default.
 230    */
 231   ClientSession* findClientSession(const std::string & addr, int port, int socketId, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) throw(anna::RuntimeException);
 232
 233
 234   /**
 235    * Same as #findClientSession, but providing client session key (<address>:<port>|<socket id>)
 236    */
 237   ClientSession* findClientSession(const std::string & key, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) throw(anna::RuntimeException);
 238
 239
 240   /**
 241    * Returns server instance identified by pair (address, port) provided.
 242    *
 243    * \param addr Diameter server address (ip or hostname).
 244    * \param port Diameter server port.
 245    * \param emode Action when no client-session is found with provided parameters (Throw/Ignore).
 246    *
 247    * \return The server instance identified by pair (address, port) provided.
 248    *
 249    * \warning If no server found, an exception is launched by default.
 250    */
 251   Server* findServer(const std::string & addr, int port, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) throw(anna::RuntimeException);
 252
 253   /**
 254    * Returns entity instance identified by internal index.
 255    *
 256    * \param socketList Diameter entity servers list.
 257    * \param emode Action when no client-session is found with provided parameters (Throw/Ignore).
 258    *
 259    * \return The entity instance identified by id provided.
 260    *
 261    * \warning If no entity found, an exception is launched by default.
 262    */
 263   Entity* findEntity(const socket_v & socketList, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) throw(anna::RuntimeException);
 264
 265   /**
 266    * Returns entity instance identified by internal index.
 267    *
 268    * \param addr1 Diameter primary server address (ip or hostname).
 269    * \param port1 Diameter primary server port.
 270    * \param addr2 Diameter secondary server address (ip or hostname).
 271    * \param port2 Diameter secondary server port.
 272    * \param emode Action when no client-session is found with provided parameters (Throw/Ignore).
 273    *
 274    * \return The entity instance identified by id provided.
 275    *
 276    * \warning If no entity found, an exception is launched by default.
 277    */
 278   Entity* findEntity(const std::string & addr1, int port1, const std::string & addr2, int port2, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) throw(anna::RuntimeException);
 279
 280   /**
 281    * Creates a diameter entity with provided parameters.
 282    *
 283    * Depending on auto-bind configuration, capabilities exchange request will be or won't be performed over the entity client-sessions.
 284    *
 285    * \param socketList Diameter server priority list (priority-ordered) in order to define whole entity.
 286    * @param description Optional entity description (empty by default)
 287    *
 288    * \return The entity created or exception when any server (address/port) already exists for another entity.
 289    *
 290    * \warning The entity won't be almost operative until a notification by mean 'ClientSession::eventResponse'
 291    * indicates that 'ClassCode::Bind' has been correctly performed for any included client-session.
 292    */
 293   Entity* createEntity(const socket_v & socketList, const std::string & description = "")
 294   throw(anna::RuntimeException);
 295
 296   /**
 297    * Creates a standard (dual) diameter entity with provided parameters.
 298    *
 299    * Depending on auto-bind configuration, capabilities exchange request will be or won't be performed over the entity client-sessions.
 300    *
 301    * \param addr1 Diameter primary server address (ip or hostname).
 302    * \param port1 Diameter primary server port.
 303    * \param addr2 Diameter secondary server address (ip or hostname).
 304    * \param port2 Diameter secondary server port.
 305    * @param description Optional entity description (empty by default)
 306    *
 307    * \return The standard entity created or exception when any server (address/port) already exists for another entity.
 308    *
 309    * \warning The entity won't be almost operative until a notification by mean 'ClientSession::eventResponse'
 310    * indicates that 'ClassCode::Bind' has been correctly performed for any included client-session.
 311    */
 312   Entity* createEntity(const std::string & addr1, int port1, const std::string & addr2, int port2, const std::string & description = "")
 313   throw(anna::RuntimeException);
 314
 315
 316   /**
 317    * Returns local server instance identified by pair (address, port) provided.
 318    *
 319    * @param addr Diameter server socket address (ip or hostname).
 320    * @param port Diameter server socket port.
 321    * \param emode Action when no local server is found with provided parameters (Throw/Ignore).
 322    *
 323    * \return The local server instance identified by pair (address, port) provided.
 324    *
 325    * \warning If no local server found, an exception is launched by default.
 326    */
 327   LocalServer* findLocalServer(const std::string & addr, int port, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) throw(anna::RuntimeException);
 328
 329   /**
 330    * Returns server-session instance identified by INetAddress serialization provided.
 331    *
 332    * @param socketId Hash for Client Socket INetAddress serialization
 333    * \param emode Action when no server-session is found with provided parameters (Throw/Ignore).
 334    *
 335    * \return The server-session instance identified by global unique socketId provided.
 336    *
 337    * \warning If no server-session found, an exception is launched by default.
 338    */
 339   ServerSession* findServerSession(int socketId, anna::Exception::Mode::_v emode = anna::Exception::Mode::Throw) throw(anna::RuntimeException);
 340
 341   /**
 342    * Creates a diameter local server with provided parameters.
 343    *
 344    * Server socket address could be an IPv4 or hostname. Default port will be standard 3868 for diameter agents,
 345    * but any other could be configured. Socket server could be created with any max accepted connections: zero
 346    * value means temporarily disabled and negative values assume no limit (shared bind) for incomming connections.
 347    *
 348    * @param addr Diameter server socket address (ip or hostname).
 349    * @param port Diameter server socket port (standard 3868 by default).
 350    * @param maxConnections Diameter server max sessions allowed (no limit by default).
 351    * @param allowedInactivityTime Max inactivity time for server sessions over the local server before being reset.
 352    * @param category Optional socket server category (1 by default).
 353    * @param description Optional socket server description (empty by default).
 354    *
 355    * \return The local server created or exception when is already created.
 356    */
 357   LocalServer *createLocalServer(const std::string & addr, int port = Session::DefaultPort, int maxConnections = -1, const anna::Millisecond & allowedInactivityTime = ServerSession::DefaultAllowedInactivityTime, int category = 1, const std::string & description = "")
 358   throw(anna::RuntimeException);
 359
 360
 361   /**
 362      Close all the engine resources (entities and local servers)
 363      Optionally all resources may be freed passing true
 364
 365      @param destroy Free all engine entity resources
 366   */
 367   void close(bool destroy = false) throw(anna::RuntimeException) { closeEntities(destroy); closeLocalServers(destroy); }
 368
 369
 370   /**
 371      Close all the engine entities (close servers, then close client-sessions within them). Depending on client-session configuration
 372      ('OnDisconnect' behaviour), pending answers will be wait (graceful) or ignored (immediate-abrupt close).
 373      Optionally all entities resources may be freed passing true; in this case, close is immediately performed:
 374      @param destroy Free all engine entity resources
 375   */
 376   void closeEntities(bool destroy = false) throw(anna::RuntimeException);
 377
 378
 379   /**
 380    * Close entity servers (then, client-sessions included) and optionally free resources including entity itself.
 381    * If entity is null, this operation has no effect.
 382    *
 383    * \param entity Diameter entity to be closed.
 384    * \param destroy Deletes entity over the engine and all its resources.
 385    */
 386   void closeEntity(Entity* entity, bool destroy = false) throw(anna::RuntimeException);
 387
 388
 389   /**
 390      Close all the engine local server sockets including their children server sessions.
 391      Optionally all local server resources may be freed passing true.
 392
 393      @param destroy Free all engine local servers resources and server sessions within them.
 394   */
 395   void closeLocalServers(bool destroy = false) throw(anna::RuntimeException);
 396
 397   /**
 398    * Close local server socket and its children server sessions.
 399    * This is useful when detecting service lost. When service is ready to handle traffic, a new server socket would
 400    * be created by mean #LocalServer::enable() and new connections could be accepted.
 401    * Optionally local server resources may be freed passing true.
 402    *
 403    * \param localServer Local server to be closed.
 404    * \param destroy Deletes local server over engine and all its resources (server sessions within it).
 405    */
 406   void closeLocalServer(LocalServer * localServer, bool destroy = false) throw(anna::RuntimeException);
 407
 408   /**
 409      Gets the number of requests messages over-the-air for entities.
 410
 411      @return OTA messages.
 412   */
 413   int getOTARequestsForEntities() const throw();
 414
 415   /**
 416      Gets the number of requests messages over-the-air for local servers.
 417
 418      @return OTA messages.
 419   */
 420   int getOTARequestsForLocalServers() const throw();
 421
 422   /**
 423      Gets the number of requests messages over-the-air for entities plus local servers.
 424
 425      @return OTA messages.
 426   */
 427   int getOTARequests() const throw() { return (getOTARequestsForEntities() + getOTARequestsForLocalServers()); }
 428
 429   /**
 430      Returns idle state (no pending answers) for entities.
 431
 432      @return Idle state.
 433   */
 434   bool idleForEntities() const throw() { return (getOTARequestsForEntities() == 0); }
 435
 436   /**
 437      Returns idle state (no pending answers).
 438
 439      @return Idle state.
 440   */
 441   bool idleForLocalServers() const throw() { return (getOTARequestsForLocalServers() == 0); }
 442
 443   /**
 444      Returns idle state (no pending answers for entities or local servers).
 445
 446      @return Idle state.
 447   */
 448   bool idle() const throw() { return (getOTARequests() == 0); }
 449
 450   /**
 451      Sent a message to all the engine entities.
 452      It is used, i.e., in Disconnect-Peer-Request procedure over the engine.
 453
 454      \param message Message which is being sent.
 455
 456      @return Returns true (success) only when broadcast is success over all the engine entities. If any entity fails,
 457      then false is returned. Broadcast try to send all over the resources in spite of any fail.
 458   */
 459   bool broadcastEntities(const Message*message) throw(anna::RuntimeException);
 460   bool broadcastEntities(const Message& message) throw(anna::RuntimeException) { return broadcastEntities(&message); }
 461
 462   /**
 463      Sent a message through all the engine local servers.
 464      It is used, i.e., in Disconnect-Peer-Request procedure over the engine.
 465
 466      \param message Message which is being sent.
 467
 468      @return Returns true (success) only when broadcast is success over all the engine local servers. If any local server fails,
 469      then false is returned. Broadcast try to send all over the resources in spite of any fail.
 470   */
 471   bool broadcastLocalServers(const Message*message) throw(anna::RuntimeException);
 472   bool broadcastLocalServers(const Message& message) throw(anna::RuntimeException) { return broadcastLocalServers(&message); }
 473
 474   /**
 475   * Class string representation
 476   *
 477   * @return String with class content
 478   */
 479   virtual std::string asString(void) const throw();
 480
 481   /**
 482      Class XML representation.
 483      \param parent XML node over which we will put instance information.
 484      \return XML documentcon with class content.
 485   */
 486   virtual anna::xml::Node* asXML(anna::xml::Node* parent) const throw();
 487
 488
 489   /**
 490      When there is not bound server session over the engine, this virtual method will be invoked.
 491      Applications must decide to do any other tasks at this idle/isolated situation.
 492      Default implementation do nothing.
 493   */
 494   virtual void availabilityLostForLocalServers(Engine *) const throw() {;}
 495
 496   /**
 497      When there is any bound server session over the engine, this virtual method will be invoked.
 498      Applications must decide to do be ready for incoming traffic.
 499      Default implementation do nothing.
 500   */
 501   virtual void availabilityRecoveredForLocalServers(Engine *) const throw() {;}
 502
 503   /**
 504      When there is not bound entity over the engine, this virtual method will be invoked.
 505      Many applications must change communicator status to Unavailable when no engines are available.
 506      Default implementation do nothing.
 507   */
 508   virtual void availabilityLostForEntities(Engine *) const throw() {;}
 509
 510   /**
 511      When there is any bound entity over the engine, this virtual method will be invoked.
 512      Many applications must recover communicator status to Available when any engine are available.
 513      Default implementation do nothing.
 514   */
 515   virtual void availabilityRecoveredForEntities(Engine *) const throw() {;}
 516
 517   /**
 518      When there is not bound server-session over the local server, this virtual method will be invoked.
 519      Default implementation do nothing.
 520   */
 521   virtual void availabilityLost(LocalServer *) const throw() {;}
 522
 523   /**
 524      When there is any bound server-session over the local server, this virtual method will be invoked.
 525      Default implementation do nothing.
 526   */
 527   virtual void availabilityRecovered(LocalServer *) const throw() {;}
 528
 529   /**
 530      When there is not bound server over the entity, this virtual method will be invoked.
 531      Default implementation do nothing.
 532   */
 533   virtual void availabilityLost(Entity *) const throw() {;}
 534
 535   /**
 536      When there is any bound server over the entity, this virtual method will be invoked.
 537      Default implementation do nothing.
 538   */
 539   virtual void availabilityRecovered(Entity *) const throw() {;}
 540
 541   /**
 542      When there is not bound client-session over the server, this virtual method will be invoked.
 543      Default implementation do nothing.
 544   */
 545   virtual void availabilityLost(Server *) const throw() {;}
 546
 547   /**
 548      When there is any bound client-session over the server, this virtual method will be invoked.
 549      Default implementation do nothing.
 550   */
 551   virtual void availabilityRecovered(Server *) const throw() {;}
 552
 553   /**
 554      When a subyacent client session is going to be bound, this method is invoked before.
 555      Default implementation do nothing.
 556   */
 557   virtual void bindingClientSession(const ClientSession *) const throw() {;}
 558
 559   /**
 560    * Class user should implement this method in order to define Disconnect-Peer-Answer for last received DPR.
 561    * Origin-Host and Origin-Realm are configured at comm::Engine with hostname and FQDN (Fully Qualified Domain Name).
 562    * Default implementation imply DPA with DIAMETER_SUCCESS Result-Code, allowing remote disconnection.
 563    * Any other implementation is responsible to build a valid DPA diameter message.
 564    * DPR/DPA procedure is disabled with empty definition of this method: no DPA will be sent when DPR is received.
 565    *
 566    * @param dpa DPA datablock passed as reference
 567    * @param dpr Corresponding DPR received (sequence values must be taken into account in order to build DPA)
 568   */
 569   virtual void readDPA(anna::DataBlock &dpa, const anna::DataBlock & dpr) throw();
 570
 571   /**
 572    * Class user should implement this method in order to define Capabilities-Exchange-Answer for received CER over server socket.
 573    * Origin-Host and Origin-Realm are configured at comm::Engine with hostname and FQDN (Fully Qualified Domain Name).
 574    * Default implementation imply CEA with DIAMETER_SUCCESS Result-Code, and own domain node parameters, but application should
 575    * analyze the CER message in order to accept it or not (with apropiate non-success Result-Code).
 576    * Any other implementation is responsible to build a valid CEA diameter message:
 577    *
 578    * If one peer sends a CER message to another Peer and receiver does not have support for
 579    *
 580    *  1) any common application then it must return the CEA with Result-Code Avp set to DIAMETER_NO_COMMON_APPLICATION
 581    *     and should disconnect the transport layer connection (automatically done by diameter::comm module).
 582    *  2) no common security mechanism then it must return the CEA with Result-Code Avp set to DIAMETER_NO_COMMON_SECURITY
 583    *     and should disconnect the transport layer connection (automatically done by diameter::comm module).
 584    *  3) if CER is received from any unknown peer then receiver should discard the message, or send the CEA with the
 585    *     Result-Code Avp set to DIAMETER_UNKNOWN_PEER.
 586    *
 587    *  If the local implementation policy permits to receive CER from unknown hosts, a successful CEA MAY be returned,
 588    *  and the life time of the peer entry in PEER-Table is equal to the lifetime of the transport connection.
 589    *  If in any case transport connection fails then all the pending transactions destined to the unknown peer can be discarded.
 590    *
 591    *  The CER and CEA messages MUST NOT be proxied, redirected or relayed. Since CER/CEA messages can not be proxied, but still
 592    *  it is possible that proxy will receive a CER message and proxy does not have any peer to handle the application requested
 593    *  in CER, in this case proxy set the E bit in CEA and set the Result-Code Avp to DIAMETER_UNABLE_TO_DELIVER, sends back to
 594    *  CER generator peer.
 595    *
 596    * @param cea CEA datablock passed as reference. Empty cea implies to discard CER received.
 597    * @param cer Corresponding CER received (sequence values must be taken into account in order to build CEA)
 598   */
 599   virtual void readCEA(anna::DataBlock &cea, const anna::DataBlock & cer) throw();
 600
 601   /**
 602    * Class user should implement this method in order to define Device-Watchdog-Answer for received DWR over server socket.
 603    * Origin-Host and Origin-Realm are configured at comm::Engine with hostname and FQDN (Fully Qualified Domain Name).
 604    * Default implementation imply DWA with DIAMETER_SUCCESS Result-Code, and own domain node parameters.
 605    * Any other implementation is responsible to build a valid DWA diameter message.
 606    *
 607    * @param dwa DWA datablock passed as reference
 608    * @param dwr Corresponding DWR received (sequence values must be taken into account in order to build DWA)
 609   */
 610   virtual void readDWA(anna::DataBlock &dwa, const anna::DataBlock & dwr) throw();
 611
 612   /**
 613      Reset engine statistics.
 614      At the moment, only diameter servers processing time is observed.
 615   */
 616   void resetStatistics() throw();
 617
 618
 619 protected:
 620   /**
 621      Constructor.
 622   */
 623   Engine();
 624
 625
 626   // INTERNAL CREATORS AND CLOSE METHODS
 627   Server *createServer(Entity*, const socket_t&) throw(anna::RuntimeException);
 628   void closeServer(Server*, bool) throw(anna::RuntimeException);
 629   ClientSession *createClientSession(Server*, int) throw(anna::RuntimeException);
 630   void closeClientSession(ClientSession*, bool) throw(anna::RuntimeException);
 631
 632   // INTERNAL ALLOCATORS
 633   Server* allocateServer() throw();
 634   void releaseServer(Server*) throw();
 635   ClientSession* allocateClientSession() throw();
 636   void releaseClientSession(ClientSession*) throw();
 637
 638
 639   /**
 640      Entity allocator method.
 641
 642      It is recommended to use anna::Recycler for entities creation/releasing.
 643
 644      \see anna::Recycler
 645   */
 646   virtual Entity* allocateEntity() throw() { return NULL; }
 647
 648
 649   /**
 650      Invoked to free entities.
 651      \see anna::Recycler
 652   */
 653   virtual void releaseEntity(Entity*) throw() {;}
 654
 655
 656   /**
 657      Local server allocator method.
 658
 659      It is recommended to use anna::Recycler for entities creation/releasing.
 660
 661      \see anna::Recycler
 662   */
 663   virtual LocalServer* allocateLocalServer() throw() { return NULL; }
 664
 665
 666   /**
 667      Invoked to free local servers.
 668      \see anna::Recycler
 669   */
 670   virtual void releaseLocalServer(LocalServer*) throw() {;}
 671
 672
 673
 674 private:
 675
 676   std::string a_realm;
 677   std::string a_host;
 678   bool a_autoBind;
 679   int a_numberOfClientSessionsPerServer;
 680
 681
 682   // ClientSessions messages:
 683   anna::DataBlock a_cer;
 684   anna::DataBlock a_dwr;
 685   anna::Millisecond a_watchdogPeriod;
 686
 687 //   // ServerSessions messages:
 688 //   anna::DataBlock a_cea;
 689 //   anna::DataBlock a_dwa;
 690
 691   // Client connectivity
 692   anna::Millisecond a_maxConnectionDelay;
 693
 694
 695   // Availability
 696   bool a_availableForEntities; // any of the entities must be bound
 697   void availabilityLostForEntities() throw();
 698   void availabilityRecoveredForEntities() throw();
 699   bool refreshAvailabilityForEntities() throw(); // return true if change
 700
 701   bool a_availableForLocalServers; // any of the local servers must be bound
 702   void availabilityLostForLocalServers() throw();
 703   void availabilityRecoveredForLocalServers() throw();
 704   bool refreshAvailabilityForLocalServers() throw(); // return true if change
 705
 706   void eraseDeprecatedIdleEntities() throw();
 707
 708   // Component:
 709   void do_initialize() throw() {;}
 710   void do_stop() throw();
 711
 712   // Integrity:
 713   void checkEntityCollision(const socket_v &) throw(anna::RuntimeException);
 714
 715
 716   //////////////////////////
 717   // CLIENT FUNCTIONALITY //
 718   //////////////////////////
 719
 720   //typedef int clientSession_key; // exclusiveHash('ADDR:PORT|id')
 721   typedef std::string clientSession_key; // 'ADDR:PORT|id'
 722   typedef std::map <clientSession_key, ClientSession*> clientSession_container;
 723   typedef clientSession_container::value_type clientSession_value_type;
 724   typedef clientSession_container::iterator clientSession_iterator;
 725   typedef clientSession_container::const_iterator const_clientSession_iterator;
 726   clientSession_container a_clientSessions;
 727   anna::Recycler<ClientSession> a_clientSessionsRecycler;
 728   clientSession_iterator clientSession_find(const clientSession_key&) throw();
 729   clientSession_iterator clientSession_begin() throw() { return a_clientSessions.begin(); }
 730   clientSession_iterator clientSession_end() throw() { return a_clientSessions.end(); }
 731   static ClientSession* clientSession(clientSession_iterator ii) throw() { return ii->second; }
 732   const_clientSession_iterator clientSession_begin() const throw() { return a_clientSessions.begin(); }
 733   const_clientSession_iterator clientSession_end() const throw() { return a_clientSessions.end(); }
 734   static const ClientSession* clientSession(const_clientSession_iterator ii) throw() { return ii->second; }
 735
 736   typedef socket_t server_key;
 737   server_key getServerKey(const std::string & addr, int port) const throw();
 738   typedef std::map <server_key, Server*> server_container;
 739   typedef server_container::value_type server_value_type;
 740   typedef server_container::iterator server_iterator;
 741   typedef server_container::const_iterator const_server_iterator;
 742   server_container a_servers;
 743   anna::Recycler<Server> a_serversRecycler;
 744   server_iterator server_find(const server_key&) throw();
 745   server_iterator server_begin() throw() { return a_servers.begin(); }
 746   server_iterator server_end() throw() { return a_servers.end(); }
 747   static Server* server(server_iterator ii) throw() { return ii->second; }
 748   const_server_iterator server_begin() const throw() { return a_servers.begin(); }
 749   const_server_iterator server_end() const throw() { return a_servers.end(); }
 750   static const Server* server(const_server_iterator ii) throw() { return ii->second; }
 751
 752   //typedef int entity_key; // exclusiveHash('IP1:PORT1 IP2:PORT2 IP3:PORT3 ...')
 753   typedef std::string entity_key; // 'ADDR1:PORT1 ADDR2:PORT2 ADDR3:PORT3 ...'
 754   entity_key getEntityKey(const socket_v &) const throw();
 755   entity_key getEntityKey(const std::string & addr1, int port1, const std::string & addr2, int port2) const throw();
 756   typedef std::map <entity_key, Entity*> entity_container;
 757   typedef entity_container::value_type entity_value_type;
 758   typedef entity_container::iterator entity_iterator;
 759   typedef entity_container::const_iterator const_entity_iterator;
 760   entity_container a_entities;
 761   entity_iterator entity_find(const entity_key&) throw();
 762   entity_iterator entity_begin() throw() { return a_entities.begin(); }
 763   entity_iterator entity_end() throw() { return a_entities.end(); }
 764   static Entity* entity(entity_iterator ii) throw() { return ii->second; }
 765   const_entity_iterator entity_begin() const throw() { return a_entities.begin(); }
 766   const_entity_iterator entity_end() const throw() { return a_entities.end(); }
 767   static const Entity* entity(const_entity_iterator ii) throw() { return ii->second; }
 768
 769
 770   //////////////////////////
 771   // SERVER FUNCTIONALITY //
 772   //////////////////////////
 773
 774   // Local servers
 775   typedef std::map <socket_t, LocalServer*> localServer_container;
 776   typedef localServer_container::value_type localServer_value_type;
 777   typedef localServer_container::iterator localServer_iterator;
 778   typedef localServer_container::const_iterator const_localServer_iterator;
 779   localServer_container a_localServers;
 780   localServer_iterator localServer_find(const socket_t&) throw();
 781   localServer_iterator localServer_begin() throw() { return a_localServers.begin(); }
 782   localServer_iterator localServer_end() throw() { return a_localServers.end(); }
 783   static LocalServer* localServer(localServer_iterator ii) throw() { return ii->second; }
 784   const_localServer_iterator localServer_begin() const throw() { return a_localServers.begin(); }
 785   const_localServer_iterator localServer_end() const throw() { return a_localServers.end(); }
 786   static const LocalServer* localServer(const_localServer_iterator ii) throw() { return ii->second; }
 787
 788   // Server sessions are managed within LocalServer (not at engine) due to dynamic cration nature
 789
 790
 791   friend class Session;
 792   friend class ServerSession;
 793   friend class ServerSocket;
 794   friend class Server;
 795   friend class Entity;
 796   friend class LocalServer;
 797   //friend class Message;
 798 };
 799
 800 }
 801 }
 802 }
 803
 804 #endif
 805