ers::StreamFactory

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

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

Supported Keys - System package:

The System package supports the following keys:

Supported Keys - ers-ipc package:

The ersipc package supports the following keys:

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

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

Definition at line 122 of file StreamFactory.h.

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

Definition at line 123 of file StreamFactory.h.

Constructor & Destructor Documentation

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.

References genRecEmupikp::i, m_streams, s, ers::severity_max, and ers::severity_none.

Referenced by instance().

00043                                 {
00044    for(int i= static_cast<int> (severity_none);i< static_cast<int> (severity_max);i++) {        
00045         severity_t s = static_cast<severity_t> (i) ; 
00046        m_streams[s]=0 ;
00047    } // for*/
00048 } // 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

Definition at line 55 of file StreamFactory.cxx.

References ERS_NOT_IMPLEMENTED, and EvtCyclic3::other().

00055                                                           {
00056     (void) other ; // shut up the compiler 
00057     ERS_NOT_IMPLEMENTED(); 
00058 } // 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.

References genRecEmupikp::i, m_streams, s, ers::severity_max, and ers::severity_none.

00064                                  {
00065     for(int i= static_cast<int> (severity_none);i< static_cast<int> (severity_max);i++) {       
00066         severity_t s = static_cast<severity_t> (i) ; 
00067         if(m_streams[s]) {
00068             delete(m_streams[s]);
00069             m_streams[s]=0 ; 
00070         } // if stream 
00071     } // for*/
00072 } // ~StreamFactory

Member Function Documentation

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.

References m_factories, RealDBUtil::npos, boss::pos, s, and deljobs::string.

00143                                                                      {
00144     std::string protocol ; 
00145     std::string uri ; 
00146 
00147     std::string::size_type colon = key.find(':') ; 
00148     if (colon==std::string::npos) {
00149         protocol = key ; 
00150     } else {
00151         protocol = key.substr(0,colon) ; 
00152         std::string::size_type uri_start = colon+1 ; 
00153         if (uri_start<key.size()) {
00154             uri = key.substr(uri_start) ; 
00155         } // if
00156     } // colon present 
00157     for(stream_factory_collection::const_iterator pos=m_factories.begin();pos!=m_factories.end();++pos) {
00158         create_stream_callback callback = pos->second; 
00159         Stream *s = callback(protocol,uri); 
00160         if (s!=0) return s ; 
00161     } // for
00162     fprintf(stderr,"Warning, could not find stream for key protocol=\"%s\" uri=\"%s\" (%s)\n",protocol.c_str(),uri.c_str(),key.c_str()); 
00163     return new DefaultStream(); 
00164 } // 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.

Definition at line 176 of file StreamFactory.cxx.

References key, and key_for_severity().

Referenced by ers::FilterStream::factory(), get_stream(), and set().

00176                                                        {
00177     const char* key = key_for_severity(s); 
00178     return create_stream(key); 
00179 } // get_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

Definition at line 347 of file StreamFactory.cxx.

References ERS_PRECONDITION, get_stream(), ers::severity_none, and ers::Core::to_string().

00347                                                 {
00348     ERS_PRECONDITION(s<ers::information && s>ers::severity_none,"severity_t is not debug : %s (%d)",ers::Core::to_string(s),s);
00349     return get_stream(s) ; 
00350 } // 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

Definition at line 231 of file StreamFactory.cxx.

References debug().

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

Definition at line 218 of file StreamFactory.cxx.

References dispatch(), ERS_PRE_CHECK_PTR, ERS_PRECONDITION, ers::information, ers::Issue::severity(), and ers::Core::to_string().

Referenced by debug().

00218                                                            {
00219     ERS_PRE_CHECK_PTR(issue_ptr); 
00220     ERS_PRECONDITION(s<ers::information,"severity_t is not debug : %s (%d) %d",ers::Core::to_string(s),s,ers::information);
00221     issue_ptr->severity(s) ; 
00222     dispatch(issue_ptr,false);
00223 } //  debug

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

Definition at line 264 of file StreamFactory.cxx.

References dispatch().

00264                                                                   {
00265         dispatch(&issue_ref,throw_error); 
00266 } // 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

Definition at line 254 of file StreamFactory.cxx.

References ERS_CHECK_PTR, ERS_PRE_CHECK_PTR, get_stream(), instance(), ers::Issue::is_error(), s, ers::Stream::send(), and ers::Issue::severity().

Referenced by debug(), dispatch(), error(), fatal(), main(), and warning().

00254                                                                   {
00255     ERS_PRE_CHECK_PTR(issue_ptr); 
00256     if (throw_error && issue_ptr->is_error()) { throw *issue_ptr  ; } 
00257     const severity_t s = issue_ptr->severity() ;
00258     Stream *stream_ptr =  instance()->get_stream(s) ; 
00259     ERS_CHECK_PTR(stream_ptr);
00260     stream_ptr->send(issue_ptr); 
00261 } // dispatch

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

Error stream.

Returns:
the current error stream

Definition at line 332 of file StreamFactory.cxx.

References ers::error, and get_stream().

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

Definition at line 196 of file StreamFactory.cxx.

References dispatch(), ers::error, ERS_PRE_CHECK_PTR, and ers::Issue::severity().

