StreamFactory.cxx

Go to the documentation of this file.

/*
 *  StreamFactory.cxx
 *  ERS
 *
 *  Created by Matthias Wiesmann on 21.01.05.
 *  Copyright 2005 CERN. All rights reserved.
 *
 */
 
#include <cstdlib>
#include <iostream>
 
#include "ers/DefaultStream.h"
#include "ers/StreamFactory.h"
#include "ers/ers.h"
 
/** This variable contains the default keys for building the default streams.
 * The default is to use the default stream, in verbose mode for errors and fatals.
 */
 
const char* ers::StreamFactory::DEFAULT_STREAMS[] = { "null:", // none
                                                      "default:", "default:", "default:",
                                                      "default:", // debug levels
                                                      "default:", "default:",
                                                      "default:", // information, notification,
                                                                  // warning
                                                      "default:verbose",
                                                      "default:verbose", // Errors and Fatals
                                                      "null:" };         // max
 
/** Pointer to the singleton instance
 */
 
ers::StreamFactory* ers::StreamFactory::s_instance = 0;
 
// Constructors & Instance access methods
// --------------------------------------
 
/** Constructor - should never be called by user code, use the \c instance() method instead
 * \see instance()
 */
 
ers::StreamFactory::StreamFactory() {
  for ( int i = static_cast<int>( severity_none ); i < static_cast<int>( severity_max ); i++ )
  {
    severity_t s = static_cast<severity_t>( i );
    m_streams[s] = 0;
  } // for*/
} // StreamFactory
 
/** Copy constructor - disabled, use the \c instance() method instead
 * \see instance()
 * \throw ers::NotImplemented in all cases
 */
 
ers::StreamFactory::StreamFactory( const StreamFactory& other ) {
  (void)other; // shut up the compiler
  ERS_NOT_IMPLEMENTED();
} // StreamFactory
 
/** Destructor - basic cleanup
 * \note in practice this method should never be called, the singleton should never be
 * deallocated
 */
 
ers::StreamFactory::~StreamFactory() {
  for ( int i = static_cast<int>( severity_none ); i < static_cast<int>( severity_max ); i++ )
  {
    severity_t s = static_cast<severity_t>( i );
    if ( m_streams[s] )
    {
      delete ( m_streams[s] );
      m_streams[s] = 0;
    } // if stream
  }   // for*/
} // ~StreamFactory
 
/** This method returns the singleton instance.
 * It should be used for every operation on the factory.
 * \return a pointer to the singleton instance
 */
 
ers::StreamFactory* ers::StreamFactory::instance() {
  if ( 0 == s_instance ) { s_instance = new StreamFactory(); } // if
  return s_instance;
} // instance
 
/** Dumps all registered types of streams */
 
void ers::StreamFactory::print_registered() {
  const StreamFactory* factory = instance();
  std::cerr << *factory;
} // print_registered
 
// Static methods
// --------------------------------------
 
/** Finds the default stream for a given severity.
 * The stream is searched in the default instance
 * \param s the severity_t
 * \return the default stream for the severity_t
 */
 
ers::Stream* ers::StreamFactory::get_default_stream( severity_t s ) {
  return instance()->get_stream( s );
} // get_default_stream
 
/** Searches for the textual key for a given severity.
 * This key is first searched in the environnement variables,
 * if this fails, the default values are loaded.
 * The environnement variable should have the same name than the severity
 * with the prefix ERS_ in front. The whole name should be in uppercases.
 * For instance for severity_t warning, the environnement variable should be
 * \c ERS_WARNING.
 * \param s the severity_t
 * \return the key describing the stream.
 */
 
const char* ers::StreamFactory::key_for_severity( severity_t s ) {
  char key_buffer[64];
  snprintf( key_buffer, sizeof( key_buffer ), "ERS_%s", ers::Core::to_string( s ) );
  char* c = &( key_buffer[0] );
  while ( *c )
  {
    *c = toupper( *c );
    c++;
  } // while
  const char* env = ::getenv( key_buffer );
  if ( env != 0 ) return env;
  const char* static_key = DEFAULT_STREAMS[s];
  if ( static_key ) return static_key;
  return ers::DefaultStream::KEY;
} // key_for_severity
 
/** Builds a stream from a textual key
 * The key should have the format \c protocol:path.extension
 * In certain cases, the path will be empty.
 * For instance to write in XML format to the error stream, the key is:
 * \c cerr:.xml
 * \param key the textual key
 * \note the stream is allocated on the stack, it is the caller's responsibility to delete it.
 */
 
