Updated license

[anna.git] / include / anna / diameter / codec / EngineImpl.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_diameter_codec_EngineImpl_hpp
#define anna_diameter_codec_EngineImpl_hpp


// STL
#include <string>

#include <anna/core/RuntimeException.hpp>
#include <anna/xml/DTDMemory.hpp>
#include <anna/core/util/Recycler.hpp>

#include <anna/core/util/Component.hpp>
#include <anna/diameter/defines.hpp>


//------------------------------------------------------------------------------
//---------------------------------------------------------------------- #define
//------------------------------------------------------------------------------


namespace anna {

namespace diameter {

namespace stack {
class Dictionary;
}

namespace codec {

extern const char *MessageDTD;

class Message;
class Avp;


/**
 * General component implementation of a diameter elements factory (messages, avps) and common resources which
 *  configure encode/decode operations behaviour.
 *
 * Standard inheritance is done over codec::Engine, allocating basic Avp and Message classes.
 * A child implementation could manage complex Avp classes with new data-part formats. Grouped ones could
 *  allocate new complex Avps through such engine which knows how to allocate this special Avp's (also for
 *  complex Message classes with application-specific setters and getters as credit-control related avps,
 *  or some another context items). For example helpers for TME scope stands for a new engine component
 *  called tme::Engine, allocating tme::Avp and tme::Message classes which support three new Avp formats:
 *  ISDNNumber, ISDNAddress and Unsigned16. Anyway, main Message/Avp and Engine classes stand for all contexts
 *  included in anna::diameter, that is to say, whole contexts (at the time only TME) will be included in future
 *  when needed apart from the independent namespace version. Thank to this, single threaded applications could
 *  use whole engine in a easy way.
 *
 * Usually an engine component is associated to a single diameter stack, although single threaded processes could
 *  use a common engine alternating different stack dictionaries by mean #setDictionary, depending on which kind of
 *  messages are being analyzed. Although the application must ensure that a single dictionary is activated during
 *  the same context operations an Avp could be considered as Unknown if was created with another, and we could
 *  have validation problems (i.e. if mandatory Avp bit is enabled). In general, managing Unknown data-part format
 *  don't have to be a problem because it is interpreted as OctetString format. Depending on what setters/getters
 *  we use, it could reach a RuntimeException at our application.
 *
 * At multithread processes we must use one heir engine per stack and never switching stacks within same component.
 * We will use each engine for each context.
 *
 * It is recommended to use Message class to create Avps (adding them through pair identification <code + vendor-id>
 *  prototype), but we could create Avps separately (other program section, i.e) and join them after:
 *
 * <pre>
 * 1. Recommended way:
 *
 *    // Message creation:
 *    Message * msg = new Message(helpers::base::COMMANDID__Re_Auth_Answer);
 *    // Adding + creation:
 *    Avp * avp_sid = msg->addAvp(helpers::base::AVPID__Session_Id);
 *    Avp * avp_oh = msg->addAvp(helpers::base::AVPID__Origin_Host);
 *    Avp * avp_or = msg->addAvp(helpers::base::AVPID__Origin_Realm);
 *    Avp * avp_rc = msg->addAvp(helpers::base::AVPID__Result_Code);
 *    // Setting data:
 *    avp_sid->getUTF8String()->setValue("grump.example.com:33041;23432;893;0AF3B81");
 *    ...
 *
 * 2. External Avp creation:
 *
 *    // Message creation:
 *    Message * msg = new Message(helpers::base::COMMANDID__Re_Auth_Answer);
 *    // Creation:
 *    Avp * avp_sid = new Avp(helpers::base::AVPID__Session_Id);
 *    Avp * avp_oh = new Avp(helpers::base::AVPID__Origin_Host);
 *    Avp * avp_or = new Avp(helpers::base::AVPID__Origin_Realm);
 *    Avp * avp_rc = new Avp(helpers::base::AVPID__Result_Code);
 *    // Adding:
 *    msg->addAvp(avp_sid);
 *    msg->addAvp(avp_oh);
 *    msg->addAvp(avp_or);
 *    msg->addAvp(avp_rc);
 *    // Setting data:
 *    avp_sid->getUTF8String()->setValue("grump.example.com:33041;23432;893;0AF3B81");
 *    ...
 *
 * The main difference is that Avps created through Message (or through grouped Avps) are internally allocated
 *  through engine which normally implements a recycler to optimize memory use.
 * </pre>
 *
 *
 * Implementation example:
 *
 *  \code
 *
 *     class MyEngine : public EngineImpl {
 *     public:
 *        Engine (getClassName()) {;}
 *        static const char* getClassName() throw() { return "<full-naming path>::MyEngine"; }
 *
 *     private:
 *        anna::Recycler<MyAvp> a_avps;
 *        anna::Recycler<MyMessage> a_messages;
 *
 *        anna::diameter::codec::Avp* allocateAvp () throw () { return a_avps.create (); }
 *
 *        void releaseAvp (anna::diameter::codec::Avp* avp) throw () {
 *             if (avp == NULL) return;
 *             MyAvp* aux = static_cast <MyAvp*> (avp);
 *             aux->clear(); // free internal data-part storage specially for grouped avps which will release its childrens
 *             a_avps.release (aux);
 *        }
 *
 *        anna::diameter::codec::Message* allocateMessage () throw () { return a_messages.create (); }
 *
 *        void releaseMessage (anna::diameter::codec::Message* message) throw () {
 *             if (message == NULL) return;
 *             MyMessage* aux = static_cast <MyMessage*> (message);
 *             aux->clear(); // free internal data-part storage specially for childrens releasing
 *             a_messages.release (aux);
 *        }
 *     };
 *
 *  \endcode
 */
class EngineImpl : public anna::Component {

public:

