anna::oam::Module Class Reference

#include <Module.hpp>

Inheritance diagram for anna::oam::Module:

Public Member Functions
	Module (const std::string &name)
virtual	~Module ()
int	scopes () const
void	enableCounters (void)
void	disableCounters (void)
void	enableAlarms (void)
void	disableAlarms (void)
bool	countersEnabled () const
bool	alarmsEnabled () const
void	enableAlarmsPreffix (void)
void	enableAlarmsSuffix (void)
void	disableAlarmsPreffix (void)
void	disableAlarmsSuffix (void)
void	setHandler (Handler *handler)
void	initializeCounterScope (const int &scopeId, const std::string &description="") noexcept(false)
void	setActiveCounterScope (const int &scopeId)
const anna::oam::CounterScope *	getActiveCounterScope () const
virtual std::string	getDefaultInternalAlarmDescription (const int &type) const
virtual std::string	getDefaultInternalCounterDescription (const int &type) const
void	registerCounter (const int &type, const std::string &description, const int &offset) noexcept(false)
void	registerAlarm (const int &type, const std::string &description, const int &externalId, const std::string &dynamicVariablesCSL, const int &activationId, const int &cancellationId=-1) noexcept(false)
const char *	getName () const
const counter_data_t *	counter (const int &type) const
const alarm_data_t *	alarm (const int &type) const
void	count (const int &type, const int &amount=1) noexcept(false)
int	resetCounters (const int &scopeId=-1)
void	setCounterRecorder (CounterRecorder *counterRecorder)
void	recordCounters () noexcept(false)
void	activateAlarm (int type,...) const noexcept(false)
void	cancelAlarm (int type,...) const noexcept(false)
virtual std::string	asString (void) const
virtual anna::xml::Node *	asXML (anna::xml::Node *parent) const

Static Public Attributes
static const int	MaxScope = 1000

Protected Member Functions
virtual void	readAlarmPreffixComponents (std::vector< std::string > &components) const
virtual void	readAlarmSuffixComponents (std::vector< std::string > &components) const

Friends
class	RecordingGuard

Detailed Description

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.

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);

Constructor & Destructor Documentation

Module()

anna::oam::Module::Module ( const std::string &  name )

inline

Constructor

Parameters

name	Logical name for the class (better use fullNaming format including namespace resolution)

                                :
    a_handler(&a_defaultHandler),
    a_name(name),
    a_counters_enabled(false),
    a_alarms_enabled(false),
    a_alarms_preffix_enabled(true),
    a_alarms_suffix_enabled(true),
    a_counterRecorder(NULL),
    a_counterRecording(false) {;}

~Module()

virtual anna::oam::Module::~Module ( )

virtual

Destructor

Member Function Documentation

activateAlarm()

void anna::oam::Module::activateAlarm ( int  type,   ...  ) const

noexcept

Activates alarm with dynamic-composed text parsed with provided data (...). Used at MODULE implementation (library or proccess itself)

Parameters

alarmType	Alarm enum-identification within the own context/module
...	Optional parsing data for dynamic-composed text.

alarm()

const alarm_data_t* anna::oam::Module::alarm ( const int &  type ) const

inline

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

Parameters

type	Counter enum-identification within the own context/module.

                                                   {
    const_alarm_iterator it = alarm_find(type);
    return ((it != alarm_end()) ? (&(*it).second) : NULL);
  }

alarmsEnabled()

bool anna::oam::Module::alarmsEnabled ( ) const

inline

Getter for alarms enabled

{ return a_alarms_enabled; }

asString()

virtual std::string anna::oam::Module::asString ( void  ) const

virtual

Class string representation Usually managed at PROCCESS implementation

Returns

String with class content

asXML()

virtual anna::xml::Node* anna::oam::Module::asXML ( anna::xml::Node *  parent ) const

virtual

Class XML representation Usually managed at PROCCESS implementation

Returns

XML with class content

cancelAlarm()

void anna::oam::Module::cancelAlarm ( int  type,   ...  ) const

noexcept

Send transferable alarm cancellation, with dynamic-composed text parsed with provided data (...) Used at MODULE implementation (library or proccess itself)

Parameters

alarmType	Alarm enum-identification within the own context/module
...	Optional parsing data for dynamic-composed text.

count()

void anna::oam::Module::count ( const int &  type, const int &  amount = 1  )

noexcept

Notifies counter increase with certain amount within the ativated scope Used at MODULE implementation (library or proccess itself)

Parameters

type	Counter enum-identification within the own context/module
amount	Units increased. Default is 1

counter()

const counter_data_t* anna::oam::Module::counter ( const int &  type ) const

inline

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

Parameters

type	Alarm enum-identification within the own context/module.

                                                       {
    const_counter_iterator it = counter_find(type);
    return ((it != counter_end()) ? (&(*it).second) : NULL);
  }

countersEnabled()

bool anna::oam::Module::countersEnabled ( ) const

inline

Getter for counters enabled

{ return a_counters_enabled; }

disableAlarms()

void anna::oam::Module::disableAlarms

(

void

)

Disable all the alarms registered in this module (enabled by default at constructor). Usually managed at PROCCESS implementation

disableAlarmsPreffix()

void anna::oam::Module::disableAlarmsPreffix

(

void

)

Hide own module alarm preffix (enabled by default at constructor). Usually managed at PROCCESS implementation

disableAlarmsSuffix()

void anna::oam::Module::disableAlarmsSuffix

(

void

)

Hide own module alarm suffix (enabled by default at constructor). Usually managed at PROCCESS implementation

disableCounters()

void anna::oam::Module::disableCounters

(

void

)