ers::Stream* ers::StreamFactory::create_stream( const std::string& key ) const {
  std::string protocol;
  std::string uri;
 
  std::string::size_type colon = key.find( ':' );
  if ( colon == std::string::npos ) { protocol = key; }
  else
  {
    protocol                         = key.substr( 0, colon );
    std::string::size_type uri_start = colon + 1;
    if ( uri_start < key.size() ) { uri = key.substr( uri_start ); } // if
  }                                                                  // colon present
  for ( stream_factory_collection::const_iterator pos = m_factories.begin();
        pos != m_factories.end(); ++pos )
  {
    create_stream_callback callback = pos->second;
    Stream*                s        = callback( protocol, uri );
    if ( s != 0 ) return s;
  } // for
  fprintf( stderr, "Warning, could not find stream for key protocol=\"%s\" uri=\"%s\" (%s)\n",
           protocol.c_str(), uri.c_str(), key.c_str() );
  return new DefaultStream();
} // create_stream
 
/** Builds a stream for a given severity.
 * The actual key for the severity_t is found using \c key_for_severity,
 * then the appropriate stream is constructred using \c create_stream
 * \see key_for_severity()
 * \see create_stream()
 * \param s the severity_t of the requested stream
 * \return the newly created stream
 * \note the stream is allocated on the stack, it is the caller's responsibility to delete it.
 */
 
ers::Stream* ers::StreamFactory::create_stream( severity_t s ) {
  const char* key = key_for_severity( s );
  return create_stream( key );
} // get_stream
 
/** Sends an Issue to the fatal error stream
 * \param issue_ptr
 */
 
void ers::StreamFactory::fatal( Issue* issue_ptr ) {
  ERS_PRE_CHECK_PTR( issue_ptr );
  issue_ptr->severity( ers::fatal );
  dispatch( issue_ptr, false );
} // fatal
 
/** Sends an Issue to the error stream
 * \param issue_ptr
 */
 
void ers::StreamFactory::error( Issue* issue_ptr ) {
  ERS_PRE_CHECK_PTR( issue_ptr );
  issue_ptr->severity( ers::error );
  dispatch( issue_ptr, false );
} // error
 
/** Sends an Issue to the warning stream
 * \param issue_ptr the issue to send
 */
 
void ers::StreamFactory::warning( Issue* issue_ptr ) {
  ERS_PRE_CHECK_PTR( issue_ptr );
  issue_ptr->severity( ers::warning );
  dispatch( issue_ptr, false );
} // warning
 
/** Sends an issue to the debug stream
 * \param issue_ptr the Issue to send
 * \param s the severity_t of the associated stream.
 *          Accepted values: \li \c ers_debug_0 \li \c ers_debug_1 \li \c ers_debug_2 \li \c
 * ers_debug_3
 */
 
void ers::StreamFactory::debug( Issue* issue_ptr, severity_t s ) {
  ERS_PRE_CHECK_PTR( issue_ptr );
  ERS_PRECONDITION( s < ers::information, "severity_t is not debug : %s (%d) %d",
                    ers::Core::to_string( s ), s, ers::information );
  issue_ptr->severity( s );
  dispatch( issue_ptr, false );
} //  debug
 
/** Sends a message to the debug stream
 * \param c the Context of the message
 * \param message the text of the message
 * \param s the severity_t of the associated stream. Accepted values: \li \c ers_debug_0 \li \c
 * ers_debug_1 \li \c ers_debug_2 \li \c ers_debug_3
 */
 
void ers::StreamFactory::debug( const Context& c, const std::string& message, severity_t s ) {
  LogIssue log_issue( c, s, message );
  debug( &log_issue, s );
} // debug
 
/** Sends a message to the warning stream
 * \param c the context of the message
 * \param message the message to send
 */
 
void ers::StreamFactory::warning( const Context& c, const std::string& message ) {
  LogIssue log_issue( c, ers::warning, message );
  warning( &log_issue );
} // warning
 
/** Dispatches an issue to the appropriate stream.
 * The stream is decided based upon the severity_t specified in the Issue.
 * If \c throw_error is true errors and fatal errors are not sent to a stream, but thrown in
 * the context of the caller. \param issue_ptr the Issue to dispatch \param throw_error should
 * errors and fatals are thrown
 */
 
void ers::StreamFactory::dispatch( Issue* issue_ptr, bool throw_error ) {
  ERS_PRE_CHECK_PTR( issue_ptr );
  if ( throw_error && issue_ptr->is_error() ) { throw *issue_ptr; }
  const severity_t s          = issue_ptr->severity();
  Stream*          stream_ptr = instance()->get_stream( s );
  ERS_CHECK_PTR( stream_ptr );
  stream_ptr->send( issue_ptr );
} // dispatch
 