  /**
   * Defines behaviour on validation procedure: complete analysis or stop at first validation error over the message (by default)
   */
  struct ValidationDepth { enum _v { Complete, FirstError /* default */ }; };

  /**
   * Defines behaviour mode regarding when to validate a message: before encoding, after decoding (by default), always or never
   * Anyway validation procedure may be called at any moment (#valid)
   */
  struct ValidationMode { enum _v { BeforeCoding, AfterDecoding /* default */, Always, Never /* optimization */ }; };

  /**
   * Defines behaviour mode regarding when to fix a message: before encoding (by default), after decoding, always or never.
   * An application could add Avps in any order; the fix procedure try to adjust it regarding dictionary. I.e., fixed
   *  Avps will be placed on first position, before mandatory and optional ones, within the message level or any
   *  grouped Avp. Usually we need to configure fixing before encoding in order to provide flexibility to the application
   *  during message construction, but actually, optimal mode implies disabling this procedure. Fixing after decoding will
   *  hide any validation problem regarding Avps position at any level.
   * Anyway fix procedure may be called at any moment (#fix)
   */
  struct FixMode { enum _v { BeforeCoding /* default */, AfterDecoding, Always, Never /* optimization */ }; };


  // Creators
  Avp* createAvp(const AvpId *id) throw(anna::RuntimeException);
  Message* createMessage(const CommandId *id) throw(anna::RuntimeException);


private:

  anna::xml::DTDMemory a_dtd;
  ValidationDepth::_v a_validationDepth;
  ValidationMode::_v a_validationMode;
  bool a_ignoreFlags;
  FixMode::_v a_fixMode;

  // Auxiliary
  const stack::Dictionary * a_dictionary;

  // helpers
  static const char* asText(const ValidationDepth::_v) throw();
  static const char* asText(const ValidationMode::_v) throw();
  static const char* asText(const FixMode::_v) throw();

public:

  /** Constructor
      @param className Logical name for the class.
   */
  EngineImpl(const char* className);

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


  /**
     Sets diameter dictionary loaded at stack engine. It's recommended to configure a valid dictionary
     (if not, or NULL provided at #setDictionary, all avps will be managed as 'Unknown' format and all
     items will need to be manually updated, i.e. message and avp flags).

     @param dictionary Diameter dictionary. At single threaded processes, the same codec engine could be used with
     different diameter dictionaries (multi-stack applications). In that case the process must switch the stack for
     the whole decoding or enconding operation over a Message depending on the context. But the smart way implies
     inherit from this engine creating a component for each diameter stack managed in the application. Inheritance
     is mandatory in multi-threaded processes: one engine, a unique stack.
  */
  void setDictionary(const stack::Dictionary * dictionary) throw() { a_dictionary = dictionary; }

  // get
  /**
  * Sets diameter dictionary loaded at stack engine with the provided identifier.
  *
  * @param stackId Stack identifier. When missing, default stack (stack::Engine::getDefaultStack()) will be used
  * @return Returns configured dictionary (NULL if stack id was not found)
  */
  const stack::Dictionary *setDictionary(int stackId = -1) throw();

  /**
     Gets currently configured dictionary. NULL if not configured (manual encode/decode operations).

     @return Returns currently configured engine dictionary
  */
  const stack::Dictionary *getDictionary() const throw() { return a_dictionary; }


  /**
   * Sets behaviour on validation procedure.
   * \param validationDepth Behaviour on validation procedure: complete analysis or stop at first validation error over the message.
   */
  void setValidationDepth(const ValidationDepth::_v validationDepth)  throw() { a_validationDepth = validationDepth; }

  /**
   * Returns behaviour on on validation procedure.
   * For practical purposes, the Failed-AVP would typically refer to the first AVP processing error that a Diameter node encounters
   * (decoding error or validation error in this case).
   * A complete validation depth incurs on multiple-content Failed-AVP and is perhaps useful during integration tasks.
   *
   * \return Behaviour on validation procedure: complete analysis or stop at first validation error over the message (by default).
   */
  ValidationDepth::_v getValidationDepth() const throw() { return a_validationDepth; }

  /**
   * Sets behaviour on validation procedure regarding stack flags. Actually, only AVP flags M & P are affected. The vendor bit is
   * too important to be ignored, and there is no way to check operation flags (as request bit).
   * By default (at engine start), flags are verified.
   * \param ignoreFlags Validation will ignore flags.
   */

  void ignoreFlagsOnValidation(bool ignoreFlags) throw() { a_ignoreFlags = ignoreFlags; }

