Event/ers/include/ers/StreamFactory.h

Go to the documentation of this file.

/*
 *  StreamFactory.h
 *  ers
 *
 *  Created by Matthias Wiesmann on 21.01.05.
 *  Copyright 2005 CERN. All rights reserved.
 *
 */
 
#ifndef ERS_STREAM_FACTORY
#define ERS_STREAM_FACTORY
 
#include "ers/Context.h"
#include "ers/Core.h"
 
#include <map>
 
namespace ers {
 
  class Stream;
  class Issue;
 
  /** The \c StreamFactory class is responsible for creating and handling all the ers stream
    used by the system.
    * It implements the singleton pattern and the factory pattern.
    * There should normally only be one instance of this class per process at any time, each
    instance
    * handles a table of the different stream attached to each severity.
    * When issues occurs, they can be dispatched using this instance.
    * In general, the following method should be used to dispatch issues
    * <ul>
    * <li> \c dispatch if the severity_t of the issue is set correctly. </li>
    * <li> \c fatal, \c error, \c warning, \c debug for setting the severity_t and
    dispatch.</li>
    * </ul>
    * The default stream are set up in the following way:
    * <ol>
    * <li>The system checks if an environnement variable with the same name as severity_t is
    defined.
    *     If this is the case, the value of this variable is parsed as a <b>key</b> for
    building the stream.
    *     Key are basically URLs, either they start with the \c file protocol, or a keyword
    that
    *     identifies a different type of protocol followed by a colon.
    *     Certain protocols accepts more information after the colon, for instance for file
    streams,
    *     the rest of the URL is used to specify the file path, and deduce the file format from
    the
    *     file extension.<br>
    *     <b>Examples</b><br>
    *     <ul>
    *     <li><code>file:/tmp/out.xml</code> represents a stream that writes
    *     issues into file <tt>/tmp/out.xml</tt> in the XML format.</li>
    *       <li><code>cerr:tab</code> represents a stream that writes in tabulated format
    *     on the standard output.
    *     </ul></li>
    * <li>If the stream cannot be determined out of the environement variable, a default stream
    is built.
    *     The actual type of this default stream is determined by the content of the key in \c
    DEFAULT_STREAMS.
    *     The content is a key with the format described above.y</li>
    * <li>The user can provide another stream for any severity_t simply by calling method \c
    set, either
    *     by specifying the stream directly, or by providing a key.</li>
    * </ol>
    * Different packages offer different stream implementations.
    * To use a specific stream type, the relevant library needs to be linked in.
    * If the key for a type of stream that is not available is used, the system will revert to
    the default stream.
    *
    * <b>Supported Keys - ERS package</b>
    *
    * The ERS package supports by default the following keys:<ul>
    * <li><tt>null:</tt> issues are discarded </li>
    * <li><tt>default:</tt> issues are displayed on standard error stream </li>
    * <li><tt>fifo:</tt> writes into a FIFO stream, to be actually used the issues need to be
    read by another entity </li>
    * <li><tt>filter:</tt> filter stream, the Issues are filtered and if the filter accept
    them, passed on to another stream (specified by another key in the stream description).
    * </ul>
    *
    * <b>Supported Keys - System package:</b>
    *
    * The System package supports the following keys:<ul>
    * <li>file: writes into a file</li>
    * <li>cerr: writes into the standard error stream.<br>
    *     The file: and cerr: protocol support the following data encodings:<ul>
    *     <li>xml - issues are serialized as XML data </li>
    *     <li>tab - issues are serialized as tabulated data </li>
    *     <li>txt - issues are serialized as single line of text </li>
    *     </ul>
    * <li>syslog: issues are sent to syslog </li>
    * </ul>
    *
    * <b>Supported Keys - ers-ipc package:</b>
    *
    * The ersipc package supports the following keys:<ul>
    * <li>mrs: writes issues into the MRS system (q.v.) the rest of the uri in this case
    designates the IPC partition to use
    *     for instance mrs://data
    * </ul>
    *
    * In order to add new stream implementations, one needs to register a factory function of
    type \c create_stream_callback.
    * This method takes two parameters, a protocol parameter, and an uri parameter, that
    basically contains everything except
    * the protocol part of the key. If the implementation can offer a stream that corresponds
    to the key it should return a
    * heap allocated stream, if not it should return a null pointer.
    * This method should be registered using the \c register_factory method
    * on the default instance.
    *
    * <b>Macros</b><br>
    * This file also defines a set of macros that send messages to the relevant streams in the
    factory.
    * Those macros are intendred for logging out debug messages.
    * They can compiled out by the way of the \c DEBUG_LEVEL macro.
    * This macro should be defined with an integer level.
    * A debugging macro is disabled if its number is higher than the value of \c DEBUG_LEVEL.
    * For instance if DEBUG_LEVEL=2 then ERS_DEBUG_3 is compiled out.
    * ERS_DEBUG_0 is never compiled out. If no debug level is specified, level 3 (maximum) is
    assumed.
    * If the macro ERS_FAST_DEBUG is defined then ERS_DEBUG_0 macro directly maps to a fprintf
    statement on stderr.
    *
    * \author Matthias Wiesmann
    * \version 1.2
    * \brief Factory for Stream objects and repository of default streams.
    * \see ers::Stream
    * \see ers::FIFOStream
    * \see ers::FilterStream
    * \see System::STLStream
    * \see System::MessageStream
    * \see System::SyslogStream
    * \see System::TabStream
    * \see System::XercesStream
    */
 
