[anna.git] / include / anna / core / oam / Module.hpp

// ANNA - Anna is Not 'N' 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_core_oam_Module_hpp
#define anna_core_oam_Module_hpp


// STL
#include <string>
#include <vector>
#include <map>

#include <anna/core/RuntimeException.hpp>

#include <anna/core/oam/defines.hpp>
#include <anna/core/oam/Handler.hpp>

#include <cstdarg>


namespace anna {
namespace xml {
class Node;
}
namespace oam {
class CounterScope;
}
}


namespace anna {

namespace oam {

class Handler;

/**
* Class used to implement context-module-alarms/counters. Each process module (within library or process itself) must
* inherit from this, defining specific-alarm/counters codes (better public enum type) which will be managed within each
* module (usually through a management singleton class). This allow code reusability regarding alarm/counter conditions
* usually badly managed with API return codes instead of self-governing alarms shared and reusabled by any API client,
* or counters with fixed-inflexible values. It is posible to manage more than one oam module per library or proccess,
* simply defining more children classes, but the normal way is to use only one.
*
* <pre>
*
* Example of use:
*
*  class OamModule : public anna::oam::Module, public anna::Singleton <OamModule>
*  {
*              struct Counter
*              {
*                 enum _v // types
*                 {
*                    None = -1,
*                    ErrorLDAP
*                 };
*
*                 anna_declare_enum(Counter);
*              };
*
*              struct Alarm
*              {
*                 enum _v // types
*                 {
*                    None = -1,
*                    ErrorOnNode__s__WithSessionId__d__
*                 };
*
*                 anna_declare_enum(Alarm);
*              };
*
*        OamModule() : anna::oam::Module ("Main Proccess 'HTE_CLDAP' OAM module") {;};
*
*        friend class anna::Singleton <OamModule>;
*  };
*
* Normally, we will use one scope per module (library/proccess) but we could define many oam modules per subsystem functionality.
* For example, libanna.diameter.b have oam modules for comm.db and codec.db. Also, macros as 'anna_declare_enum' are useful to
* define default descriptions for counter and alarm types.
*
*
* == REGISTRATION for all the linked scopes ==
*
* anna::<project>::oam::Handler *projectHandler = new anna::<project>::oam::Handler(); // handler for project alarms
*
* OamModule & oam_proc = OamModule::instantiate();
* <library_namespace>::OamModule & oam_lib = <library_namespace>::OamModule::instantiate();
* oam_proc.setHandler(projectHandler);
* oam_proc.initializeCounterScope (1);
* oam_proc.registerCounter (OamModule::Counter::ErrorLDAP, "ErrorLDAP", 0);
* oam_proc.registerAlarm (OamModule::Alarm::ErrorOnNode__s__WithSessionId__d__, "Error on node", 1, "nodeName,errorCode", anna::oam::MSAlarmId::NODE_ERROR);
*
* oam_lib.setHandler(projectHandler);
* oam_lib.initializeCounterScope (2); // different scope for different modules (normal way)
* oam_lib.registerCounter (<library_namespace>::OamModule::Counter::<type>, "counter description", 0);
* oam_lib.registerAlarm (<library_namespace>::OamModule::Alarm::<type>, "alarm description", 2, <dynamic variable names CSL>, anna::oam::MSAlarmId::<type>);
*
* -> LAUNCH for all local scopes (library launches will be done at library code):
* oam_proc.count (OamModule::Counter::ErrorLDAP);
* oam_proc.activateAlarm (OamModule::Alarm::ErrorOnNode__s__WithSessionId__d__, "my node", a_session_id);
*
*
* == MULTI-CONTEXT APPLICATIONS ==
*
* Suppose two contexts, one with scopes 1 and 4 for process and library respectively, and
* the other defined by 2 and 5:
*
* oam_proc.initializeCounterScope (1, "Main OAM Module - Context A");
* oam_proc.initializeCounterScope (2, "Main OAM Module - Context B");
* Counters registration ...
*
* oam_lib.initializeCounterScope (4, "Encoder OAM Module - Context A");
* oam_lib.initializeCounterScope (5, "Encoder OAM Module - Context B");
* Counters registration ...
*
* Application must switch between these scope ids to distinguise the contexts:
*
* Context A:
* oam_proc.setActiveCounterScope(1);
* oam_lib.setActiveCounterScope(4);
*
* Context B:
* oam_proc.setActiveCounterScope(2);
* oam_lib.setActiveCounterScope(5);
*
* </pre>
*/
class Module {

