ers::StreamFactory Class Reference

Factory for Stream objects and repository of default streams. More...

#include <StreamFactory.h>

Public Types
typedef Stream *(*	create_stream_callback) (const std::string &, const std::string &)
typedef std::map< std::string, create_stream_callback >	stream_factory_collection

Public Member Functions
	~StreamFactory ()
Stream *	create_stream (const std::string &key) const
	create a stream from a key
Stream *	get_stream (severity_t s)
	get stream for severity_t
void	set (severity_t severity, Stream *s)
	Sets the stream for a given severity_t.
void	set (severity_t severity, const char *key)
	Setup a stream for a given severity_t based on a key.
Stream *	fatal ()
	Fatal stream.
Stream *	error ()
	Error stream.
Stream *	warning ()
	Warning stream.
Stream *	debug (severity_t s)
	Debug stream for level.
bool	register_factory (const std::string &name, create_stream_callback callback)
	register a factory method
void	write_to (std::ostream &stream) const
	write content of factory to stream

Static Public Member Functions
static StreamFactory *	instance ()
	return the singleton
static void	print_registered ()
static void	fatal (Issue *i)
	sends an issue to the fatal stream
static void	error (Issue *i)
	sends an issue to the error stream
static void	warning (Issue *i)
	sends an issue to the warning stream
static void	warning (const Context &c, const std::string &message)
	sends a warning message
static void	debug (Issue *i, severity_t)
	sends an Issue to the debug stream
static void	debug (const Context &c, const std::string &message, severity_t s)
	sends a debug message
static void	dispatch (Issue *i, bool throw_error=false)
	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)

Protected Member Functions
	StreamFactory ()
	StreamFactory (const StreamFactory &other)
Stream *	create_stream (severity_t s)
	create a stream for severity_t

Static Protected Member Functions
static const char *	key_for_severity (severity_t s)
	finds key for severity_t
static Stream *	get_default_stream (severity_t s)
	builds default stream for severity_t

Protected Attributes
Stream *	m_streams [severity_max]
	array of pointers to streams per severity_t
stream_factory_collection	m_factories
	collection of factories to build streams

Static Protected Attributes
static StreamFactory *	s_instance = 0
	singleton instance
static const char *	DEFAULT_STREAMS []
	keys for default streams

Detailed Description

Factory for Stream objects and repository of default streams.

The 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

• dispatch if the severity_t of the issue is set correctly.
• fatal, error, warning, debug for setting the severity_t and dispatch.

The default stream are set up in the following way:

1. 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 key for building the stream. Key are basically URLs, either they start with the 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.
   Examples
   
   • file:/tmp/out.xml represents a stream that writes issues into file /tmp/out.xml in the XML format.
   • cerr:tab represents a stream that writes in tabulated format on the standard output.
2. 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 DEFAULT_STREAMS. The content is a key with the format described above.y
3. The user can provide another stream for any severity_t simply by calling method set, either by specifying the stream directly, or by providing a key.

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.

Supported Keys - ERS package

The ERS package supports by default the following keys:

• null: issues are discarded
• default: issues are displayed on standard error stream
• fifo: writes into a FIFO stream, to be actually used the issues need to be read by another entity
• filter: 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).

Supported Keys - System package:

The System package supports the following keys:

• file: writes into a file
• cerr: writes into the standard error stream.
  The file: and cerr: protocol support the following data encodings:
  • xml - issues are serialized as XML data
  • tab - issues are serialized as tabulated data
  • txt - issues are serialized as single line of text
• syslog: issues are sent to syslog

Supported Keys - ers-ipc package:

The ersipc package supports the following keys:

• 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

In order to add new stream implementations, one needs to register a factory function of type 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 register_factory method on the default instance.

Macros
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 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 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

See also

ers::Stream

ers::FIFOStream

ers::FilterStream

System::STLStream

System::MessageStream

System::SyslogStream

System::TabStream

System::XercesStream

Definition at line 119 of file StreamFactory.h.

Member Typedef Documentation

create_stream_callback

typedef Stream *(* ers::StreamFactory::create_stream_callback) (const std::string &, const std::string &)

