diff options
Diffstat (limited to 'src/lib/log/message_dictionary.h')
| -rw-r--r-- | src/lib/log/message_dictionary.h | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/src/lib/log/message_dictionary.h b/src/lib/log/message_dictionary.h new file mode 100644 index 0000000..6afc0f0 --- /dev/null +++ b/src/lib/log/message_dictionary.h @@ -0,0 +1,208 @@ +// 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 |