Ceylan::Object Class Reference

This abstract mother class, root of the whole Ceylan object's hierarchy, plays a very similar role to java.lang.Object, namely describing the basic services every Ceylan object should be able to provide. More...

#include <CeylanObject.h>

Inheritance diagram for Ceylan::Object:
Inheritance graph
[legend]
Collaboration diagram for Ceylan::Object:
Collaboration graph
[legend]

List of all members.

Public Types

enum  TextOutputFormat { rawText, html }
 

Defines what text output formats for TextDisplayable instances are available.

More...
enum  TextOutputFormat { rawText, html }
 

Defines what text output formats for TextDisplayable instances are available.

More...

Public Member Functions

 Object (bool trackInstance=true, bool dropIdentifierOnExit=true)
 Constructs a brand new Ceylan::Object.
virtual ~Object () throw ()
 Basic do-nothing destructor used to force virtual destructors in the hierarchy.
virtual const std::string getClassName () const
virtual bool isOfSameType (const Object &other) const
 Returns whether other is an instance of the same type as this object.
virtual void logState (Ceylan::VerbosityLevels level=Ceylan::high)
 Uses its dedicated log channel to display its state.
virtual void send (const std::string &message, Log::LevelOfDetail levelOfDetail=Log::DefaultLevelOfDetailForMessage)
 Sends message to the internal channel.
virtual void forgeIdentifier ()
 Forges this object's identifier.
virtual const std::string toString (Ceylan::VerbosityLevels level=Ceylan::high) const
 Returns a user-friendly description of the state of this object.
IdentifiergetIdentifier () const
 Returns this IdentifierOwner's identifier.
void setIdentifier (Identifier &id)
 Sets this IdentifierOwner's identifier.
bool hasIdentifier () const
 Returns whether this IdentifierOwner has a stored identifier.
void deleteIdentifier ()
 Deletes this IdentifierOwner's identifier.
void setChannelName (const std::string &channelName)
 Sets this Logable channel name.
bool hasChannelName () const
 Returns whether this Log source has a registered channel name.
std::string getChannelName () const
 Returns this LogSource channel name.
void setLevelOfDetail (LevelOfDetail newLevel)
 Sets this LogSource level of detail of interest.
LevelOfDetail getLevelOfDetail () const
 Returns this LogSource channel name.
virtual void sendToChannel (const std::string &channel, const std::string &message, LevelOfDetail levelOfDetail=DefaultLevelOfDetailForMessage) const
 Sends message to the specified channel, through known LogTransport.
virtual void setTransport (LogTransport &newTransport)
 Sets a new Log transport for this LogSource.
virtual LogTransportgetTransport () const
 Returns this LogSource's Log transport.
virtual bool hasTransport () const
 Tells whether this LogSource has a registered Log transport.

Static Public Member Functions

static const std::string ToString (std::list< TextDisplayable * > displayables, Ceylan::VerbosityLevels level=Ceylan::high)
 Returns a user-friendly description of this list of pointers to text displayable instances.
static TextOutputFormat GetOutputFormat ()
 Returns the current overall text format to be used by TextDisplayable instances.
static void SetOutputFormat (TextOutputFormat newOutputFormat)
 Sets the current overall text format to be used by TextDisplayable instances.