00196                                              {
00197     ERS_PRE_CHECK_PTR(issue_ptr); 
00198     issue_ptr->severity(ers::error); 
00199     dispatch(issue_ptr,false); 
00200 } // error

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

Fatal stream.

Returns:
the current fatal stream

Definition at line 326 of file StreamFactory.cxx.

References ers::fatal, and get_stream().

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

Definition at line 186 of file StreamFactory.cxx.

References dispatch(), ERS_PRE_CHECK_PTR, ers::fatal, and ers::Issue::severity().

00186                                              {
00187     ERS_PRE_CHECK_PTR(issue_ptr); 
00188     issue_ptr->severity(ers::fatal); 
00189     dispatch(issue_ptr,false); 
00190 } // fatal

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

Definition at line 104 of file StreamFactory.cxx.

References get_stream(), and instance().

00104                                                             {
00105     return instance()->get_stream(s) ; 
00106 } // get_default_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.

References create_stream(), and m_streams.

Referenced by debug(), dispatch(), error(), fatal(), get_default_stream(), and warning().

00283                                                       {
00284     if (m_streams[s]==0) {
00285         m_streams[s]=create_stream(s) ; 
00286     } // if 
00287     return m_streams[s] ; 
00288 } // get_stream

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.

References s_instance, and StreamFactory().

Referenced by dispatch(), ers::FilterStream::factory(), get_default_stream(), print_registered(), and set_stream().

00080                                              {
00081     if (0==s_instance) {
00082         s_instance = new StreamFactory(); 
00083     } // if
00084     return s_instance ; 
00085 } // instance

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.

Definition at line 119 of file StreamFactory.cxx.

References DEFAULT_STREAMS, ers::DefaultStream::KEY, and ers::Core::to_string().

Referenced by create_stream().

00119                                                            {
00120     char key_buffer[64] ; 
00121     snprintf(key_buffer,sizeof(key_buffer),"ERS_%s",ers::Core::to_string(s)) ;
00122     char *c = &(key_buffer[0]);
00123     while(*c) {
00124         *c = toupper(*c) ;
00125         c++ ;
00126     } // while
00127     const char *env = ::getenv(key_buffer) ; 
00128     if (env!=0) return env ;
00129     const char* static_key = DEFAULT_STREAMS[s] ; 
00130     if (static_key) return static_key ; 
00131     return ers::DefaultStream::KEY ; 
00132 } // key_for_severity

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

Dumps all registered types of streams

Definition at line 89 of file StreamFactory.cxx.

References factory(), and instance().

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

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.

References m_factories, and true.

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

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.

References create_stream(), ERS_PRE_CHECK_PTR, s, and set().

00316                                                                {
00317     ERS_PRE_CHECK_PTR(key); 
00318     Stream *s = create_stream(key);
00319     set(severity,s); 
00320 } //

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.

References ERS_PRE_CHECK_PTR, ERS_PRECONDITION, m_streams, s, ers::severity_max, and ers::severity_none.

Referenced by set(), and set_stream().

00299                                                          {
00300     ERS_PRE_CHECK_PTR(s); 
00301     ERS_PRECONDITION(severity_none < severity && severity < severity_max,"illegal severity_t %d",(int) severity);
00302     if (m_streams[severity]) {
00303         delete m_streams[severity] ;
00304     } // if there is a stream defined 
00305     m_streams[severity] = s ; 
00306 } // stream

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

Definition at line 269 of file StreamFactory.cxx.

References instance(), and set().

Referenced by main(), and massive_test().

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

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

Warning stream.

Returns:
the current warning stream

Definition at line 338 of file StreamFactory.cxx.

References get_stream(), and ers::warning.

Referenced by main(), and warning().

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

Definition at line 241 of file StreamFactory.cxx.

References warning(), and ers::warning.

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

Definition at line 206 of file StreamFactory.cxx.

References dispatch(), ERS_PRE_CHECK_PTR, ers::Issue::severity(), and ers::warning.

00206                                                {
00207     ERS_PRE_CHECK_PTR(issue_ptr); 
00208     issue_ptr->severity(ers::warning); 
00209     dispatch(issue_ptr,false); 
00210 } // warning

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.

References genRecEmupikp::i, m_factories, boss::pos, and deljobs::string.

00378                                                         {
00379     stream << "Stream factory - registered streams\n" ; 
00380     stream << "-----------------------------------\n" ; 
00381     int i = 0 ; 
00382     for(stream_factory_collection::const_iterator pos=m_factories.begin();pos!=m_factories.end();++pos) {
00383         std::string name = pos->first; 
00384         stream << i << ")\t" << name << std::endl; 
00385         i++ ; 
00386     } // for
00387     stream << "-----------------------------------\n" ; 
00388 } // write_to

Member Data Documentation

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.

Definition at line 126 of file StreamFactory.h.

Referenced by key_for_severity().

stream_factory_collection ers::StreamFactory::m_factories [protected]

collection of factories to build streams

Definition at line 134 of file StreamFactory.h.

Referenced by create_stream(), register_factory(), and write_to().

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 get_stream(), set(), StreamFactory(), and ~StreamFactory().

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

singleton instance

Pointer to the singleton instance

Definition at line 125 of file StreamFactory.h.

Referenced by instance().

Generated on Tue Nov 29 23:36:32 2016 for BOSS_7.0.2 by  doxygen 1.4.7