  Handler a_defaultHandler;        // default OAM handler
  Handler *a_handler;              // Handler reference

  std::string a_className;         // module description
  bool a_counters_enabled;         // Enable/Disable registered counters over this module (default is 'true')
  bool a_alarms_enabled;           // Enable/Disable registered alarms over this module (default is 'true')

  // dynamic modifications over alarm text
  bool a_alarms_preffix_enabled;   // Show own module alarm preffix
  bool a_alarms_suffix_enabled;    // Show own module alarm suffix
  std::string alarmComponentsToText(const std::vector<std::string> & components, const std::string & psL, const std::string & psS, const std::string & psR) const throw();

  // GENERIC COUNTERS
  anna::oam::CounterScope* a_active_counter_scope; // Current scope for counters generation
  typedef std::map <int, anna::oam::CounterScope*> scope_container;
  scope_container a_scopes; // Module can manage N scope clones (usually, there is only one registered scope: mono-context applications)
  typedef std::map < int /*type*/, counter_data_t > counter_container;
  counter_container a_counters;

  // GENERIC ALARMS
  typedef std::map < int /*type*/, alarm_data_t > alarm_container;
  alarm_container a_alarms;

  void alarmEvent(bool activation, const int & type, va_list argList) const throw();

  // Counters
  typedef scope_container::iterator scope_iterator;
  typedef scope_container::const_iterator const_scope_iterator;
  scope_iterator scope_find(const int &key) throw() { return a_scopes.find(key); }
  scope_iterator scope_begin() throw() { return a_scopes.begin(); }
  scope_iterator scope_end() throw() { return a_scopes.end(); }
  static anna::oam::CounterScope* scope(scope_iterator ii) throw() { return ii->second; }
  const_scope_iterator scope_begin() const throw() { return a_scopes.begin(); }
  const_scope_iterator scope_end() const throw() { return a_scopes.end(); }
  static const anna::oam::CounterScope* scope(const_scope_iterator ii) throw() { return ii->second; }
  anna::oam::CounterScope *getScope(const int &id) throw();
  typedef counter_container::iterator counter_iterator;
  typedef counter_container::const_iterator const_counter_iterator;
//   bool counter_remove(const int &key) throw();
  const_counter_iterator counter_find(const int &key) const throw() { return a_counters.find(key); }
  const_counter_iterator counter_begin() const throw() { return a_counters.begin(); }
  const_counter_iterator counter_end() const throw() { return a_counters.end(); }
  counter_iterator counter_find(const int &key) throw() { return a_counters.find(key); }
  counter_iterator counter_begin() throw() { return a_counters.begin(); }
  counter_iterator counter_end() throw() { return a_counters.end(); }


  // Alarms
  typedef alarm_container::iterator alarm_iterator;
  typedef alarm_container::const_iterator const_alarm_iterator;
//   bool alarm_remove(const int &key) throw();
  const_alarm_iterator alarm_find(const int &key) const throw() { return a_alarms.find(key); }
  const_alarm_iterator alarm_begin() const throw() { return a_alarms.begin(); }
  const_alarm_iterator alarm_end() const throw() { return a_alarms.end(); }
  alarm_iterator alarm_find(const int &key) throw() { return a_alarms.find(key); }
  alarm_iterator alarm_begin() throw() { return a_alarms.begin(); }
  alarm_iterator alarm_end() throw() { return a_alarms.end(); }
  void getAlarmPreffixSuffixAndZoneSeparator(std::string & preffix, std::string & suffix, char & zS) const throw();


public:

  /** Constructor
      @param className Logical name for the class (better use fullNaming format including namespace resolution)
   */
  Module(const std::string &className) :    a_className(className),
    a_handler(&a_defaultHandler),
    a_counters_enabled(true),
    a_alarms_enabled(true),
    a_alarms_preffix_enabled(true),
    a_alarms_suffix_enabled(true) {;}


  /**
   * Destructor
   */
  virtual ~Module() {;}


  /**
  * Enable all the counters registered in this module (enabled by default at constructor).
  * Usually managed at PROCCESS implementation
  */
  void enableCounters(void) throw();

  /**
  * Disable all the counters registered in this module (enabled by default at constructor).
  * Usually managed at PROCCESS implementation
  */
  void disableCounters(void) throw();

  /**
  * Enable all the alarms registered in this module (enabled by default at constructor).
  * Usually managed at PROCCESS implementation
  */
  void enableAlarms(void) throw();

