/src/kea/src/lib/log/message_dictionary.h

Source
// Copyright (C) 2011-2016 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.

#ifndef MESSAGE_DICTIONARY_H
#define MESSAGE_DICTIONARY_H

#include <cstddef>
#include <string>
#include <map>
#include <vector>

#include <boost/lexical_cast.hpp>
#include <boost/shared_ptr.hpp>

#include <log/message_types.h>

namespace isc {
namespace log {

/// \brief Forward declaration of \c MessageDictionary
class MessageDictionary;

/// \brief Shared pointer to the \c MessageDictionary.
typedef boost::shared_ptr<MessageDictionary> MessageDictionaryPtr;

/// \brief Message Dictionary
///
/// The message dictionary is a wrapper around a std::map object, and allows
/// message text to be retrieved given the string identification.
///
/// Adding text occurs in two modes:
///
/// Through the "Add" method, ID/text mappings are added to the dictionary
/// unless the ID already exists.  This is designed for use during program
/// initialization, where a local message may supplant a compiled-in message.
///
/// Through the "Replace" method, ID/text mappings are added to the dictionary
/// only if the ID already exists.  This is for use when a message file is
/// supplied to replace messages provided with the program.
///
/// Although the class can be used stand-alone, it does supply a static method
/// to return a particular instance - the "global" dictionary.

class MessageDictionary {
public:

    typedef std::map<std::string, std::string> Dictionary;
    typedef Dictionary::const_iterator  const_iterator;

    /// \brief Constructor
    MessageDictionary();

    /// \brief Virtual Destructor
    virtual ~MessageDictionary();

    /// \brief Add Message
    ///
    /// Adds a message to the dictionary.  If the ID already exists, the ID is
    /// added to the overflow vector.
    ///
    /// \param ident Identification of the message to add
    /// \param text Message text
    ///
    /// \return true if the message was added to the dictionary, false if the
    /// message existed and it was not added.
    virtual bool add(const MessageID& ident, const std::string& text) {
        return (add(boost::lexical_cast<std::string>(ident), text));
    }

    /// \brief Add Message
    ///
    /// Alternate signature.
    ///
    /// \param ident Identification of the message to add
    /// \param text Message text
    ///
    /// \return true if the message was added to the dictionary, false if the
    /// message existed and it was not added.
    virtual bool add (const std::string& ident, const std::string& text);


    /// \brief Replace Message
    ///
    /// Replaces a message in the dictionary.  If the ID does not exist, it is
    /// added to the overflow vector.
    ///
    /// \param ident Identification of the message to replace
    /// \param text Message text
    ///
    /// \return true if the message was added to the dictionary, false if the
    /// message did not exist and it was not added.
    virtual bool replace(const MessageID& ident, const std::string& text) {
        return (replace(boost::lexical_cast<std::string>(ident), text));
    }

    /// \brief Replace Message
    ///
    /// Alternate signature.
    ///
    /// \param ident Identification of the message to replace
    /// \param text Message text
    ///
    /// \return true if the message was added to the dictionary, false if the
    /// message did not exist and it was not added.
    virtual bool replace(const std::string& ident, const std::string& text);


    /// \brief Removes the specified message from the dictionary.
    ///
    /// Checks if both the message identifier and the text match the message
    /// in the dictionary before removal. If the text doesn't match it is
    /// an indication that the message which removal is requested is a
    /// duplicate of another message. This may occur when two Kea modules
    /// register messages with the same identifier. When one of the modules
    /// is unloaded and the relevant messages are unregistered, there is a
    /// need to make sure that the message registered by the other module
    /// is not accidentally removed. Hence, the additional check for the
    /// text match is needed.
    ///
    /// \param ident Identification of the message to remove.
    /// \param text Message text
    ///
    /// \return true of the message has been removed, false if the message
    /// couldn't be found.
    virtual bool erase(const std::string& ident, const std::string& text);

    /// \brief Load Dictionary
    ///
    /// Designed to be used during the initialization of programs, this
    /// accepts a set of (ID, text) pairs as a one-dimensional array of
    /// const char* and adds them to the dictionary.  The messages are added
    /// using "Add".
    ///
    /// \param elements null-terminated array of const char* alternating ID and
    /// message text.  This should be an odd number of elements long, the last
    /// element being NULL.  If it is an even number of elements long, the
    /// last ID is ignored.
    ///
    /// \return Vector of message IDs that were not loaded because an ID of the
    /// same name already existing in the dictionary.  This vector may be
    /// empty.
    virtual std::vector<std::string> load(const char* elements[]);

