ers::StreamFactory Class Reference

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

#include <StreamFactory.h>

List of all members.

Public Types
typedef Stream *(*	create_stream_callback )(const std::string &, const std::string &)
typedef Stream *(*	create_stream_callback )(const std::string &, const std::string &)
typedef std::map< std::string, create_stream_callback >	stream_factory_collection
typedef std::map< std::string, create_stream_callback >	stream_factory_collection
Public Member Functions
Stream *	create_stream (const std::string &key) const
	create a stream from a key
Stream *	create_stream (const std::string &key) const
	create a stream from a key
Stream *	debug (severity_t s)
	Debug stream for level.
Stream *	debug (severity_t s)
	Debug stream for level.
Stream *	error ()
	Error stream.
Stream *	error ()
	Error stream.
Stream *	fatal ()
	Fatal stream.
Stream *	fatal ()
	Fatal stream.
Stream *	get_stream (severity_t s)
	get stream for severity_t
Stream *	get_stream (severity_t s)
	get stream for severity_t
bool	register_factory (const std::string &name, create_stream_callback callback)
	register a factory method
bool	register_factory (const std::string &name, create_stream_callback callback)
	register a factory method
void	set (severity_t severity, const char *key)
	Setup a stream for a given severity_t based on a key.
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.
void	set (severity_t severity, Stream *s)
	Sets the stream for a given severity_t.
Stream *	warning ()
	Warning stream.
Stream *	warning ()
	Warning stream.
void	write_to (std::ostream &stream) const
	write content of factory to stream
void	write_to (std::ostream &stream) const
	write content of factory to stream
	~StreamFactory ()
	~StreamFactory ()
Static Public Member Functions
void	debug (const Context &c, const std::string &message, severity_t s)
	sends a debug message
void	debug (Issue *i, severity_t)
	sends an Issue to the debug stream
void	debug (const Context &c, const std::string &message, severity_t s)
	sends a debug message
void	debug (Issue *i, severity_t)
	sends an Issue to the debug stream
void	dispatch (Issue &i, bool throw_error=false)
void	dispatch (Issue *i, bool throw_error=false)
	Sends an issue to the appropriate stream according to its severity_t.
void	dispatch (Issue &i, bool throw_error=false)
void	dispatch (Issue *i, bool throw_error=false)
	Sends an issue to the appropriate stream according to its severity_t.
void	error (Issue *i)
	sends an issue to the error stream
void	error (Issue *i)
	sends an issue to the error stream
void	fatal (Issue *i)
	sends an issue to the fatal stream
void	fatal (Issue *i)
	sends an issue to the fatal stream
StreamFactory *	instance ()
	return the singleton
StreamFactory *	instance ()
	return the singleton
void	print_registered ()
void	print_registered ()
void	set_stream (severity_t, const std::string &key)
void	set_stream (severity_t, const std::string &key)
void	warning (const Context &c, const std::string &message)
	sends a warning message
void	warning (Issue *i)
	sends an issue to the warning stream
void	warning (const Context &c, const std::string &message)
	sends a warning message
void	warning (Issue *i)
	sends an issue to the warning stream
Protected Member Functions
Stream *	create_stream (severity_t s)
	create a stream for severity_t
Stream *	create_stream (severity_t s)
	create a stream for severity_t
	StreamFactory (const StreamFactory &other)
	StreamFactory ()
	StreamFactory (const StreamFactory &other)
	StreamFactory ()
Static Protected Member Functions
Stream *	get_default_stream (severity_t s)
	builds default stream for severity_t
Stream *	get_default_stream (severity_t s)
	builds default stream for severity_t
const char *	key_for_severity (severity_t s)
	finds key for severity_t
const char *	key_for_severity (severity_t s)
	finds key for severity_t
Protected Attributes
stream_factory_collection	m_factories
	collection of factories to build streams
Stream *	m_streams [severity_max]
	array of pointers to streams per severity_t
Stream *	m_streams [severity_max]
	array of pointers to streams per severity_t
Static Protected Attributes
const char *	DEFAULT_STREAMS []
	keys for default streams
const char *	DEFAULT_STREAMS []
	keys for default streams
StreamFactory *	s_instance
	singleton instance
StreamFactory *	s_instance = 0
	singleton instance

---

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

---

Member Typedef Documentation

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

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

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

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

---

Constructor & Destructor Documentation

ers::StreamFactory::StreamFactory (   )  [protected]