Disable all the counters registered in this module (enabled by default at constructor). Usually managed at PROCCESS implementation

enableAlarms()

void anna::oam::Module::enableAlarms

(

void

)

Enable all the alarms registered in this module (enabled by default at constructor). Usually managed at PROCCESS implementation

enableAlarmsPreffix()

void anna::oam::Module::enableAlarmsPreffix

(

void

)

Show own module alarm preffix (enabled by default at constructor). Usually managed at PROCCESS implementation

enableAlarmsSuffix()

void anna::oam::Module::enableAlarmsSuffix

(

void

)

Show own module alarm suffix (enabled by default at constructor). Usually managed at PROCCESS implementation

enableCounters()

void anna::oam::Module::enableCounters

(

void

)

Enable all the counters registered in this module (enabled by default at constructor). Usually managed at PROCCESS implementation

getActiveCounterScope()

const anna::oam::CounterScope* anna::oam::Module::getActiveCounterScope ( ) const

inline

Gets the current activated counter scope

Returns

Activated counter scope

{ return a_active_counter_scope; }

getDefaultInternalAlarmDescription()

virtual std::string anna::oam::Module::getDefaultInternalAlarmDescription ( const int &  type ) const

virtual

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.

Parameters

type	Counter enum-identification within the own context/module

Returns

Default alarm description

Reimplemented in anna::diameter::comm::OamModule, and anna::diameter::codec::OamModule.

getDefaultInternalCounterDescription()

virtual std::string anna::oam::Module::getDefaultInternalCounterDescription ( const int &  type ) const

virtual

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.

Parameters

type	Counter enum-identification within the own context/module

Returns

Default counter description

Reimplemented in anna::diameter::comm::OamModule, anna::diameter::codec::OamModule, and anna::diameter::comm::ApplicationMessageOamModule.

getName()

const char* anna::oam::Module::getName ( ) const

inline

Gets the OAM module name

Parameters

OAM	module name

{ return a_name.c_str(); }

initializeCounterScope()

void anna::oam::Module::initializeCounterScope ( const int &  scopeId, const std::string &  description = ""  )

noexcept

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)

Parameters

scopeId	Counter scope id. It must be non negative (0 is usually reserved for core platform counters).
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).

readAlarmPreffixComponents()

virtual void anna::oam::Module::readAlarmPreffixComponents ( std::vector< std::string > &  components ) const

inlineprotectedvirtual

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)

Parameters

components

Alarm preffix components defined by oam module. Empty on default implementation.

{;}

readAlarmSuffixComponents()

virtual void anna::oam::Module::readAlarmSuffixComponents ( std::vector< std::string > &  components ) const

inlineprotectedvirtual

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)

Parameters

components

Alarm suffix components defined by oam module. Empty on default implementation.

{;}

recordCounters()

void anna::oam::Module::recordCounters ( )

noexcept

Dumps the modified counters from last invocation to this method. A counter recorder should have been assigned by mean setCounterRecorder(), which will have the specific behaviour. This procedure is oriented to have physical storage for counters information.

registerAlarm()

void anna::oam::Module::registerAlarm ( const int &  type, const std::string &  description, const int &  externalId, const std::string &  dynamicVariablesCSL, const int &  activationId, const int &  cancellationId = -1  )

noexcept

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).

Parameters

type	Alarm enum-identification added within the module (defined enum type on child class)
description	Alarm description added within the module. If empty string is provided, default description for non-registered will be searched (getDefaultInternalAlarmDescription).
externalId	External text identification.
dynamicVariablesCSL	Comma-separated list of dynamic variable names (same order than launched with activateAlarm and cancelAlarm).
activationId	Alarm activation identifier
cancellationId	Alarm cancellation identifier. If missing, the alarm will interpreted as non-transferable

registerCounter()

void anna::oam::Module::registerCounter ( const int &  type, const std::string &  description, const int &  offset  )

noexcept

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)

Parameters

type	Counter enum-identification added within the module (defined enum type on child class)
description	Counter description added within the module. If empty string is provided, default description for non-registered will be searched (getDefaultInternalCounterDescription).
offset	Counter offset over (1000 * scope id). Offset has 0-999 range.

resetCounters()

int anna::oam::Module::resetCounters

(

const int &

scopeId = -1

)

Reset all counters accumulated amount (analysis purposes) Usually managed at PROCCESS implementation

Parameters

scopeId

Restrict reset to provided scope id. If missing, all scopes will be affected.

Returns

Number of affected counters which have been reset (only those which have non-zero accumulated count).

scopes()

int anna::oam::Module::scopes ( ) const

inline

Number of scopes registered

{ return a_scopes.size(); }

setActiveCounterScope()

void anna::oam::Module::setActiveCounterScope

(

const int &

scopeId

)

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)

Parameters

scopeId

Counter scope id which becomes active.

setCounterRecorder()

void anna::oam::Module::setCounterRecorder ( CounterRecorder *  counterRecorder )

inline

Sets the instance for the class which will save the counters information. Provided instance

Warning

It should be invoked periodically as a common solution

{ a_counterRecorder = counterRecorder; }

setHandler()

void anna::oam::Module::setHandler ( Handler *  handler )

inline

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)

Parameters

handler

Handler used for OAM operations (registering and launch). NULL is ignored

{ if(handler) a_handler = handler; }

Friends And Related Function Documentation

RecordingGuard

friend class RecordingGuard

friend

Member Data Documentation

MaxScope

const int anna::oam::Module::MaxScope = 1000

static

Numero maximo de ambitos

---

The documentation for this class was generated from the following file:

• /tmp/anna/include/anna/core/oam/Module.hpp