    /// \brief Get Message Text
    ///
    /// Given an ID, retrieve associated message text.
    ///
    /// \param ident Message identification
    ///
    /// \return Text associated with message or empty string if the ID is not
    /// recognized.  (Note: this precludes an ID being associated with an empty
    /// string.)
    virtual const std::string& getText(const MessageID& ident) const {
        return(getText(boost::lexical_cast<std::string>(ident)));
    }


    /// \brief Get Message Text
    ///
    /// Alternate signature.
    ///
    /// \param ident Message identification
    ///
    /// \return Text associated with message or empty string if the ID is not
    /// recognized.  (Note: this precludes an ID being associated with an empty
    /// string.)
    virtual const std::string& getText(const std::string& ident) const;


    /// \brief Number of Items in Dictionary
    ///
    /// \return Number of items in the dictionary
    virtual size_t size() const {
        return (dictionary_.size());
    }


    /// \brief Return begin() iterator of internal map
    const_iterator begin() const {
        return (dictionary_.begin());
    }


    /// \brief Return end() iterator of internal map
    const_iterator end() const {
        return (dictionary_.end());
    }


    /// \brief Return Global Dictionary
    ///
    /// Returns a pointer to the singleton global dictionary.
    ///
    /// \return Pointer to global dictionary.
    static const MessageDictionaryPtr& globalDictionary();

private:
    Dictionary       dictionary_;   ///< Holds the ID to text lookups
    const std::string empty_;       ///< Empty string
};

} // namespace log
} // namespace isc

#endif // MESSAGE_DICTIONARY_H

Coverage Report

Created: 2026-07-14 08:11

