Line data    Source code

       1             : #ifndef _ATM_EXCEPTIONS_H
       2             : #define _ATM_EXCEPTIONS_H
       3             : 
       4             : /****************************************************************************
       5             :  * ALMA - Atacama Large Millimiter Array
       6             :  * (c) Instituto de Estructura de la Materia, 2009
       7             :  *
       8             :  * This library is free software; you can redistribute it and/or
       9             :  * modify it under the terms of the GNU Lesser General Public
      10             :  * License as published by the Free Software Foundation; either
      11             :  * version 2.1 of the License, or (at your option) any later version.
      12             :  *
      13             :  * This library is distributed in the hope that it will be useful,
      14             :  * but WITHOUT ANY WARRANTY; without even the implied warranty of
      15             :  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      16             :  * Lesser General Public License for more details.
      17             :  *
      18             :  * You should have received a copy of the GNU Lesser General Public
      19             :  * License along with this library; if not, write to the Free Software
      20             :  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
      21             :  *
      22             :  * "@(#) $Id: ATMException.h Exp $"
      23             :  *
      24             :  * who       when      what
      25             :  * --------  --------  ----------------------------------------------
      26             :  * jroche    09/09/09  created
      27             :  */
      28             : 
      29             : #ifndef __cplusplus
      30             : #error "This is a C++ include file and cannot be used from plain C"
      31             : #endif
      32             : 
      33             : #include "ATMCommon.h" 
      34             : #include <exception>
      35             : #include <string>
      36             : 
      37             : using std::string;
      38             : 
      39             : ATM_NAMESPACE_BEGIN
      40             : 
      41             : /**
      42             :  * @class AtmException
      43             :  * @brief Manage exceptions that raises in ATM.
      44             :  *
      45             :  * @remarks Don't use a STL container (particularly a std::string) in a catch
      46             :  * block of a TelCal exception class because the container may dynamically
      47             :  * allocate the memory and so raise a std::exception if the case of
      48             :  * std::bad_alloc exception.
      49             :  *
      50             :  * To create a AtmException follow the example. The #ATM_EXCEPTION_ARGS macro
      51             :  * must be used to define the position (file, method and line) where the
      52             :  * exception is raised.
      53             :  * First include the header file for exceptions.
      54             :  *
      55             :  * @code
      56             :  *  #include "ATMException.h"
      57             :  * @endcode
      58             :  *
      59             :  * Then create an exception object in a try block. Possibly insert here a log
      60             :  * message.
      61             :  *
      62             :  * @code
      63             :  *  try
      64             :  *  {
      65             :  *    if(something wrong)
      66             :  *    {
      67             :  *      throw atm::AtmException(ATM_EXCEPTION_ARGS("A message."));
      68             :  *    }
      69             :  *  }
      70             :  * @endcode
      71             :  *
      72             :  * If you don't want to indicate the location in the log message then use the
      73             :  * message() method instead of what().
      74             :  * Finally catch the exception.
      75             :  *
      76             :  * @code
      77             :  *  catch(const atm::AtmException &e)
      78             :  *  {
      79             :  *    // do something like destroy the allocated memory in the try block...
      80             :  *    throw e;
      81             :  *  }
      82             :  * @endcode
      83             :  *
      84             :  * In this catch block you can also modify the exception before throwing it. To
      85             :  * do it remove the const keyword in the catch call.
      86             :  *
      87             :  * The message may be formated using a stream. So first include the needed
      88             :  * stream library.
      89             :  *
      90             :  * @code
      91             :  *  #include "ATMException.h"
      92             :  *  #include <sstream>
      93             :  * @endcode
      94             :  *
      95             :  * Format the message like the following example where x is a variable of
      96             :  * miscellaneous type. See following web links:
      97             :  * @li ostringstream class: http://www.cplusplus.com/reference/iostream/ostringstream
      98             :  * @li ostream::operator<< operator: http://www.cplusplus.com/reference/iostream/ostream/operator%3C%3C.html
      99             :  *
     100             :  * @code
     101             :  *  std::ostringstream oss;
     102             :  *  oss << "A message " << x << " end of the message.";
     103             :  *  throw atm::AtmException(ATM_EXCEPTION_ARGS(oss.str().c_str()));
     104             :  * @endcode
     105             :  *
     106             :  * It is recommended to catch unknown exceptions with an AtmException.
     107             :  *
     108             :  * @code
     109             :  *  catch(...)
     110             :  *  {
     111             :  *    throw atm::AtmException(ATM_EXCEPTION_ARGS("Uncaught exception!"));
     112             :  *  }
     113             :  * @endcode
     114             :  *
     115             :  * To change the format of the outputed method, change the pattern of trace
     116             :  * messages using the telcal::Trace::setTracePattern() method.
     117             :  */
     118             : class AtmException : public std::exception
     119             : {
     120             : public:
     121             :   // --------------------------------------------------
     122             :   //@{
     123             :   //! @name Constructors and destructor
     124             :   // --------------------------------------------------
     125             :   /**
     126             :     * @brief Constructor.
     127             :     * @param msg a message that describes the exception.
     128             :     */
     129             :   AtmException(const char* msg) throw();
     130             :   /**
     131             :    * @brief Constructor.
     132             :    * @param file the file name where the exception raised.
     133             :    * @param routine the routine name where the exception raised.
     134             :    * @param line the line where the exception raised.
     135             :    * @param msg a message that describes the exception.
     136             :    * @see formatMsg()
     137             :    *
     138             :    * This constructor define the AtmException::what_m attribute using the
     139             :    * output string formatted with the formatMsg() method.
     140             :    */
     141             :   AtmException(const char* file, const char* routine, int line, const char* msg) throw();
     142             :   /**
     143             :    * @brief Destructor.
     144             :    */
     145           0 :   virtual ~AtmException() throw()
     146           0 :   {
     147           0 :   }
     148             :   //@}
     149             : 
     150             :   // --------------------------------------------------
     151             :   //@{
     152             :   //! @name Get attributes
     153             :   // --------------------------------------------------
     154             :   /**
     155             :    * @brief Returns the file name where the current error raised.
     156             :    * @return A C-style character string.
     157             :    */
     158           0 :   virtual const char* file() const throw() { return file_m.c_str(); }
     159             :   /**
     160             :     * @brief Returns the routine name where the current error raised.
     161             :     * @return A C-style character string.
     162             :     */
     163           0 :   virtual const char* routine() const throw() { return routine_m.c_str(); }
     164             :   /**
     165             :     * @brief Returns the line number where the current error raised.
     166             :     * @return An integer.
     167             :     * @remarks -1 is returned if no line was given.
     168             :     */
     169           0 :   virtual int line() const throw() { return line_m; }
     170             :   /**
     171             :     * @brief Returns the message where the current error raised.
     172             :     * @return A C-style character string.
     173             :    */
     174           0 :   virtual const char* message() const throw() { return msg_m.c_str(); }
     175             :   /**
     176             :     * @brief Returns a string describing the general cause of the current error.
     177             :     * @return A C-style character string.
     178             :     */
     179           0 :   virtual const char* what() const throw() { return what_m.c_str(); }
     180             :   //@}
     181             : 
     182             : private:
     183             :   // --------------------------------------------------
     184             :   //@{
     185             :   //! @name Manage messages
     186             :   // --------------------------------------------------
     187             :   /**
     188             :    * @brief Output a message that conform to a given trace pattern.
     189             :    * @param file a file name.
     190             :    * @param routine a routine name.
     191             :    * @param line a line number.
     192             :    * @param msg a message.
     193             :    * @return The formatted message.
     194             :    */
     195             :   string formatMsg(const char* file, const char* routine, int line, const char* msg);
     196             :   //@}
     197             : 
     198             : private:
     199             :   string file_m; //!< The file where the exception raised.
     200             :   string routine_m; //!< The routine where the exception raised.
     201             :   int line_m; //!< The line where the exception raised.
     202             :   string msg_m; //!< The message where the exception raised.
     203             :   string what_m; //!< The error message to be displayed.
     204             : }; // class AtmException
     205             : 
     206             : ATM_NAMESPACE_END
     207             : 
     208             : /**
     209             :  * @def ATM_EXCEPTION_ARGS(msg)
     210             :  * @brief Writes arguments needed to create an AtmException object.
     211             :  * @param msg a message (that describes the exception).
     212             :  * @see AtmException
     213             :  *
     214             :  * Writes (during the C++ code parsing) the list of arguments that contains the
     215             :  * position (file, function and line) in the C++ module where this macro is
     216             :  * written and the exception description \p msg.
     217             :  *
     218             :  * Use this macro to create an AtmException object:
     219             :  *
     220             :  * @code
     221             :  *  atm::AtmException(ATM_EXCEPTION_ARGS("An exception message..."));
     222             :  * @endcode
     223             :  */
     224             : #define ATM_EXCEPTION_ARGS(msg) __FILE__, __PRETTY_FUNCTION__, __LINE__, msg
     225             : 
     226             : #endif /*!_ATM_EXCEPTIONS_H*/