Definition at line 122 of file StreamFactory.h.

stream_factory_collection

typedef std::map<std::string, create_stream_callback> ers::StreamFactory::stream_factory_collection

Definition at line 123 of file StreamFactory.h.

Constructor & Destructor Documentation

StreamFactory() [1/2]

ers::StreamFactory::StreamFactory ( )

protected

Constructor - should never be called by user code, use the instance() method instead

See also

instance()

Definition at line 43 of file StreamFactory.cxx.

                                {
   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

StreamFactory() [2/2]

ers::StreamFactory::StreamFactory ( const StreamFactory &  other )

protected

Copy constructor - disabled, use the instance() method instead

See also

instance()

Exceptions

ers::NotImplemented

in all cases

Definition at line 55 of file StreamFactory.cxx.

                                                          {
    (void) other ; // shut up the compiler 
    ERS_NOT_IMPLEMENTED(); 
} // StreamFactory

~StreamFactory()

ers::StreamFactory::~StreamFactory

(

)

Destructor - basic cleanup

Note

in practice this method should never be called, the singleton should never be deallocated

Definition at line 64 of file StreamFactory.cxx.

                                 {
    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

Member Function Documentation

create_stream() [1/2]

ers::Stream * ers::StreamFactory::create_stream

(

const std::string &

key

)

const

create a stream from a key

Builds a stream from a textual key The key should have the format 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: cerr:.xml

Parameters

key	the textual key

Note

the stream is allocated on the stack, it is the caller's responsibility to delete it.

Definition at line 143 of file StreamFactory.cxx.

                                                                     {
    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

create_stream() [2/2]

ers::Stream * ers::StreamFactory::create_stream ( severity_t  s )

protected

create a stream for severity_t

Builds a stream for a given severity. The actual key for the severity_t is found using key_for_severity, then the appropriate stream is constructred using create_stream

See also

key_for_severity()

create_stream()

Parameters

s	the severity_t of the requested stream

Returns

the newly created stream

Note

the stream is allocated on the stack, it is the caller's responsibility to delete it.

Definition at line 176 of file StreamFactory.cxx.

                                                       {
    const char* key = key_for_severity(s); 
    return create_stream(key); 
} // get_stream

Referenced by ers::FilterStream::factory().

debug() [1/3]

void ers::StreamFactory::debug ( const Context &  c, const std::string &  message, severity_t  s  )

static

sends a debug message

Sends a message to the debug stream

Parameters

c	the Context of the message
message	the text of the message
s	the severity_t of the associated stream. Accepted values: ers_debug_0 ers_debug_1 ers_debug_2 ers_debug_3

Definition at line 231 of file StreamFactory.cxx.

                                                                                     {
    LogIssue log_issue(c,s,message); 
    debug(&log_issue,s); 
} // debug

debug() [2/3]

void ers::StreamFactory::debug ( Issue *  issue_ptr, severity_t  s  )

static

sends an Issue to the debug stream

Sends an issue to the debug stream

Parameters

issue_ptr	the Issue to send
s	the severity_t of the associated stream. Accepted values: ers_debug_0 ers_debug_1 ers_debug_2 ers_debug_3

Definition at line 218 of file StreamFactory.cxx.

                                                           {
    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

debug() [3/3]

ers::Stream * ers::StreamFactory::debug

(

severity_t

s

)

Debug stream for level.

Finds the debug stream

Parameters

s	the severity_t of the associated stream. Accepted values: ers_debug_0 ers_debug_1 ers_debug_2 ers_debug_3

Returns

debug stream

Definition at line 347 of file StreamFactory.cxx.

                                                {
    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

dispatch() [1/2]

void ers::StreamFactory::dispatch ( Issue &  i, bool  throw_error = false  )

static

Definition at line 264 of file StreamFactory.cxx.

                                                                  {
    dispatch(&issue_ref,throw_error); 
} // dispatch

dispatch() [2/2]

void ers::StreamFactory::dispatch ( Issue *  issue_ptr, bool  throw_error = false  )

static

Sends an issue to the appropriate stream according to its severity_t.

Dispatches an issue to the appropriate stream. The stream is decided based upon the severity_t specified in the Issue. If throw_error is true errors and fatal errors are not sent to a stream, but thrown in the context of the caller.

Parameters

issue_ptr	the Issue to dispatch
throw_error	should errors and fatals are thrown

Definition at line 254 of file StreamFactory.cxx.

                                                                  {
    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

Referenced by main().

error() [1/2]

ers::Stream * ers::StreamFactory::error

(

)

Error stream.

Returns

the current error stream

Definition at line 332 of file StreamFactory.cxx.

{ return get_stream(ers::error) ; } // error

error() [2/2]

void ers::StreamFactory::error ( Issue *  issue_ptr )

static

sends an issue to the error stream

Sends an Issue to the error stream

Parameters

issue_ptr

Definition at line 196 of file StreamFactory.cxx.

                                             {
    ERS_PRE_CHECK_PTR(issue_ptr); 
    issue_ptr->severity(ers::error); 
    dispatch(issue_ptr,false); 
} // error

fatal() [1/2]

ers::Stream * ers::StreamFactory::fatal

(

)

Fatal stream.

Returns

the current fatal stream

Definition at line 326 of file StreamFactory.cxx.

{ return get_stream(ers::fatal) ; } // fatal 

fatal() [2/2]

void ers::StreamFactory::fatal ( Issue *  issue_ptr )

static

sends an issue to the fatal stream

Sends an Issue to the fatal error stream

Parameters

issue_ptr

Definition at line 186 of file StreamFactory.cxx.

                                             {
    ERS_PRE_CHECK_PTR(issue_ptr); 
    issue_ptr->severity(ers::fatal); 
    dispatch(issue_ptr,false); 
} // fatal

get_default_stream()

ers::Stream * ers::StreamFactory::get_default_stream ( severity_t  s )

staticprotected

builds default stream for severity_t

Finds the default stream for a given severity. The stream is searched in the default instance

Parameters

s	the severity_t

Returns

the default stream for the severity_t

Definition at line 104 of file StreamFactory.cxx.

                                                            {
    return instance()->get_stream(s) ; 
} // get_default_stream

get_stream()

ers::Stream * ers::StreamFactory::get_stream

(

severity_t

s

)

get stream for severity_t

Gets stream for severity_t

Parameters

s	the severity_t of the requested stream

Returns

the stream

Definition at line 283 of file StreamFactory.cxx.

                                                      {
    if (m_streams[s]==0) {
    m_streams[s]=create_stream(s) ; 
    } // if 
    return m_streams[s] ; 
} // get_stream

instance()

ers::StreamFactory * ers::StreamFactory::instance ( )

static

return the singleton

This method returns the singleton instance. It should be used for every operation on the factory.

Returns

a pointer to the singleton instance

Definition at line 80 of file StreamFactory.cxx.

                                             {
    if (0==s_instance) {
    s_instance = new StreamFactory(); 
    } // if
    return s_instance ; 
} // instance

Referenced by ers::FilterStream::factory().

key_for_severity()

const char * ers::StreamFactory::key_for_severity ( severity_t  s )

staticprotected

finds key for severity_t

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 ERS_WARNING.

Parameters

s	the severity_t

Returns

the key describing the stream.

Definition at line 119 of file StreamFactory.cxx.

                                                           {
    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

print_registered()

void ers::StreamFactory::print_registered ( )

static

Dumps all registered types of streams

Definition at line 89 of file StreamFactory.cxx.

                                        {
    const StreamFactory *factory = instance();
    std::cerr << *factory ; 
} // print_registered

register_factory()

bool ers::StreamFactory::register_factory	(	const std::string &	name,
		create_stream_callback	callback
	)

register a factory method

Registers a factory function with the stream factory. The callback is function that takes two parameters

1. a string describing the protocol, for instance file
2. a string describing a uri, can be a path, a suffix or anything

The function should return a heap allocated stream, or null if it does not understand the protocol.

Parameters

name	name of the stream type (human display only).
callback	the callback function

Returns

true if the registration was sucessfull

Definition at line 367 of file StreamFactory.cxx.

                                                                                              {
    // std::cerr << "registering " << name << std::endl ; 
    m_factories[name] = callback ;
    return true  ;
} // register_factory

set() [1/2]

void ers::StreamFactory::set	(	severity_t	severity,
		const char *	key
	)

Setup a stream for a given severity_t based on a key.

Builds a stream using a string key and sets it up for a given severity

Parameters

severity_t	severity_t of the stream Accepted values: ers_debug_0 ers_debug_1 ers_debug_2 ers_debug_3 ers_information ers_notification ers_warning ers::error ers_fatal
key	the key used to build the new stream

Definition at line 316 of file StreamFactory.cxx.

                                                               {
    ERS_PRE_CHECK_PTR(key); 
    Stream *s = create_stream(key);
    set(severity,s); 
} // 

set() [2/2]

void ers::StreamFactory::set	(	severity_t	severity,
		Stream *	s
	)

Sets the stream for a given severity_t.

Sets the stream for a given severity_t

Parameters

severity_t	severity_t of the stream Accepted values: ers_debug_0 ers_debug_1 ers_debug_2 ers_debug_3 ers_information ers_notification ers_warning ers::error ers_fatal
s	the new stream

Definition at line 299 of file StreamFactory.cxx.

                                                         {
    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

set_stream()

void ers::StreamFactory::set_stream ( severity_t  s, const std::string &  key  )

static

Definition at line 269 of file StreamFactory.cxx.

                                                                    {
    instance()->set(s,key.c_str()) ; 
} // set

Referenced by main(), and massive_test().

warning() [1/3]

ers::Stream * ers::StreamFactory::warning

(

)

Warning stream.

Returns

the current warning stream

Definition at line 338 of file StreamFactory.cxx.

{ return get_stream(ers::warning); } // warning

Referenced by main().

warning() [2/3]

void ers::StreamFactory::warning ( const Context &  c, const std::string &  message  )

static

sends a warning message

Sends a message to the warning stream

Parameters

c	the context of the message
message	the message to send

Definition at line 241 of file StreamFactory.cxx.

                                                                         {
    LogIssue log_issue(c,ers::warning,message);
    warning(&log_issue); 
} // warning

warning() [3/3]

void ers::StreamFactory::warning ( Issue *  issue_ptr )

static

sends an issue to the warning stream

Sends an Issue to the warning stream

Parameters

issue_ptr

the issue to send

Definition at line 206 of file StreamFactory.cxx.

                                               {
    ERS_PRE_CHECK_PTR(issue_ptr); 
    issue_ptr->severity(ers::warning); 
    dispatch(issue_ptr,false); 
} // warning

write_to()

void ers::StreamFactory::write_to

(

std::ostream &

stream

)

const

write content of factory to stream

Writes a description of the factory to a stream. This method gives a list of all registered stream types.

Parameters

stream

the stream to write into

Definition at line 378 of file StreamFactory.cxx.

                                                        {
    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

Member Data Documentation

DEFAULT_STREAMS

const char * ers::StreamFactory::DEFAULT_STREAMS

staticprotected

Initial value:

= {
    "null:",                                                          
    "default:",  "default:",  "default:", "default:",                 
    "default:",  "default:",  "default:",                             
    "default:verbose",  "default:verbose",                            
    "null:"  }

keys for default streams

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.

Definition at line 126 of file StreamFactory.h.

m_factories

stream_factory_collection ers::StreamFactory::m_factories

protected

collection of factories to build streams

Definition at line 134 of file StreamFactory.h.

m_streams

Stream* ers::StreamFactory::m_streams[severity_max]

protected

array of pointers to streams per severity_t

Definition at line 133 of file StreamFactory.h.

Referenced by StreamFactory().

s_instance

ers::StreamFactory * ers::StreamFactory::s_instance = 0

staticprotected

singleton instance

Pointer to the singleton instance

Definition at line 125 of file StreamFactory.h.

---

The documentation for this class was generated from the following files:

• StreamFactory.h
• StreamFactory.cxx