static bool IsALoggableChannelName (const std::string &channelName)
 Returns whether the specified channel name is an object channel name, based on the possible presence of the protocol prefix and separators (typically, loggable://).
static const std::string GetEmbeddedChannelName (const std::string &fullChannelName)
 Returns the real channel name used by a Loggable by removing the protocol prefix and separators (typically, 'loggable://').
static const std::string ToString (std::list< TextDisplayable * > displayables, Ceylan::VerbosityLevels level=Ceylan::high)
 Returns a user-friendly description of this list of pointers to text displayable instances.
static TextOutputFormat GetOutputFormat ()
 Returns the current overall text format to be used by TextDisplayable instances.
static void SetOutputFormat (TextOutputFormat newOutputFormat)
 Sets the current overall text format to be used by TextDisplayable instances.

Static Public Attributes

static const std::string ProtocolName = "loggable"
static const LevelOfDetail DefaultLevelOfDetailForSource = 10
 The default level of detail of a Log source.

Protected Member Functions

void dropIdentifier ()
 Removes this Object's identifier, in order to avoid class name mangling.
virtual void directSend (const std::string &channel, const std::string &message, LevelOfDetail levelOfDetail=DefaultLevelOfDetailForMessage) const
 Internal method to send messages.
virtual void unlinkTransport ()
 Suppresses the link between this LogSource and its Log transport.

Protected Attributes

bool _trackInstance
 Tells whether this instance's lifecycle should be advertised in log system.
std::string _channelName
 Stores this LogSource channel name.
LevelOfDetail _level
 The current level of detail of interest for this Log source.
LogTransport * _transport
 The LogTransport to be used for sending messages.

Static Protected Attributes

static TextOutputFormat _OutputFormat = rawText
 The text format to be used currently by TextDisplayable instances.
static TextOutputFormat _OutputFormat = rawText
 The text format to be used currently by TextDisplayable instances.

Private Member Functions

 Object (const Object &source)
 Copy constructor made private to ensure that it will be never called.
Objectoperator= (const Object &source)
 Assignment operator made private to ensure that it will be never called.

Detailed Description

This abstract mother class, root of the whole Ceylan object's hierarchy, plays a very similar role to java.lang.Object, namely describing the basic services every Ceylan object should be able to provide.

One of the services provided is that each Ceylan::Object can have its own private log channel. The resource overhead for that behaviour (identifier building, message propagating, etc.) will be non-null if and only if this service is actually used, apart some very minor costs.

Definition at line 58 of file CeylanObject.h.


Member Enumeration Documentation

Defines what text output formats for TextDisplayable instances are available.

Enumerator:
rawText 
html 

Definition at line 124 of file CeylanTextDisplayable.h.

Defines what text output formats for TextDisplayable instances are available.

Enumerator:
rawText 
html 

Definition at line 124 of file CeylanTextDisplayable.h.


Constructor & Destructor Documentation

Object::Object ( bool  trackInstance = true,
bool  dropIdentifierOnExit = true 
) [explicit]

Constructs a brand new Ceylan::Object.

Parameters:
trackInstance tells whether the created instances's lifecycle is to be watched through the log system (ex: deallocation notice).
dropIdentifierOnExit if trackInstance is true, then a mangled message has been emitted (since the instance tracking has to be made in the constructor), the identifier will therefore have to be forged again. Setting dropIdentifierOnExit to true will cause the identifier to be rebuilt on the next sending after the constructor call, which is what should be done if no more messages are to be sent from Object's child constructors. If, on the contrary, the instance inherits from Object and has to send more messages from child constructors, then dropIdentifierOnExit should better be false, and after the last statement of the deepest constructor, a call to Object::dropIdentifier would have to be done to rely on an unmangled relevant identifier.

LogException in case of failure.

Note:
This object's identifier will not be computed as long as it is not needed.
Beware of Ceylan::Objects instanciated as automatic variables: they share their mother type (Ceylan::Object), they are on the same host and PID, and they have the same address: they might be mixed up by the log system. One way to spot that is when an object channel as more than one "Being allocated now." sentence.

Definition at line 54 of file CeylanObject.cc.

References _trackInstance, CEYLAN_LOG, dropIdentifier(), and send().

Object::~Object (  )  throw () [virtual]

Basic do-nothing destructor used to force virtual destructors in the hierarchy.

Definition at line 85 of file CeylanObject.cc.

References _trackInstance, CEYLAN_LOG, and send().

Ceylan::Object::Object ( const Object source  )  [private]

Copy constructor made private to ensure that it will be never called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.


Member Function Documentation

void IdentifierOwner::deleteIdentifier (  )  [inherited]

Deletes this IdentifierOwner's identifier.

Definition at line 128 of file CeylanIdentifierOwner.cc.

References Ceylan::IdentifierOwner::_id, and Ceylan::emergencyShutdown().

Referenced by dropIdentifier(), and Ceylan::IdentifierOwner::~IdentifierOwner().

void LogSource::directSend ( const std::string &  channel,
const std::string &  message,
LevelOfDetail  levelOfDetail = DefaultLevelOfDetailForMessage 
) const [protected, virtual, inherited]

Internal method to send messages.

Filters them out if their level of detail is higher than the one of this log source.

Definition at line 164 of file CeylanLogSource.cc.

References Ceylan::Log::LogSource::_transport, and Ceylan::Log::LogTransport::propagate().

Referenced by Ceylan::Log::LogSource::send(), and Ceylan::Log::LogSource::sendToChannel().

void Object::dropIdentifier (  )  [protected]

Removes this Object's identifier, in order to avoid class name mangling.

Note:
This method should be used at least after the last message sent from an Object's deepest constructor (the final child).

Definition at line 261 of file CeylanObject.cc.

References Ceylan::IdentifierOwner::deleteIdentifier().

Referenced by forgeIdentifier(), and Object().

void Object::forgeIdentifier (  )  [virtual]

Forges this object's identifier.

See also:
TextIdentifier
Exceptions:
Log::LogException if the identifier could not be forged.

Definition at line 211 of file CeylanObject.cc.

References CEYLAN_LOG, dropIdentifier(), Ceylan::IdentifierOwner::getIdentifier(), Ceylan::IdentifierOwner::hasIdentifier(), Ceylan::IdentifierOwner::setIdentifier(), toString(), and Ceylan::Exception::toString().

std::string LogSource::getChannelName (  )  const [inherited]

Returns this LogSource channel name.

Definition at line 101 of file CeylanLogSource.cc.

References Ceylan::Log::LogSource::_channelName.

Referenced by Ceylan::Log::LogSource::toString().

const std::string Object::getClassName (  )  const [virtual]

Definition at line 102 of file CeylanObject.cc.

References CEYLAN_LOG.

Referenced by isOfSameType().

const string Loggable::GetEmbeddedChannelName ( const std::string &  fullChannelName  )  [static, inherited]
Identifier & IdentifierOwner::getIdentifier (  )  const [inherited]

Returns this IdentifierOwner's identifier.

Exceptions:
IdentifierNotAvailableException if the operation failed.

Definition at line 83 of file CeylanIdentifierOwner.cc.

References Ceylan::IdentifierOwner::_id.

Referenced by forgeIdentifier().

LevelOfDetail LogSource::getLevelOfDetail (  )  const [inherited]

Returns this LogSource channel name.

Definition at line 119 of file CeylanLogSource.cc.

References Ceylan::Log::LogSource::_level.

TextDisplayable::TextOutputFormat TextDisplayable::GetOutputFormat (  )  [static, inherited]
TextDisplayable::TextOutputFormat TextDisplayable::GetOutputFormat (  )  [static, inherited]
LogTransport * LogSource::getTransport (  )  const [virtual, inherited]

Returns this LogSource's Log transport.

Definition at line 209 of file CeylanLogSource.cc.

References Ceylan::Log::LogSource::_transport.

bool LogSource::hasChannelName (  )  const [inherited]

Returns whether this Log source has a registered channel name.

Definition at line 83 of file CeylanLogSource.cc.

References Ceylan::Log::LogSource::_channelName.

Referenced by Ceylan::Log::LogSource::toString().

bool IdentifierOwner::hasIdentifier (  )  const [inherited]

Returns whether this IdentifierOwner has a stored identifier.

Definition at line 119 of file CeylanIdentifierOwner.cc.

References Ceylan::IdentifierOwner::_id.

Referenced by forgeIdentifier(), and Ceylan::IdentifierOwner::~IdentifierOwner().

bool LogSource::hasTransport (  )  const [virtual, inherited]

Tells whether this LogSource has a registered Log transport.

Definition at line 218 of file CeylanLogSource.cc.

References Ceylan::Log::LogSource::_transport.

Referenced by Ceylan::Log::LogSource::setTransport().

bool Loggable::IsALoggableChannelName ( const std::string &  channelName  )  [static, inherited]

Returns whether the specified channel name is an object channel name, based on the possible presence of the protocol prefix and separators (typically, loggable://).

Definition at line 73 of file CeylanLoggable.cc.

References Ceylan::URI::getProtocolName(), Ceylan::Log::Loggable::ProtocolName, and Ceylan::URI::ProtocolSeparator.

Referenced by Ceylan::Log::LogAggregator::findChannel(), and Ceylan::Log::LogAggregator::store().

bool Object::isOfSameType ( const Object other  )  const [virtual]

Returns whether other is an instance of the same type as this object.

Parameters:
other the object whose type is to be compared with this object's type.
See also:
getClassName

Definition at line 140 of file CeylanObject.cc.

References getClassName().

void Object::logState ( Ceylan::VerbosityLevels  level = Ceylan::high  )  [virtual]

Uses its dedicated log channel to display its state.

Note:
This is the very convenient combination of a Loggable and a TextDisplayable: it requests this Object to log its textual representation in its own channel.
Parameters:
level chooses the level of detail
Note:
This method cannot have the const qualifier since the send method might have to forge a new identifier.

Definition at line 149 of file CeylanObject.cc.

References send(), and toString().

Object& Ceylan::Object::operator= ( const Object source  )  [private]

Assignment operator made private to ensure that it will be never called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

virtual void Ceylan::Object::send ( const std::string &  message,
Log::LevelOfDetail  levelOfDetail = Log::DefaultLevelOfDetailForMessage 
) [virtual]

Sends message to the internal channel.

Parameters:
message the log message to send. Please avoid characters '<' and '>' since they have a special meaning for HTML log output. These characters used to be filtered in HTML aggregators but it prevented messages to contain HTML tags on purpose, which proved to be convenient in the case only HTML aggregators are to be used.
levelOfDetail the level of detail of this message (level 5 by default).
Exceptions:
Log::LogException if the operation failed.
Note:
This method had to be overriden because when forging the identifier from the object constructor, the class name is mangled. So we delay the construction of the identifier until the first log message in internal channel is sent. This is an elegant solution too, since objects which will not send messages on their private channel will not have to construct their identifier.
There may be a small lag when the first send is called, due to the identifier construction.
This method cannot have the const qualifier since it might have to forge a new identifier.

Reimplemented from Ceylan::Log::LogSource.

Referenced by logState(), Ceylan::Module::Module(), Object(), Ceylan::Module::~Module(), and ~Object().

void LogSource::sendToChannel ( const std::string &  channel,
const std::string &  message,
LevelOfDetail  levelOfDetail = DefaultLevelOfDetailForMessage 
) const [virtual, inherited]

Sends message to the specified channel, through known LogTransport.

Note:
This method is to be used when a message is to be sent to a channel different from the LogSource's internal one.
Parameters:
channel the channel name which will identify the targeted Loglistener.
message the log message to send. Please avoid characters '<' and '>' since they have a special meaning for HTML log output. These characters used to be filtered in HTML aggregators but it prevented messages to contain HTML tags on purpose, which proved to be convenient.
levelOfDetail the level of detail of this message (level 1 by default).
See also:
send with implied internal channel

Definition at line 142 of file CeylanLogSource.cc.

References Ceylan::Log::LogSource::_level, CEYLAN_LOG, Ceylan::Log::LogSource::directSend(), and Ceylan::toString().

void Loggable::setChannelName ( const std::string &  channelName  )  [inherited]

Sets this Logable channel name.

Reimplemented from Ceylan::Log::LogSource.

Definition at line 63 of file CeylanLoggable.cc.

References Ceylan::Log::Loggable::ProtocolName, and Ceylan::URI::ProtocolSeparator.

Referenced by Ceylan::Log::Loggable::Loggable().

void IdentifierOwner::setIdentifier ( Identifier id  )  [inherited]

Sets this IdentifierOwner's identifier.

Exceptions:
IdentifierNotAvailableException if the operation failed.
Note:
This IdentifierOwner takes ownership of provided identifier.

Definition at line 101 of file CeylanIdentifierOwner.cc.

References Ceylan::IdentifierOwner::_id.

Referenced by forgeIdentifier().

void LogSource::setLevelOfDetail ( LevelOfDetail  newLevel  )  [inherited]

Sets this LogSource level of detail of interest.

Definition at line 110 of file CeylanLogSource.cc.

References Ceylan::Log::LogSource::_level.

void TextDisplayable::SetOutputFormat ( TextOutputFormat  newOutputFormat  )  [static, inherited]

Sets the current overall text format to be used by TextDisplayable instances.

Parameters:
newOutputFormat the new output format.

Definition at line 72 of file CeylanTextDisplayable.cc.

References Ceylan::TextDisplayable::_OutputFormat.

Referenced by Ceylan::Log::LogHolder::LogHolder().

void TextDisplayable::SetOutputFormat ( TextOutputFormat  newOutputFormat  )  [static, inherited]

Sets the current overall text format to be used by TextDisplayable instances.

Parameters:
newOutputFormat the new output format.

Definition at line 72 of file CeylanTextDisplayable.cc.

References Ceylan::TextDisplayable::_OutputFormat.

Referenced by Ceylan::Log::LogHolder::LogHolder().

void LogSource::setTransport ( LogTransport newTransport  )  [virtual, inherited]
const std::string TextDisplayable::ToString ( std::list< TextDisplayable * >  displayables,
Ceylan::VerbosityLevels  level = Ceylan::high 
) [static, inherited]

Returns a user-friendly description of this list of pointers to text displayable instances.

Parameters:
displayables a list of pointers to TextDisplayable instances/
level the requested verbosity level.
Note:
Text output format is determined from overall settings.
See also:
toString, Ceylan::VerbosityLevels

Definition at line 45 of file CeylanTextDisplayable.cc.

References Ceylan::formatStringList().

const std::string TextDisplayable::ToString ( std::list< TextDisplayable * >  displayables,
Ceylan::VerbosityLevels  level = Ceylan::high 
) [static, inherited]

Returns a user-friendly description of this list of pointers to text displayable instances.

Parameters:
displayables a list of pointers to TextDisplayable instances/
level the requested verbosity level.
Note:
Text output format is determined from overall settings.
See also:
toString, Ceylan::VerbosityLevels

Definition at line 45 of file CeylanTextDisplayable.cc.

References Ceylan::formatStringList().

const string Object::toString ( Ceylan::VerbosityLevels  level = Ceylan::high  )  const [virtual]

Returns a user-friendly description of the state of this object.

Parameters:
level the requested verbosity level.
Note:
Text output format is determined from overall settings.
See also:
TextDisplayable

Reimplemented from Ceylan::IdentifierOwner.

Reimplemented in Ceylan::Maths::Random::RandomGenerator, Ceylan::Maths::Random::RandomGeneratorFromPDF, Ceylan::Maths::Random::WhiteNoiseGenerator, Ceylan::Module, and Ceylan::Plugin.

Definition at line 191 of file CeylanObject.cc.

References _trackInstance.

Referenced by forgeIdentifier(), and logState().

void LogSource::unlinkTransport (  )  [protected, virtual, inherited]

Suppresses the link between this LogSource and its Log transport.

Definition at line 243 of file CeylanLogSource.cc.

Referenced by Ceylan::Log::LogSource::setTransport(), and Ceylan::Log::LogSource::~LogSource().


Member Data Documentation

std::string Ceylan::Log::LogSource::_channelName [protected, inherited]
LevelOfDetail Ceylan::Log::LogSource::_level [protected, inherited]
TextDisplayable::TextOutputFormat TextDisplayable::_OutputFormat = rawText [static, protected, inherited]

The text format to be used currently by TextDisplayable instances.

Note:
Defaults to raw text.

Definition at line 158 of file CeylanTextDisplayable.h.

Referenced by Ceylan::TextDisplayable::GetOutputFormat(), and Ceylan::TextDisplayable::SetOutputFormat().

TextDisplayable::TextOutputFormat TextDisplayable::_OutputFormat = rawText [static, protected, inherited]

The text format to be used currently by TextDisplayable instances.

Note:
Defaults to raw text.

Definition at line 158 of file CeylanTextDisplayable.h.

Referenced by Ceylan::TextDisplayable::GetOutputFormat(), and Ceylan::TextDisplayable::SetOutputFormat().

Tells whether this instance's lifecycle should be advertised in log system.

Definition at line 254 of file CeylanObject.h.

Referenced by Object(), toString(), and ~Object().

LogTransport* Ceylan::Log::LogSource::_transport [protected, inherited]
const LevelOfDetail Ceylan::Log::LogSource::DefaultLevelOfDetailForSource = 10 [static, inherited]

The default level of detail of a Log source.

Definition at line 221 of file CeylanLogSource.h.

const string Loggable::ProtocolName = "loggable" [static, inherited]

The documentation for this class was generated from the following files:
Generated on Mon Nov 29 13:40:47 2010 for Ceylan by  doxygen 1.6.3