  class StreamFactory {
 
  public:
    typedef Stream* ( *create_stream_callback )( const std::string&, const std::string& );
    typedef std::map<std::string, create_stream_callback> stream_factory_collection;
 
  protected:
    static StreamFactory* s_instance;        /**< \brief singleton instance */
    static const char*    DEFAULT_STREAMS[]; /**< \brief keys for default streams */
    static const char* key_for_severity( severity_t s ); /**< \brief finds key for severity_t
                                                          */
    static Stream* get_default_stream( severity_t s );   /**< \brief builds default stream for
                                                            severity_t */
 
    StreamFactory();
    StreamFactory( const StreamFactory& other );
 
    Stream* m_streams[severity_max]; /**< \brief array of pointers to streams per severity_t */
    stream_factory_collection m_factories; /**< \brief collection of factories to build streams
                                            */
 
    Stream* create_stream( severity_t s ); /**< \brief create a stream for severity_t */
  public:
    static StreamFactory* instance(); /**< \brief return the singleton */
    static void           print_registered();
    static void           fatal( Issue* i ); /**< \brief sends an issue to the fatal stream */
    static void           error( Issue* i ); /**< \brief sends an issue to the error stream */
    static void warning( Issue* i ); /**< \brief sends an issue to the warning stream */
    static void warning( const Context&     c,
                         const std::string& message ); /**< \brief sends a warning message */
    static void debug( Issue* i,
                       severity_t ); /**< \brief sends an Issue to the debug stream */
    static void debug( const Context& c, const std::string& message,
                       severity_t s ); /**< \brief sends a debug message */
    static void dispatch( Issue* i, bool throw_error = false ); /**< \brief Sends an issue to
                                                                 the appropriate stream
                                                                 according to its severity_t */
    static void dispatch( Issue& i, bool throw_error = false );
    static void set_stream( severity_t, const std::string& key );
    ~StreamFactory();
    Stream* create_stream( const std::string& key ) const; /**< \brief create a stream from a
                                                              key */
    Stream* get_stream( severity_t s ); /**< \brief get stream for severity_t */
    void    set( severity_t severity,
                 Stream*    s ); /**< \brief Sets the stream for a given severity_t */
    void    set( severity_t severity, const char* key ); /**< \brief Setup a stream for a given
                                                            severity_t based on a key */
    Stream* fatal();                                     /**< \brief Fatal stream */
    Stream* error();                                     /**< \brief Error stream */
    Stream* warning();                                   /**< \brief Warning stream */
    Stream* debug( severity_t s );                       /**< \brief Debug stream for level*/
    bool    register_factory( const std::string&     name,
                              create_stream_callback callback ); /**< \brief register a factory
                                                                    method */
    void write_to( std::ostream& stream ) const; /**< \brief write content of factory to stream
                                                  */
  };
  std::ostream& operator<<( std::ostream&,
                            const ers::StreamFactory& factory ); /**< \brief streaming operator
                                                                  */
} // namespace ers
 
