Internal clear respecting codec engine

[anna.git] / include / anna / diameter / codec / Message.hpp

diff --git a/include/anna/diameter/codec/Message.hpp b/include/anna/diameter/codec/Message.hpp
index 4c3e6e6..27ee6da 100644 (file)
--- a/include/anna/diameter/codec/Message.hpp
+++ b/include/anna/diameter/codec/Message.hpp
@@ -180,16 +180,24 @@ public:
   *
   * Once assigned (here or at constructor), this method SHALL NOT be used anymore.
   * Also, the associated dictionary SHOULD NOT BE CHANGED through the engine,
-  * unless you know what are you doing. If you want to reconfigure the engine,
-  * first #clear the message and then you could reuse the same object with
-  * different configurations (execution contexts).
-  *
+  * unless you know what are you doing.
   * Setting a new different engine with different stack, even same engine where the
   * stack has been dynamically changed, could cause a bad behaviour depending on the
   * changes: in general, if the dictionary grows, nothing bad will happen, but if
   * you remove or modified some elements which were processed with a certain format,
   * will be interpreted as 'unknown' with the new dictionary, and then some problems
   * may occur. If you add elements (vendors, avps, messages) is not a problem.
+  *
+  * IMPORTANT NOTES:
+  * 1) if you want to reuse the message, as a recommendation, you should set engine to
+  * NULL or use #clear. In that way, next operation will adjust automatically the needed
+  * engine because it would not be configured in such stage.
+  * 2) if you want to pre-configure the engine you will need to set the engine to NULL
+  * previously and then you could change to the new one without warning/ignoring.
+  * 3) if you have dedicated message objects for each interface (application id), then
+  * you could set the corresponding engine on constructor (or setEngine), and forget
+  * about #clear. The needed cleanup will be done automatically from decoding and xml
+  * loading procedures, and initialized engine will be kept along message operations.
   */
   void setEngine(Engine *engine) throw();
 
@@ -493,8 +501,13 @@ public:
   * Application must clear auxiliary message objects before adding Avps in a new context if the same object is reused.
   * Application don't need to clear a message object before decode operation (decode invokes #clear before any other task).
   * Any reimplementation must first invoke base class method.
+  *
+  * @param resetEngine Sets to NULL the codec engine (true, default) or respect its current value (false). If you are going
+  * to reuse the message instance it is better to clear all the information (default) to manage different stacks, because if
+  * you don't initialize the engine to NULL, the second use of the message will keep the same engine deduced from the first
+  * decoding/loading operation, which could be wrong if the second message belongs to a different application identifier.
   */
-  virtual void clear() throw(anna::RuntimeException);
+  virtual void clear(bool resetEngine = true) throw(anna::RuntimeException);
 
   /**
      Decodes buffer provided over class content. If an error ocurred, decoding will stop launching exception (fatal error) or a warning trace (perhaps the achieved