1 // ANNA - Anna is Not Nothingness Anymore
3 // (c) Copyright 2005-2014 Eduardo Ramos Testillano & Francisco Ruiz Rayo
5 // http://redmine.teslayout.com/projects/anna-suite
7 // Redistribution and use in source and binary forms, with or without
8 // modification, are permitted provided that the following conditions
11 // * Redistributions of source code must retain the above copyright
12 // notice, this list of conditions and the following disclaimer.
13 // * Redistributions in binary form must reproduce the above
14 // copyright notice, this list of conditions and the following disclaimer
15 // in the documentation and/or other materials provided with the
17 // * Neither the name of the copyright holder nor the names of its
18 // contributors may be used to endorse or promote products derived from
19 // this software without specific prior written permission.
21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 // Authors: eduardo.ramos.testillano@gmail.com
34 // cisco.tierra@gmail.com
37 #ifndef anna_diameter_stack_Engine_hpp
38 #define anna_diameter_stack_Engine_hpp
42 #include <anna/diameter/stack/Dictionary.hpp>
44 #include <anna/xml/DTDMemory.hpp>
45 #include <anna/core/RuntimeException.hpp>
46 #include <anna/core/Singleton.hpp>
61 //------------------------------------------------------------------------------
62 //----------------------------------------------------------------- class Engine
63 //------------------------------------------------------------------------------
67 class Engine : public anna::Singleton <Engine> {
70 const anna::xml::DTDMemory * getDictionariesDTD() const throw() { return &a_dtd; }
74 typedef std::map<unsigned int, Dictionary*> stack_container;
75 typedef stack_container::const_iterator const_stack_iterator;
76 typedef stack_container::iterator stack_iterator;
81 * Returns the dictionary registered with the provided identifier, which commonly
82 * is the 'Application-Id'.
84 * @param stackId Stack identifier.
85 * @return Dictionary reference, NULL if no stack found
87 const Dictionary * getDictionary(unsigned int stackId) const throw();
89 /** Beginning stack iterator */
90 const_stack_iterator stack_begin() const throw() { return a_stacks.begin(); }
91 /** Ending stack iterator */
92 const_stack_iterator stack_end() const throw() { return a_stacks.end(); }
94 int stack_size() const throw() { return a_stacks.size(); }
98 * Gets boolean about empty stack condition
100 * @return Boolean about empty stack condition
102 bool isEmpty(void) const throw() { return (!a_stacks.size()); }
105 * Class string representation
107 * @param all Complete engine information versus only stacks list with its ids and dictionary names
109 * @return String with class content
111 std::string asString(bool all = true) const throw();
116 * Creates a diameter dictionary based on xml document file and store it over the provided stack identifier.
117 * If the stack is currently used, an exception will be launched to notify the stack collision (a dictionary
118 * could be removed with #removeStack).
119 * If missing xml path file, the dictionary will be created without loading data.
122 * Method 1 - Create and load xml data (commonly used for mono-load stacks):
123 * engine->createDictionary(MMS_STACK_ID, "/var/tmp/mms.xml");
125 * Method 2 - Create and then, load xml data (useful for multi-load stacks):
126 * Dictionary * d = engine->createDictionary(MMS_STACK_ID);
128 * d->load("/var/tmp/mms.xml");
130 * Method 3 - Create and then, load data through Dictionary API (*):
131 * Dictionary * d = engine->createDictionary(MMS_STACK_ID);
137 * (*) Applications could create a dictionary with its own API (#Dictionary) but it is much more difficult,
138 * and usually, the method version with xml document load is used instead of this.
142 * @param stackId Stack identifier for created dictionary. We recommend to use the Diameter 'Application-Id' unless
143 * the application is going to use dictionaries covering different applications (which is not very usual).
144 * @param xmlPathFile Path file to the xml document which represents the diameter dictionary.
146 * @return Dictionary registered. When exception happen, dictionary can be accessed by #getDictionary
148 Dictionary * createDictionary(unsigned int stackId, const std::string & xmlPathFile = "") throw(anna::RuntimeException);
151 * Register a externally created Dictionary or a derived class from Dictionary
153 * @param stackId Stack identifier for provided dictionary. We recommend to use the Diameter 'Application-Id' unless
154 * the application is going to use dictionaries covering different applications (which is not very usual).
155 * @param dictionary Externally created dictionary
157 * @return Dictionary registered. When exception happen, dictionary can be accessed by #getDictionary
159 Dictionary * registerDictionary(unsigned int stackId, Dictionary *dictionary) throw(anna::RuntimeException);
162 * Loads an XML dictionary document over the diameter stack identifiers (one or more stack id's).
163 * Passing more than one stack id, synchronized loadings are performed, which could be useful when
164 * an application loads many dictionaries with common avps.
166 * @param stacks Stacks identifiers over which the dictionary will be load.
167 * @param xmlPathFile Path file to the xml document which represents the diameter dictionary.
169 void loadDictionary(const std::vector<unsigned int> & stacks, const std::string & xmlPathFile) throw(anna::RuntimeException);
172 * Loads an XML dictionary document over all the diameter engine registered stacks. When more than one stack id is
173 * used, synchronized loadings are performed, which could be useful when an application loads many dictionaries with
176 * @param xmlPathFile Path file to the xml document which represents the diameter dictionary.
178 void loadDictionary(const std::string & xmlPathFile) throw(anna::RuntimeException);
181 * Remove all stacks registered on diameter stack engine
183 void removeStacks(void) throw() { a_stacks.clear(); }
186 * Remove the stack provided.
188 * @param stackId Stack identifier for created dictionary
190 void removeStack(unsigned int stackId) throw();
194 anna::xml::DTDMemory a_dtd;
195 stack_container a_stacks;
199 friend class anna::Singleton <Engine>;
200 friend class Dictionary; // access to 'getDictionariesDTD()'