#ifndef DEBUG_LEVEL
/** If no debug level is defined, we assume the highest level */
#  define DEBUG_LEVEL 3
#endif
 
/** Sends a debug message with level 0, the first parameter is a \c printf like pattern, the
 * next are parameters for it */
 
#if !defined( ERS_FAST_DEBUG )
#  define ERS_DEBUG_0( ... )                                                                  \
    {                                                                                         \
      char ers_debug_buf[256];                                                                \
      snprintf( ers_debug_buf, sizeof( ers_debug_buf ), __VA_ARGS__ );                        \
      ers::StreamFactory::debug( ERS_HERE, ers_debug_buf, ers::debug_0 );                     \
    }
#else
#  define ERS_DEBUG_0( ... )                                                                  \
    {                                                                                         \
      fprintf( stderr, "debug-0 " );                                                          \
      fprintf( stderr, __VA_ARGS__ );                                                         \
      fprintf( stderr, "\n" );                                                                \
    }
#endif
 
/** Sends a debug message with level 1, the first parameter is a \c printf like pattern, the
 * next are parameters for it */
#if ( DEBUG_LEVEL > 0 )
#  if ( !defined( ERS_FAST_DEBUG ) )
#    define ERS_DEBUG_1( ... )                                                                \
      {                                                                                       \
        char ers_debug_buf[256];                                                              \
        snprintf( ers_debug_buf, sizeof( ers_debug_buf ), __VA_ARGS__ );                      \
        ers::StreamFactory::debug( ERS_HERE, ers_debug_buf, ers::debug_1 );                   \
      }
#  else
#    define ERS_DEBUG_1( ... )                                                                \
      {                                                                                       \
        fprintf( stderr, "debug-1 " );                                                        \
        fprintf( stderr, __VA_ARGS__ );                                                       \
        fprintf( stderr, "\n" );                                                              \
      }
#  endif
#else
#  define ERS_DEBUG_1( ... )
#endif
 
/** Sends a debug message with level 2, the first parameter is a \c printf like pattern, the
 * next are parameters for it */
#if DEBUG_LEVEL > 1
#  define ERS_DEBUG_2( ... )                                                                  \
    {                                                                                         \
      char ers_debug_buf[256];                                                                \
      snprintf( ers_debug_buf, sizeof( ers_debug_buf ), __VA_ARGS__ );                        \
      ers::StreamFactory::debug( ERS_HERE, ers_debug_buf, ers::debug_2 );                     \
    }
#else
#  define ERS_DEBUG_2( ... )
#endif
 
/** Sends a debug message with level 3, the first parameter is a \c printf like pattern, the
 * next are parameters for it */
#if DEBUG_LEVEL > 2
#  define ERS_DEBUG_3( ... )                                                                  \
    {                                                                                         \
      char ers_debug_buf[256];                                                                \
      snprintf( ers_debug_buf, sizeof( ers_debug_buf ), __VA_ARGS__ );                        \
      ers::StreamFactory::debug( ERS_HERE, ers_debug_buf, ers::debug_3 );                     \
    }
#else
#  define ERS_DEBUG_3( ... )
#endif
 
/** Sends a warning, the first parameter is a \c printf like pattern, the next are parameters
 * for it */
#define ERS_WARN( ... )                                                                       \
  {                                                                                           \
    char ers_warn_buf[256];                                                                   \
    snprintf( ers_warn_buf, sizeof( ers_warn_buf ), __VA_ARGS__ );                            \
    ers::StreamFactory::warning( ERS_HERE, ers_warn_buf );                                    \
  }
 
#endif