  /**
  * Disable all the alarms registered in this module (enabled by default at constructor).
  * Usually managed at PROCCESS implementation
  */
  void disableAlarms(void) throw();

  /**
  * Show own module alarm preffix (enabled by default at constructor).
  * Usually managed at PROCCESS implementation
  */
  void enableAlarmsPreffix(void) throw();

  /**
  * Show own module alarm suffix (enabled by default at constructor).
  * Usually managed at PROCCESS implementation
  */
  void enableAlarmsSuffix(void) throw();

  /**
  * Hide own module alarm preffix (enabled by default at constructor).
  * Usually managed at PROCCESS implementation
  */
  void disableAlarmsPreffix(void) throw();

  /**
  * Hide own module alarm suffix (enabled by default at constructor).
  * Usually managed at PROCCESS implementation
  */
  void disableAlarmsSuffix(void) throw();

  /**
  * Sets the operations handler. By default, all modules will use the default anna::oam::Handler.
  * This method will be used only when a different behaviour is needed, for example for the project
  * specific events.
  *
  * Used ONLY at PROCCESS implementation (initial tasks)
  *
  * @param handler Handler used for OAM operations (registering and launch). NULL is ignored
  */
  void setHandler(Handler *handler) throw() { if(handler) a_handler = handler; }

  /**
  * Counter scope registration. Usually, only one scope id will be registered, but multicontext applications
  * could manage scope clones where all the counters are REPLICATED in order to manage separate sub-facilities.
  * Multicontext applications must invoke N times to this method, and then register the common counters.
  * Each context must activate with 'setActiveCounterScope()', the correct scope id.
  * After invocation, provided scope id will be activated.
  * Used ONLY at PROCCESS implementation (initial tasks)
  *
  * @param scopeId Counter scope id. It must be non negative (0 is usually reserved for core platform counters).
  * @param description Counter scope id description. If missing, module description will be set, but is
  * a good idea add different names between replicated scopes, i.e.: 'Main OAM Module - Context X', etc.
  * better than 'Main OAM Module' for all of them. Also, you can use the same description for all scopes
  * (that is the case of default assignment).
  */
  void initializeCounterScope(const int & scopeId, const std::string & description = "") throw(anna::RuntimeException);


  /**
  * Multicontext application could decide the correct scope id in order to sure right sub-module counting.
  * Applications that only initializes one scope (which becomes active after that), don't need to use this method.
  * Used ONLY at PROCCESS implementation (normal tasks)
  *
  * @param scopeId Counter scope id which becomes active.
  */
  void setActiveCounterScope(const int & scopeId) throw();


  /**
  * Gets the current activated counter scope
  *
  * @return Activated counter scope
  */
  const anna::oam::CounterScope* getActiveCounterScope() const throw() { return a_active_counter_scope; }

  /**
  * Child oam module classes should define descriptions for each enum type. A good practice would be the use of
  * 'anna_declare_enum' macro in order to define names for enum types. This is an oam-internal description which
  * should be redefined at application layer during registering. Returns undefined by default.
  *
  * @param type Counter enum-identification within the own context/module
  *
  * @return Default alarm description
  */
  virtual std::string getDefaultInternalAlarmDescription(const int & type) const throw();

  /**
  * Child oam module classes should define descriptions for each enum type. A good practice would be the use of
  * 'anna_declare_enum' macro in order to define names for enum types. This is an oam-internal description which
  * should be redefined at application layer during registering. Returns undefined by default.
  *
  * @param type Counter enum-identification within the own context/module
  *
  * @return Default counter description
  */
  virtual std::string getDefaultInternalCounterDescription(const int & type) const throw();


  /**
  * Counter registration providing the specific documentacion codes.
  * To guarantee clone operations, no scope initialization will be possible after use of this method.
  * Used ONLY at PROCCESS implementation (initial tasks)
  *
  * @param type Counter enum-identification added within the module (defined enum type on @Singleton child class)
  * @param description Counter description added within the module. If empty string is provided, default description
  * for non-registered will be searched (#getDefaultInternalCounterDescription).
  * @param offset Counter offset over (1000 * scope id). Offset has 0-999 range.
  */
  void registerCounter(const int &type, const std::string &description, const int &offset) throw(anna::RuntimeException);


