#ifndef _utl_deprecator_h_
#define _utl_deprecator_h_

#include <string>
#include <map>
#include <utl/AugerException.h>
#include <utl/Singleton.h>


namespace utl {

  /**
    \class Deprecator Deprecator.h utl/Deprecator.h
    \brief Class to collect and provide information about deprecated class
    interfaces.

    A central deprecation log is used to collect the information about all uses
    of deprecated interfaces. Use the Deprecator::GetInstance() call to get
    a reference to the central deprecation log. The member function Deprecated()
    is used to log the use of a deprecated interface. At the end of the run,
    use GetReport() to obtain a string reporting the deprecated interface uses.

    \code
    class c {
    public:
      void
      NewInterface();

      void
      OldInterface
      {
        Deprecator::GetInstance().Deprecated("OldInterface", "v9r3",
          "See documentation page 3, use NewInterface");
        NewInterface();
    };
    \endcode

    \note If an interface gets deprecated, it should also get marked as such in
    the doxygen documentation using the \\deprecated command. The documentation
    should include the time when the interface is expected to go away. This
    information might also get listed in the hint argument of the Deprecated()
    call.

    \note If needed, on could add other reporting facilities to get the
    report in XML format or to get the raw data.

    \author Lukas Nellen
    \date 22 Jan 2008

    \ingroup utilities
  */

  class Deprecator : public Singleton<Deprecator> {
  public:
    /// Constructor
    /**
      \note The constructor is not protected to make it possible to create
      instances of the class for testing. For use in a real application, use
      the static GetInstance() function to get the central deprecation register.
     */
    Deprecator() { }

    /// Log the usage of a deprecated interface and emit a warning.
    /**
       \param theInterface The name of the deprecated interface
       \param theVersion The version where this interface got deprecated in
       \param theNewUsageHint Information about what to do in the future
     */
    void Deprecated(const std::string& theInterface,
                    const std::string& theVersion,
                    const std::string& theNewUsageHint);

    /// Check if empty, i.e., no deprecated usage registered
    bool IsEmpty() const
    { return fData.empty(); }

    /// Size, i.e., number of different deprecated interfaces uses
    std::size_t GetSize() const
    { return fData.size(); }

    /// Get the final report on interface usage problems
    std::string GetReport() const;

  private:
    /// Information about the deprecated interface
    class DeprecationInfo {
    public:
      DeprecationInfo(const std::string& theHint,
                      const std::string& theVersion)
        : fHint(theHint),
          fVersion(theVersion),
          fCount(1)
        { }

      void IncrementUsage()
      { ++fCount; }

      const std::string& GetHint() const
      { return fHint; }

      const std::string& GetVersion() const
      { return fVersion; }

      std::size_t GetCount() const
      { return fCount; }
    private:
      /// Hint what to do to avoid deprecated interface
      std::string fHint;
      /// Version since when this interface is deprecated
      std::string fVersion;
      /// Count of uses of deprecated interface
      std::size_t fCount;
    };

    typedef std::map<std::string, DeprecationInfo> DataMap;
    DataMap fData;
  };
}

#endif