bug in RC
[anna.git] / include / anna / diameter / codec / EngineImpl.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_codec_EngineImpl_hpp
10 #define anna_diameter_codec_EngineImpl_hpp
11
12
13 // STL
14 #include <string>
15
16 #include <anna/core/RuntimeException.hpp>
17 #include <anna/xml/DTDMemory.hpp>
18 #include <anna/core/util/Recycler.hpp>
19
20 #include <anna/core/util/Component.hpp>
21 #include <anna/diameter/defines.hpp>
22
23
24 //------------------------------------------------------------------------------
25 //---------------------------------------------------------------------- #define
26 //------------------------------------------------------------------------------
27
28
29 namespace anna {
30
31 namespace diameter {
32
33 namespace stack {
34 class Dictionary;
35 }
36
37 namespace codec {
38
39 class Message;
40 class Avp;
41
42
43 /**
44  * General component implementation of a diameter elements factory (messages, avps) and common resources which
45  *  configure encode/decode operations behaviour.
46  *
47  * Standard inheritance is done over codec::Engine, allocating basic Avp and Message classes.
48  * A child implementation could manage complex Avp classes with new data-part formats. Grouped ones could
49  *  allocate new complex Avps through such engine which knows how to allocate this special Avp's (also for
50  *  complex Message classes with application-specific setters and getters as credit-control related avps,
51  *  or some another context items). For example tme::Avp and tme::Message classes support three new Avp formats:
52  *  ISDNNumber, ISDNAddress and Unsigned16. Anyway, main Message/Avp and Engine classes stand for all contexts
53  *  included in anna::diameter, that is to say, whole contexts (at the time only TME) will be included in future
54  *  when needed apart from the independent namespace version. Thank to this, single threaded applications could
55  *  use whole engine in a easy way.
56  *
57  * An engine component is associated to a single diameter stack. It is application responsability to use message
58  * container initialized with the correct codec engine depending on the context. There are helpers to do this at
59  * anna::diameter::codec::functions::getApplicationId (from xml document or hexadecimal buffer).
60  *
61  * It is recommended to use Message class to create Avps (adding them through pair identification <code + vendor-id>
62  *  prototype), but we could create Avps separately (other program section, i.e) and join them after:
63  *
64  * <pre>
65  * 1. Recommended way:
66  *
67  *    // Message creation:
68  *    Message * msg = new Message(helpers::base::COMMANDID__Re_Auth_Answer, codecEngine);
69  *    // Adding + creation:
70  *    Avp * avp_sid = msg->addAvp(helpers::base::AVPID__Session_Id);
71  *    Avp * avp_oh = msg->addAvp(helpers::base::AVPID__Origin_Host);
72  *    Avp * avp_or = msg->addAvp(helpers::base::AVPID__Origin_Realm);
73  *    Avp * avp_rc = msg->addAvp(helpers::base::AVPID__Result_Code);
74  *    // Setting data:
75  *    avp_sid->getUTF8String()->setValue("grump.example.com:33041;23432;893;0AF3B81");
76  *    ...
77  *
78  * 2. External Avp creation:
79  *
80  *    // Message creation:
81  *    Message * msg = new Message(helpers::base::COMMANDID__Re_Auth_Answer, codecEngine);
82  *    // Creation:
83  *    Avp * avp_sid = new Avp(helpers::base::AVPID__Session_Id, codecEngine);
84  *    Avp * avp_oh = new Avp(helpers::base::AVPID__Origin_Host, codecEngine);
85  *    Avp * avp_or = new Avp(helpers::base::AVPID__Origin_Realm, codecEngine);
86  *    Avp * avp_rc = new Avp(helpers::base::AVPID__Result_Code, codecEngine);
87  *    // Adding:
88  *    msg->addAvp(avp_sid);
89  *    msg->addAvp(avp_oh);
90  *    msg->addAvp(avp_or);
91  *    msg->addAvp(avp_rc);
92  *    // Setting data:
93  *    avp_sid->getUTF8String()->setValue("grump.example.com:33041;23432;893;0AF3B81");
94  *    ...
95  *
96  * The main difference is that Avps created through Message (or through grouped Avps) are internally allocated
97  *  through engine which normally implements a recycler to optimize memory use.
98  * </pre>
99  *
100  *
101  * Implementation example:
102  *
103  *  \code
104  *
105  *     class MyEngine : public EngineImpl {
106  *     public:
107  *        MyEngine (const char *className = "MyEngine") : Engine(className) {;}
108  *
109  *     private:
110  *        anna::Recycler<MyAvp> a_avps;
111  *        anna::Recycler<MyMessage> a_messages;
112  *
113  *        anna::diameter::codec::Avp* allocateAvp () throw () { return a_avps.create (); }
114  *
115  *        void releaseAvp (anna::diameter::codec::Avp* avp) throw () {
116  *             if (avp == NULL) return;
117  *             MyAvp* aux = static_cast <MyAvp*> (avp);
118  *             aux->clear(); // free internal data-part storage specially for grouped avps which will release its childrens
119  *             a_avps.release (aux);
120  *        }
121  *
122  *        anna::diameter::codec::Message* allocateMessage () throw () { return a_messages.create (); }
123  *
124  *        void releaseMessage (anna::diameter::codec::Message* message) throw () {
125  *             if (message == NULL) return;
126  *             MyMessage* aux = static_cast <MyMessage*> (message);
127  *             aux->clear(); // free internal data-part storage specially for childrens releasing
128  *             a_messages.release (aux);
129  *        }
130  *     };
131  *
132  *  \endcode
133  */
134 class EngineImpl : public anna::Component {
135
136 public:
137
138   /**
139    * Defines behaviour on validation procedure: complete analysis or stop at first validation error over the message (by default)
140    */
141   struct ValidationDepth { enum _v { Complete, FirstError /* default */ }; };
142
143   /**
144    * Defines behaviour mode regarding when to validate a message: before encoding, after decoding (by default), always or never
145    * Anyway validation procedure may be called at any moment (#valid)
146    */
147   struct ValidationMode { enum _v { BeforeEncoding, AfterDecoding /* default */, Always, Never /* optimization */ }; };
148
149   /**
150    * Defines behaviour mode regarding when to fix a message: before encoding (by default), after decoding, always or never.
151    * An application could add Avps in any order; the fix procedure try to adjust it regarding dictionary. I.e., fixed
152    *  Avps will be placed on first position, before mandatory and optional ones, within the message level or any
153    *  grouped Avp. Usually we need to configure fixing before encoding in order to provide flexibility to the application
154    *  during message construction, but actually, optimal mode implies disabling this procedure. Fixing after decoding will
155    *  hide any validation problem regarding Avps position at any level.
156    * Anyway fix procedure may be called at any moment (#fix)
157    */
158   struct FixMode { enum _v { BeforeEncoding /* default */, AfterDecoding, Always, Never /* optimization */ }; };
159
160
161   // Creators
162   Avp* createAvp(const AvpId *id) throw(anna::RuntimeException);
163   Message* createMessage(const CommandId *id) throw(anna::RuntimeException);
164
165
166 private:
167
168   ValidationDepth::_v a_validationDepth;
169   ValidationMode::_v a_validationMode;
170   bool a_singleFailedAVP;
171   bool a_ignoreFlags;
172   FixMode::_v a_fixMode;
173
174   // Auxiliary
175   const stack::Dictionary * a_dictionary;
176
177   // helpers
178   static const char* asText(const ValidationDepth::_v) throw();
179   static const char* asText(const ValidationMode::_v) throw();
180   static const char* asText(const FixMode::_v) throw();
181
182 public:
183
184   /** Constructor
185       @param className Logical name for the class.
186       @param dictionary Diameter dictionary. At single threaded processes, the same codec engine could be used with
187       different diameter dictionaries (multi-stack applications). In that case the process must switch the stack for
188       the whole decoding or enconding operation over a Message depending on the context (normally the message header
189       Application-Id is used as stack identifier). But the smart way implies inherit from this engine creating a
190       component for each diameter stack managed in the application. Inheritance is mandatory in multi-threaded processes:
191       one engine, a unique stack.
192    */
193   EngineImpl(const char* className, const stack::Dictionary * dictionary);
194
195   /**
196    * Destructor
197    */
198   virtual ~EngineImpl() {;}
199
200
201   /**
202      Gets currently configured dictionary. NULL if not configured (manual encode/decode operations).
203
204      @return Returns currently configured engine dictionary
205   */
206   const stack::Dictionary *getDictionary() const throw() { return a_dictionary; }
207
208
209   /**
210    * Sets behaviour on validation procedure.
211    * \param validationDepth Behaviour on validation procedure: complete analysis or stop at first validation error over the message.
212    */
213   void setValidationDepth(const ValidationDepth::_v validationDepth)  throw() { a_validationDepth = validationDepth; }
214
215   /**
216    * Returns behaviour on on validation procedure.
217    * For practical purposes, the Failed-AVP would typically refer to the first AVP processing error that a Diameter node encounters
218    * (decoding error or validation error in this case).
219    * A complete validation depth incurs on multiple-content Failed-AVP and is perhaps useful during integration tasks.
220    *
221    * \return Behaviour on validation procedure: complete analysis or stop at first validation error over the message (by default).
222    */
223   ValidationDepth::_v getValidationDepth() const throw() { return a_validationDepth; }
224
225   /**
226    * Sets behaviour on validation procedure regarding stack flags. Actually, only AVP flags M & P are affected. The vendor bit is
227    * too important to be ignored, and there is no way to check operation flags (as request bit).
228    * By default (at engine start), flags are verified.
229    * \param ignoreFlags Validation will ignore flags.
230    */
231
232   void ignoreFlagsOnValidation(bool ignoreFlags) throw() { a_ignoreFlags = ignoreFlags; }
233
234   /**
235    * Gets behaviour on validation procedure regarding stack flags. Actually, only AVP flags M & P are affected. The vendor bit is
236    * too important to be ignored, and there is no way to check operation flags (as request bit).
237    * By default (at engine start), flags are verified.
238    * \return Validation ignore flags indicator.
239    */
240   bool ignoreFlagsOnValidation() const throw() { return a_ignoreFlags; }
241
242   /**
243    * Sets validation mode.
244    * \param validationMode Validation mode: before encoding, after decoding, always or never.
245    */
246   void setValidationMode(const ValidationMode::_v validationMode)  throw() { a_validationMode = validationMode; }
247
248   /**
249    * Returns validation mode.
250    * Before coding validation mode is perhaps useful during debugging tasks, i.e. to check answer messages built by the application
251    * during development phase.
252    * \return Validation mode: before encoding, after decoding (by default), always or never.
253    */
254   ValidationMode::_v getValidationMode() const throw() { return a_validationMode; }
255
256
257
258   /**
259    * Sets fix mode.
260    * \param fixMode Fix mode: before encoding, after decoding, always or never.
261    */
262   void setFixMode(const FixMode::_v fixMode)  throw() { a_fixMode = fixMode; }
263
264   /**
265    * Returns fix mode.
266    * \return Fix mode: before encoding (by default), after decoding, always or never.
267    */
268   FixMode::_v getFixMode() const throw() { return a_fixMode; }
269
270   /**
271    * Sets single FailedAVP. True by default. If false, and more than one wrong avp are found during message
272    * decoding and or validation, a new Failed-AVP will be added to the dynamic answer provided. The standard
273    * talks about only one but it is open to do this.
274    *
275    * \param single Single Failed-AVP boolean.
276    */
277   void setSingleFailedAVP(bool single = true)  throw() { a_singleFailedAVP = single; }
278
279   /**
280    * Returns single Failed-AVP boolean.
281    * \return Failed-AVP could be one (true) or more (false) in answer message.
282    */
283   bool getSingleFailedAVP() const throw() { return a_singleFailedAVP; }
284
285   /**
286   * Creates a new diameter avp assigning its identifier, using engine resources to allocate memory (recommended
287   *  recycler allocation at engine component re-implementation of allocator methods). Obviously, normal objects
288   *  creation (new) is possible.
289   *
290   * @param id Avp identifier. AVP flags will be established based on active dictionary for known avps, or
291   * uninitialized for unknown ones.
292   *
293   * @return Created avp ready to be used
294   */
295   Avp* createAvp(AvpId id) throw(anna::RuntimeException) { return createAvp(&id); }
296
297   /**
298   * Creates a new diameter avp, using engine resources to allocate memory (recommended recycler allocation at
299   *  engine component re-implementation of allocator methods). Obviously, normal objects creation (new) is possible.
300   *
301   * @return Created avp ready to be used
302   */
303   Avp* createAvp() throw(anna::RuntimeException) { return createAvp(NULL); }
304
305   /**
306   * Creates a new diameter Message assigning its identifier, using engine resources to allocate memory (recommended
307   *  recycler allocation at engine component re-implementation of allocator methods). Obviously, normal objects
308   *  creation (new) is possible.
309   *
310   * @param id Command identifier. Message flags will be established based on active dictionary for known commands,
311   *  or uninitialized for unknown ones.
312   *
313   * @return Created message ready to be used
314   */
315   Message* createMessage(CommandId id) throw(anna::RuntimeException) { return createMessage(&id); }
316
317   /**
318   * Creates a new diameter message, using engine resources to allocate memory (recommended recycler allocation
319   *  at engine component re-implementation of allocator methods). Obviously, normal objects creation (new) is possible.
320   *
321   * @return Created message ready to be used
322   */
323   Message* createMessage() throw(anna::RuntimeException) { return createMessage(NULL); }
324
325
326   /**
327      Loads an xml file representing a diameter message base in a DTD document (#getDTD)
328
329      @param xmlPathFile Complete path file to the xml document which represents the diameter message
330   */
331   Message *createMessage(const std::string & xmlPathFile) throw(anna::RuntimeException);
332
333
334   /**
335      Invoked to free Avps.
336      \see anna::Recycler
337   */
338   virtual void releaseAvp(Avp*) throw() = 0;
339
340   /**
341      Invoked to free Messages.
342      \see anna::Recycler
343   */
344   virtual void releaseMessage(Message*) throw() = 0;
345
346
347   /**
348   * Class string representation
349   *
350   * @return String with class content
351   */
352   virtual std::string asString(void) const throw();
353
354   /**
355      Class XML representation.
356      \param parent XML node over which we will put instance information.
357      \return XML documentcon with class content.
358   */
359   virtual anna::xml::Node* asXML(anna::xml::Node* parent) const throw();
360
361
362   /**
363      Gets the Avp identifier providing its logical name at engine dictionary
364
365      @param name Name of the Avp at engine dictionary
366
367      @return Avp identifier as pair (code,vendor-id)
368   */
369   AvpId avpIdForName(const char * name) throw(anna::RuntimeException);
370
371
372   /**
373      Gets the Command identifier providing its logical name at engine dictionary
374
375      @param name Name of the Command at engine dictionary
376
377      @return Command identifier as pair (code,request-indicator)
378   */
379   CommandId commandIdForName(const char * name) throw(anna::RuntimeException);
380
381
382 protected:
383
384   /**
385      Avp allocator method.
386
387      It is recommended to use anna::Recycler for Avps creation/releasing.
388
389      \see anna::Recycler
390   */
391   virtual Avp* allocateAvp() throw() = 0;
392
393
394   /**
395      Message allocator method.
396
397      It is recommended to use anna::Recycler for Message creation/releasing.
398
399      \see anna::Recycler
400   */
401   virtual Message* allocateMessage() throw() = 0;
402
403
404   /**
405      Manages warning trace or exception on validation anomaly depending on ValidationDepth configuration
406      ('complete' and 'first error' reports respectively).
407
408      @description Anomaly description used in trace or exception
409
410      @see setValidationDepth
411      @see getValidationDepth
412   */
413   void validationAnomaly(const std::string & description) const throw(anna::RuntimeException);
414 };
415
416 }
417 }
418 }
419
420 #endif
421