  /**
  * Alarm registration providing the specific process codes useful for manage any kind of alarm generation: external id
  * (which could be a database unique idenfier), dynamic variables used during text parsing to allow advanced manipulation,
  * and activation/cancellation codes (which could be used at a certain management system node).
  *
  * @param type Alarm enum-identification added within the module (defined enum type on @Singleton child class)
  * @param description Alarm description added within the module. If empty string is provided, default description
  * for non-registered will be searched (#getDefaultInternalAlarmDescription).
  * @param externalId External text identification.
  * @param dynamicVariablesCSL Comma-separated list of dynamic variable names (same order than launched with #activateAlarm and #cancelAlarm).
  * @param activationId Alarm activation identifier
  * @param cancellationId Alarm cancellation identifier. If missing, the alarm will interpreted as non-transferable
  */
  void registerAlarm(const int &type, const std::string &description, const int &externalId, const std::string &dynamicVariablesCSL, const int &activationId, const int &cancellationId = -1) throw(anna::RuntimeException);


  /**
     Gets the OAM module name

     @param OAM module name
  */
  const char *getClassName() const throw() { return a_className.c_str(); }


  /**
     Gets counter data for type provided. NULL if not found.

     @param type Alarm enum-identification within the own context/module.
  */
  const counter_data_t *counter(const int &type) const throw() {
    const_counter_iterator it = counter_find(type);
    return ((it != counter_end()) ? (&(*it).second) : NULL);
  }

  /**
     Gets alarm data for type provided. NULL if not found.

     @param type Counter enum-identification within the own context/module.
  */
  const alarm_data_t *alarm(const int &type) const throw() {
    const_alarm_iterator it = alarm_find(type);
    return ((it != alarm_end()) ? (&(*it).second) : NULL);
  }


  /**
  * Notifies counter increase with certain amount within the ativated scope
  * Used at MODULE implementation (library or proccess itself)
  *
  * @param type Counter enum-identification within the own context/module
  * @param amount Units increased. Default is 1
  */
  void count(const int & type, const int & amount = 1) throw(anna::RuntimeException);


  /**
  * Reset all counters accumulated amount (analysis purposes)
  * Usually managed at PROCCESS implementation
  *
  * @param scopeId Restrict reset to provided scope id. If missing, all scopes will be affected.
  *
  * @return Number of affected counters which have been reset (only those which have non-zero accumulated count).
  */
  int resetCounters(const int & scopeId = -1) throw();


  /**
  * Activates alarm with dynamic-composed text parsed with provided data (...).
  * Used at MODULE implementation (library or proccess itself)
  *
  * @param alarmType Alarm enum-identification within the own context/module
  * @param ... Optional parsing data for dynamic-composed text.
  */
  void activateAlarm(const int & type, ...) const throw(anna::RuntimeException);


  /**
  * Send transferable alarm cancellation, with dynamic-composed text parsed with provided data (...)
  * Used at MODULE implementation (library or proccess itself)
  *
  * @param alarmType Alarm enum-identification within the own context/module
  * @param ... Optional parsing data for dynamic-composed text.
  */
  void cancelAlarm(const int & type, ...) const throw(anna::RuntimeException);


  /**
  * Class string representation
  * Usually managed at PROCCESS implementation
  *
  * @return String with class content
  */
  virtual std::string asString(void) const throw();


  /**
  * Class XML representation
  * Usually managed at PROCCESS implementation
  *
  * @return XML with class content
  */
  virtual anna::xml::Node* asXML(anna::xml::Node* parent) const throw();


protected:

  /**
  * Module alarm preffix components used to add aditional information over alarm text.
  * Oam modules push-back this additional components to global 'Configuration' preffix components.
  * To disable, use 'disableAlarmsPreffix()'.
  * Note that preffix components string should be multilanguage texts if alarm texts are based on
  * language-context traslations.
  * Used at MODULE implementation (library or proccess itself)
  *
  * @param components Alarm preffix components defined by oam module. Empty on default implementation.
  */
  virtual void readAlarmPreffixComponents(std::vector<std::string> & components) const throw() {;}


  /**
  * Module alarm suffix components used to add aditional information over alarm text.
  * Oam modules push-back this additional components to global 'Configuration' suffix components.
  * To disable, use 'disableAlarmsSuffix()'.
  * Note that suffix components string should be multilanguage texts if alarm texts are based on
  * language-context traslations.
  * Used at MODULE implementation (library or proccess itself)
  *
  * @param components Alarm suffix components defined by oam module. Empty on default implementation.
  */
  virtual void readAlarmSuffixComponents(std::vector<std::string> & components) const throw() {;}
};

}
}

#endif