void ers::StreamFactory::dispatch( Issue& issue_ref, bool throw_error ) {
  dispatch( &issue_ref, throw_error );
} // dispatch
 
void ers::StreamFactory::set_stream( severity_t s, const std::string& key ) {
  instance()->set( s, key.c_str() );
} // set
 
// Member methods
// --------------------------------------
 
/** Gets stream for severity_t
 * \param s the severity_t of the requested stream
 * \return the stream
 */
 
ers::Stream* ers::StreamFactory::get_stream( severity_t s ) {
  if ( m_streams[s] == 0 ) { m_streams[s] = create_stream( s ); } // if
  return m_streams[s];
} // get_stream
 
/** Sets the stream for a given severity_t
 * \param severity_t  severity_t of the stream
 * Accepted values: \li \c ers_debug_0 \li \c ers_debug_1 \li \c ers_debug_2 \li \c ers_debug_3
 * \li \c ers_information \li \c ers_notification \li \c ers_warning
 * \li \c ers::error \li \c ers_fatal
 * \param s the new stream
 */
 
void ers::StreamFactory::set( severity_t severity, Stream* s ) {
  ERS_PRE_CHECK_PTR( s );
  ERS_PRECONDITION( severity_none < severity && severity < severity_max,
                    "illegal severity_t %d", (int)severity );
  if ( m_streams[severity] ) { delete m_streams[severity]; } // if there is a stream defined
  m_streams[severity] = s;
} // stream
 
/** Builds a stream using a string key and sets it up for a given severity
 * \param severity_t  severity_t of the stream
 * Accepted values: \li \c ers_debug_0 \li \c ers_debug_1 \li \c ers_debug_2 \li \c ers_debug_3
 * \li \c ers_information \li \c ers_notification \li \c ers_warning
 * \li \c ers::error \li \c ers_fatal
 * \param key the key used to build the new stream
 */
 
void ers::StreamFactory::set( severity_t severity, const char* key ) {
  ERS_PRE_CHECK_PTR( key );
  Stream* s = create_stream( key );
  set( severity, s );
} //
 
/**
 * \return the current fatal stream
 */
 
ers::Stream* ers::StreamFactory::fatal() { return get_stream( ers::fatal ); } // fatal
 
/**
 * \return the current error stream
 */
 
ers::Stream* ers::StreamFactory::error() { return get_stream( ers::error ); } // error
 
/**
 * \return the current warning stream
 */
 
ers::Stream* ers::StreamFactory::warning() { return get_stream( ers::warning ); } // warning
 
/** Finds the debug stream
 * \param s the severity_t of the associated stream.
 * Accepted values: \li \c ers_debug_0 \li \c ers_debug_1 \li \c ers_debug_2 \li \c ers_debug_3
 * \return debug stream
 */
 
ers::Stream* ers::StreamFactory::debug( severity_t s ) {
  ERS_PRECONDITION( s < ers::information && s > ers::severity_none,
                    "severity_t is not debug : %s (%d)", ers::Core::to_string( s ), s );
  return get_stream( s );
} // debug
 
/** Registers a factory function with the stream factory.
 * The callback is function that takes two parameters <ol>
 * <li>a string describing the protocol, for instance \c file </li>
 * <li>a string describing a uri, can be a path, a suffix or anything</li>
 * </ol>
 * The function should return a heap allocated stream, or null if it does not
 * understand the protocol.
 * \param name name of the stream type (human display only).
 * \param callback the callback function
 * \return \c true if the registration was sucessfull
 */
 
bool ers::StreamFactory::register_factory( const std::string&     name,
                                           create_stream_callback callback ) {
  // std::cerr << "registering " << name << std::endl ;
  m_factories[name] = callback;
  return true;
} // register_factory
 
/** Writes a description of the factory to a stream.
 * This method gives a list of all registered stream types.
 * \param stream the stream to write into
 */
 
void ers::StreamFactory::write_to( std::ostream& stream ) const {
  stream << "Stream factory - registered streams\n";
  stream << "-----------------------------------\n";
  int i = 0;
  for ( stream_factory_collection::const_iterator pos = m_factories.begin();
        pos != m_factories.end(); ++pos )
  {
    std::string name = pos->first;
    stream << i << ")\t" << name << std::endl;
    i++;
  } // for
  stream << "-----------------------------------\n";
} // write_to
 
/** Streaming operator
 * \param stream destination stream
 * \param factory the factory object to display
 * \return the stream passed as first parameter
 * \see ers::StreamFactory::write_to()
 */
 
std::ostream& ers::operator<<( std::ostream& stream, const ers::StreamFactory& factory ) {
  factory.write_to( stream );
  return stream;
} // operator