Line	Count	Source
1		// Copyright (C) 2011-2016 Internet Systems Consortium, Inc. ("ISC")
2		//
3		// This Source Code Form is subject to the terms of the Mozilla Public
4		// License, v. 2.0. If a copy of the MPL was not distributed with this
5		// file, You can obtain one at http://mozilla.org/MPL/2.0/.
6
7		#ifndef MESSAGE_DICTIONARY_H
8		#define MESSAGE_DICTIONARY_H
9
10		#include <cstddef>
11		#include <string>
12		#include <map>
13		#include <vector>
14
15		#include <boost/lexical_cast.hpp>
16		#include <boost/shared_ptr.hpp>
17
18		#include <log/message_types.h>
19
20		namespace isc {
21		namespace log {
22
23		/// \brief Forward declaration of \c MessageDictionary
24		class MessageDictionary;
25
26		/// \brief Shared pointer to the \c MessageDictionary.
27		typedef boost::shared_ptr<MessageDictionary> MessageDictionaryPtr;
28
29		/// \brief Message Dictionary
30		///
31		/// The message dictionary is a wrapper around a std::map object, and allows
32		/// message text to be retrieved given the string identification.
33		///
34		/// Adding text occurs in two modes:
35		///
36		/// Through the "Add" method, ID/text mappings are added to the dictionary
37		/// unless the ID already exists. This is designed for use during program
38		/// initialization, where a local message may supplant a compiled-in message.
39		///
40		/// Through the "Replace" method, ID/text mappings are added to the dictionary
41		/// only if the ID already exists. This is for use when a message file is
42		/// supplied to replace messages provided with the program.
43		///
44		/// Although the class can be used stand-alone, it does supply a static method
45		/// to return a particular instance - the "global" dictionary.
46
47		class MessageDictionary {
48		public:
49
50		typedef std::map<std::string, std::string> Dictionary;
51		typedef Dictionary::const_iterator const_iterator;
52
53		/// \brief Constructor
54		MessageDictionary();
55
56		/// \brief Virtual Destructor
57		virtual ~MessageDictionary();
58
59		/// \brief Add Message
60		///
61		/// Adds a message to the dictionary. If the ID already exists, the ID is
62		/// added to the overflow vector.
63		///
64		/// \param ident Identification of the message to add
65		/// \param text Message text
66		///
67		/// \return true if the message was added to the dictionary, false if the
68		/// message existed and it was not added.
69	25.2k	virtual bool add(const MessageID& ident, const std::string& text) {
70	25.2k	return (add(boost::lexical_cast<std::string>(ident), text));
71	25.2k	}
72
73		/// \brief Add Message
74		///
75		/// Alternate signature.
76		///
77		/// \param ident Identification of the message to add
78		/// \param text Message text
79		///
80		/// \return true if the message was added to the dictionary, false if the
81		/// message existed and it was not added.
82		virtual bool add (const std::string& ident, const std::string& text);
83
84
85		/// \brief Replace Message
86		///
87		/// Replaces a message in the dictionary. If the ID does not exist, it is
88		/// added to the overflow vector.
89		///
90		/// \param ident Identification of the message to replace
91		/// \param text Message text
92		///
93		/// \return true if the message was added to the dictionary, false if the
94		/// message did not exist and it was not added.
95	0	virtual bool replace(const MessageID& ident, const std::string& text) {
96	0	return (replace(boost::lexical_cast<std::string>(ident), text));
97	0	}
98
99		/// \brief Replace Message
100		///
101		/// Alternate signature.
102		///
103		/// \param ident Identification of the message to replace
104		/// \param text Message text
105		///
106		/// \return true if the message was added to the dictionary, false if the
107		/// message did not exist and it was not added.
108		virtual bool replace(const std::string& ident, const std::string& text);
109
110
111		/// \brief Removes the specified message from the dictionary.
112		///
113		/// Checks if both the message identifier and the text match the message
114		/// in the dictionary before removal. If the text doesn't match it is
115		/// an indication that the message which removal is requested is a
116		/// duplicate of another message. This may occur when two Kea modules
117		/// register messages with the same identifier. When one of the modules
118		/// is unloaded and the relevant messages are unregistered, there is a
119		/// need to make sure that the message registered by the other module
120		/// is not accidentally removed. Hence, the additional check for the
121		/// text match is needed.
122		///
123		/// \param ident Identification of the message to remove.
124		/// \param text Message text
125		///
126		/// \return true of the message has been removed, false if the message
127		/// couldn't be found.
128		virtual bool erase(const std::string& ident, const std::string& text);
129
130		/// \brief Load Dictionary
131		///
132		/// Designed to be used during the initialization of programs, this
133		/// accepts a set of (ID, text) pairs as a one-dimensional array of
134		/// const char* and adds them to the dictionary. The messages are added
135		/// using "Add".
136		///
137		/// \param elements null-terminated array of const char* alternating ID and
138		/// message text. This should be an odd number of elements long, the last
139		/// element being NULL. If it is an even number of elements long, the
140		/// last ID is ignored.
141		///
142		/// \return Vector of message IDs that were not loaded because an ID of the
143		/// same name already existing in the dictionary. This vector may be
144		/// empty.
145		virtual std::vector<std::string> load(const char* elements[]);
146
147		/// \brief Get Message Text
148		///
149		/// Given an ID, retrieve associated message text.
150		///
151		/// \param ident Message identification
152		///
153		/// \return Text associated with message or empty string if the ID is not
154		/// recognized. (Note: this precludes an ID being associated with an empty
155		/// string.)
156	915k	virtual const std::string& getText(const MessageID& ident) const {
157	915k	return(getText(boost::lexical_cast<std::string>(ident)));
158	915k	}
159
160
161		/// \brief Get Message Text
162		///
163		/// Alternate signature.
164		///
165		/// \param ident Message identification
166		///
167		/// \return Text associated with message or empty string if the ID is not
168		/// recognized. (Note: this precludes an ID being associated with an empty
169		/// string.)
170		virtual const std::string& getText(const std::string& ident) const;
171
172
173		/// \brief Number of Items in Dictionary
174		///
175		/// \return Number of items in the dictionary
176	0	virtual size_t size() const {
177	0	return (dictionary_.size());
178	0	}
179
180
181		/// \brief Return begin() iterator of internal map
182	0	const_iterator begin() const {
183	0	return (dictionary_.begin());
184	0	}
185
186
187		/// \brief Return end() iterator of internal map
188	0	const_iterator end() const {
189	0	return (dictionary_.end());
190	0	}
191
192
193		/// \brief Return Global Dictionary
194		///
195		/// Returns a pointer to the singleton global dictionary.
196		///
197		/// \return Pointer to global dictionary.
198		static const MessageDictionaryPtr& globalDictionary();
199
200		private:
201		Dictionary dictionary_; ///< Holds the ID to text lookups
202		const std::string empty_; ///< Empty string
203		};
204
205		} // namespace log
206		} // namespace isc
207
208		#endif // MESSAGE_DICTIONARY_H