  /**
   * Gets behaviour on validation procedure regarding stack flags. Actually, only AVP flags M & P are affected. The vendor bit is
   * too important to be ignored, and there is no way to check operation flags (as request bit).
   * By default (at engine start), flags are verified.
   * \return Validation ignore flags indicator.
   */
  bool ignoreFlagsOnValidation() const throw() { return a_ignoreFlags; }

  /**
   * Sets validation mode.
   * \param validationMode Validation mode: before encoding, after decoding, always or never.
   */
  void setValidationMode(const ValidationMode::_v validationMode)  throw() { a_validationMode = validationMode; }

  /**
   * Returns validation mode.
   * Before coding validation mode is perhaps useful during debugging tasks, i.e. to check answer messages built by the application
   * during development phase.
   * \return Validation mode: before encoding, after decoding (by default), always or never.
   */
  ValidationMode::_v getValidationMode() const throw() { return a_validationMode; }



  /**
   * Sets fix mode.
   * \param fixMode Fix mode: before encoding, after decoding, always or never.
   */
  void setFixMode(const FixMode::_v fixMode)  throw() { a_fixMode = fixMode; }

  /**
   * Returns fix mode.
   * \return Fix mode: before encoding (by default), after decoding, always or never.
   */
  FixMode::_v getFixMode() const throw() { return a_fixMode; }



  /**
     DTD document for xml message parsing
  */
  const anna::xml::DTDMemory & getDTD() const throw() { return a_dtd; }

  /**
  * Creates a new diameter avp assigning its identifier, using engine resources to allocate memory (recommended
  *  recycler allocation at engine component re-implementation of allocator methods). Obviously, normal objects
  *  creation (new) is possible.
  *
  * @param id Avp identifier. AVP flags will be established based on active dictionary for known avps, or
  * uninitialized for unknown ones.
  *
  * @return Created avp ready to be used
  */
  Avp* createAvp(AvpId id) throw(anna::RuntimeException) { return createAvp(&id); }

  /**
  * Creates a new diameter avp, using engine resources to allocate memory (recommended recycler allocation at
  *  engine component re-implementation of allocator methods). Obviously, normal objects creation (new) is possible.
  *
  * @return Created avp ready to be used
  */
  Avp* createAvp() throw(anna::RuntimeException) { return createAvp(NULL); }

  /**
  * Creates a new diameter Message assigning its identifier, using engine resources to allocate memory (recommended
  *  recycler allocation at engine component re-implementation of allocator methods). Obviously, normal objects
  *  creation (new) is possible.
  *
  * @param id Command identifier. Message flags will be established based on active dictionary for known commands,
  *  or uninitialized for unknown ones.
  *
  * @return Created message ready to be used
  */
  Message* createMessage(CommandId id) throw(anna::RuntimeException) { return createMessage(&id); }

  /**
  * Creates a new diameter message, using engine resources to allocate memory (recommended recycler allocation
  *  at engine component re-implementation of allocator methods). Obviously, normal objects creation (new) is possible.
  *
  * @return Created message ready to be used
  */
  Message* createMessage() throw(anna::RuntimeException) { return createMessage(NULL); }


  /**
     Loads an xml file representing a diameter message base in a DTD document (#getDTD)

     @param xmlPathFile Complete path file to the xml document which represents the diameter message
  */
  Message *createMessage(const std::string & xmlPathFile) throw(anna::RuntimeException);


  /**
     Invoked to free Avps.
     \see anna::Recycler
  */
  virtual void releaseAvp(Avp*) throw() = 0;

  /**
     Invoked to free Messages.
     \see anna::Recycler
  */
  virtual void releaseMessage(Message*) throw() = 0;


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

  /**
     Class XML representation.
     \param parent XML node over which we will put instance information.
     \return XML documentcon with class content.
  */
  virtual anna::xml::Node* asXML(anna::xml::Node* parent) const throw();


  /**
     Gets the Avp identifier providing its logical name at engine dictionary

     @param name Name of the Avp at engine dictionary

     @return Avp identifier as pair (code,vendor-id)
  */
  AvpId avpIdForName(const char * name) throw(anna::RuntimeException);


  /**
     Gets the Command identifier providing its logical name at engine dictionary

     @param name Name of the Command at engine dictionary

     @return Command identifier as pair (code,request-indicator)
  */
  CommandId commandIdForName(const char * name) throw(anna::RuntimeException);


protected:

  /**
     Avp allocator method.

     It is recommended to use anna::Recycler for Avps creation/releasing.

     \see anna::Recycler
  */
  virtual Avp* allocateAvp() throw() = 0;


  /**
     Message allocator method.

     It is recommended to use anna::Recycler for Message creation/releasing.

     \see anna::Recycler
  */
  virtual Message* allocateMessage() throw() = 0;


  /**
     Manages warning trace or exception on validation anomaly depending on ValidationDepth configuration
     ('complete' and 'first error' reports respectively).

     @description Anomaly description used in trace or exception

     @see setValidationDepth
     @see getValidationDepth
  */
  void validationAnomaly(const std::string & description) const throw(anna::RuntimeException);
};

}
}
}

#endif