Constructor - should never be called by user code, use the instance() method instead See also: instance() { 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

ers::StreamFactory::StreamFactory (  const StreamFactory &  other  )  [protected]

Copy constructor - disabled, use the instance() method instead See also: instance() Exceptions: ers::NotImplemented  in all cases { (void) other ; // shut up the compiler ERS_NOT_IMPLEMENTED(); } // StreamFactory

ers::StreamFactory::~StreamFactory (   )

Destructor - basic cleanup Note: in practice this method should never be called, the singleton should never be deallocated { 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

ers::StreamFactory::StreamFactory (   )  [protected]

ers::StreamFactory::StreamFactory (  const StreamFactory &  other  )  [protected]

ers::StreamFactory::~StreamFactory (   )

---

Member Function Documentation

Stream* ers::StreamFactory::create_stream (  const std::string &  key  )  const

create a stream from a key

Stream* ers::StreamFactory::create_stream (  severity_t  s  )  [protected]

create a stream for severity_t

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

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. { const char* key = key_for_severity(s); return create_stream(key); } // get_stream

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

Debug stream for level.

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

sends a debug message

void ers::StreamFactory::debug (  Issue *  i, severity_t  )  [static]

sends an Issue to the debug stream

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

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 { LogIssue log_issue(c,s,message); debug(&log_issue,s); } // debug

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

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

void ers::StreamFactory::dispatch (  Issue *  i, bool  throw_error = false )  [static]

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

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

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

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

Stream* ers::StreamFactory::error (   )

Error stream.

void ers::StreamFactory::error (  Issue *  i  )  [static]

sends an issue to the error stream

ers::Stream * ers::StreamFactory::error (   )

Error stream. Returns: the current error stream { return get_stream(ers::error) ; } // error

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  { ERS_PRE_CHECK_PTR(issue_ptr); issue_ptr->severity(ers::error); dispatch(issue_ptr,false); } // error

Stream* ers::StreamFactory::fatal (   )

Fatal stream.

void ers::StreamFactory::fatal (  Issue *  i  )  [static]

sends an issue to the fatal stream

ers::Stream * ers::StreamFactory::fatal (   )

Fatal stream. Returns: the current fatal stream { return get_stream(ers::fatal) ; } // fatal

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  { ERS_PRE_CHECK_PTR(issue_ptr); issue_ptr->severity(ers::fatal); dispatch(issue_ptr,false); } // fatal

Stream* ers::StreamFactory::get_default_stream (  severity_t  s  )  [static, protected]

builds default stream for severity_t

ers::Stream * ers::StreamFactory::get_default_stream (  severity_t  s  )  [static, protected]

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 { return instance()->get_stream(s) ; } // get_default_stream

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

get stream for severity_t

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 { if (m_streams[s]==0) { m_streams[s]=create_stream(s) ; } // if return m_streams[s] ; } // get_stream

StreamFactory* ers::StreamFactory::instance (   )  [static]

return the singleton

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 { if (0==s_instance) { s_instance = new StreamFactory(); } // if return s_instance ; } // instance

const char* ers::StreamFactory::key_for_severity (  severity_t  s  )  [static, protected]

finds key for severity_t

const char * ers::StreamFactory::key_for_severity (  severity_t  s  )  [static, protected]

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

void ers::StreamFactory::print_registered (   )  [static]

void ers::StreamFactory::print_registered (   )  [static]

Dumps all registered types of streams { const StreamFactory *factory = instance(); std::cerr << *factory ; } // print_registered

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

register a factory method

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 a string describing the protocol, for instance file 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 { // std::cerr << "registering " << name << std::endl ; m_factories[name] = callback ; return true ; } // register_factory

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

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

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

Sets the stream for a given severity_t.

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 { ERS_PRE_CHECK_PTR(key); Stream *s = create_stream(key); set(severity,s); } //

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

void ers::StreamFactory::set_stream (  severity_t  , const std::string &  key )  [static]

void ers::StreamFactory::set_stream (  severity_t  , const std::string &  key )  [static]

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

Stream* ers::StreamFactory::warning (   )

Warning stream.

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

sends a warning message

void ers::StreamFactory::warning (  Issue *  i  )  [static]

sends an issue to the warning stream

ers::Stream * ers::StreamFactory::warning (   )

Warning stream. Returns: the current warning stream { return get_stream(ers::warning); } // warning

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 { LogIssue log_issue(c,ers::warning,message); warning(&log_issue); } // warning

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 { ERS_PRE_CHECK_PTR(issue_ptr); issue_ptr->severity(ers::warning); dispatch(issue_ptr,false); } // warning

void ers::StreamFactory::write_to (  std::ostream &  stream  )  const

write content of factory to stream

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

const char* ers::StreamFactory::DEFAULT_STREAMS[] [static, protected]

keys for default streams

const char * ers::StreamFactory::DEFAULT_STREAMS [static, protected]

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.

stream_factory_collection ers::StreamFactory::m_factories [protected]

collection of factories to build streams

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

array of pointers to streams per severity_t

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

array of pointers to streams per severity_t

StreamFactory* ers::StreamFactory::s_instance [static, protected]

singleton instance

ers::StreamFactory * ers::StreamFactory::s_instance = 0 [static, protected]

singleton instance Pointer to the singleton instance

---

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

• /data0/mdestefa/bes3soft/Boss_6.5.5/dist/6.5.5/Event/ers/ers-00-00-01/ers/StreamFactory.h
• /data0/mdestefa/bes3soft/Boss_6.5.5/dist/6.5.5/InstallArea/include/ers/ers/StreamFactory.h
• /data0/mdestefa/bes3soft/Boss_6.5.5/dist/6.5.5/Event/ers/ers-00-00-01/src/StreamFactory.cxx

---