OBMessageHandler Class Reference

Handle error messages, warnings, debugging information and the like. More...

#include <openbabel/oberror.h>

List of all members.

Public Member Functions

 OBMessageHandler ()
 ~OBMessageHandler ()
void ThrowError (OBError err, errorQualifier qqualifier=always)
void ThrowError (const std::string &method, const std::string &errorMsg, obMessageLevel level=obDebug, errorQualifier qualifier=always)
std::vector< std::string > GetMessagesOfLevel (const obMessageLevel)
void StartLogging ()
void StopLogging ()
void SetMaxLogEntries (unsigned int max)
unsigned int GetMaxLogEntries ()
void ClearLog ()
void SetOutputLevel (const obMessageLevel level)
obMessageLevel GetOutputLevel ()
void SetOutputStream (std::ostream *os)
std::ostream * GetOutputStream ()
bool StartErrorWrap ()
bool StopErrorWrap ()
unsigned int GetErrorMessageCount ()
unsigned int GetWarningMessageCount ()
unsigned int GetInfoMessageCount ()
unsigned int GetAuditMessageCount ()
unsigned int GetDebugMessageCount ()
std::string GetMessageSummary ()

Protected Attributes

unsigned int _messageCount [5]
std::deque< OBError > _messageList
obMessageLevel _outputLevel
std::ostream * _outputStream
bool _logging
unsigned int _maxEntries
std::streambuf * _inWrapStreamBuf
std::streambuf * _filterStreamBuf

Detailed Description

Handle error messages, warnings, debugging information and the like.

OBMessageHandler represents a configurable error system for Open Babel.

A global error log is defined by the Open Babel library for use of internal code as well as code built on top of Open Babel. This class allows flexible filtering based on urgency (defined by the obMessageLevel type), an "audit log" of molecular changes, including recall using the GetMessagesOfLevel method, etc.

The default is to only log and output errors of priority obMessageLevel::obError or obMessageLevel::obWarning.

Long-running code may wish to set the size of the in-memory error log using the StartLogging / StopLogging methods and SetMaxLogEntries. Otherwise, the error log may easily fill up, requiring large amounts of memory.

If you wish to divert error output to a different std::ostream (i.e., for graphical display, or a file log), use the SetOutputStream method -- the default goes to the std::clog stream. Furthermore, some older code uses std::cerr for direct error output, rather than the ThrowError() methods in this class. To prevent this, you can turn on "error wrapping" using the StartErrorWrap method -- this behavior is turned off by default.

To make it easy to use the OBMessageHandler class and error logging facilities, a global log is defined:

  OBERROR extern OBMessageHandler obErrorLog;

Therefore, it is very easy to log errors:

  if (atomIndex < 1 || atomIndex > mol.NumAtoms() )
     obErrorLog.ThrowError(__FUNCTION__, "Requested Atom Out of Range", obDebug);

or

  stringstream errorMsg;
  errorMsg << " Could not parse line in type translation table types.txt -- incorect number of columns";
  errorMsg << " found " << vc.size() << " expected " << _ncols << ".";
  obErrorLog.ThrowError(__FUNCTION__, errorMsg.str(), obInfo);

The __FUNCTION__ builtin is defined by many compilers (e.g., GCC) but can be defined to an empty string on some platforms without this compiler extension.

Output from the error log typically looks like: 

  ==============================
 Open Babel Audit Log  in ReadChemObject
  OpenBabel::Read molecule Protein Data Bank format
  ==============================
 Open Babel Information  in ParseConectRecord
  WARNING: Problems reading a PDB file
  Problems reading a CONECT record.
  According to the PDB specification,
  the record should have 70 columns, but OpenBabel found 61 columns.

Constructor & Destructor Documentation

OBMessageHandler (  ) 

~OBMessageHandler (  ) 

Member Function Documentation

void ThrowError ( OBError  err,
errorQualifier  qqualifier = always 
)

Throw an error with an already-formatted OBError object.

Referenced by FastSearchIndexer::Add(), OBChiralData::AddAtomRef(), OBMol::AddBond(), OBConversion::AddChemObject(), OBMol::AddHydrogens(), OBDescriptor::AddProperties(), OBMol::Align(), OpenBabel::AllocateByteCode(), OBChemTsfm::Apply(), patty::assign_types(), OBAromaticTyper::AssignAromaticFlags(), OBAtomTyper::AssignHyb(), OBAtomTyper::AssignImplicitValence(), OBGastChrg::AssignPartialCharges(), OBMol::AssignSpinMultiplicity(), OBRingTyper::AssignTypes(), OBAtomTyper::AssignTypes(), OpenBabel::CalcSignedVolume(), OpenBabel::CartesianToInternal(), OBMol::Center(), OBConversion::CheckForUnintendedBatch(), FptIndex::CheckFP(), OBMol::Clear(), OBDescriptor::Compare(), OBDescriptor::CompareStringWithFilter(), OBMol::ConnectTheDots(), OBConversion::Convert(), OBMol::ConvertDativeBonds(), OpenBabel::CorrectBadResonanceForm(), OBPhModel::CorrectForPH(), OBMol::CorrectForPH(), OBMoleculeFormat::DeferMolOutput(), OBMol::DeleteHydrogens(), OBMol::DeleteNonPolarHydrogens(), OBMol::DoTransformations(), OBMol::EndModify(), OBMol::expand_kekulize(), OpenBabel::FatalAllocationError(), OpenBabel::FatalMemoryError(), OBDescriptor::FilterCompare(), SpaceGroup::Find(), FastSearch::Find(), OBMol::FindChiralCenters(), OBMol::FindRingAtomsAndBonds(), OBRotorList::FindRotors(), OBMol::FindSSSR(), OBFingerprint::Fold(), OBBitVec::FromString(), OBConversion::FullConvert(), OpenBabel::GenerateByteCodes(), OBMol::GetAtom(), OBChiralData::GetAtom4Refs(), OpenBabel::GetAtomIDNumber(), OBChiralData::GetAtomRef(), OBMol::GetBond(), OBMol::GetFormula(), OBMol::GetResidue(), OBRotorRules::GetRotorIncrements(), OBChiralData::GetSize(), OBMol::GetTotalCharge(), OBMol::GetTotalSpinMultiplicity(), OBDescriptor::GetValues(), OBAtom::HtoMethyl(), OBGlobalDataBase::Init(), OpenBabel::InternalToCartesian(), OBBond::IsClosure(), OBMol::Kekulize(), OBConversion::LoadFormatFiles(), OBBuilder::LoadFragments(), OBMoleculeFormat::MakeCombinedMolecule(), OBMol::NewPerceiveKekuleBonds(), OBConversion::OpenAndSetFormat(), OBConversion::OpenInAndOutFiles(), OpenBabel::operator>>(), OBMoleculeFormat::OutputDeferredMols(), OBAromaticTyper::ParseLine(), OBRingTyper::ParseLine(), OBAtomTyper::ParseLine(), OBRotorRules::ParseLine(), OBPhModel::ParseLine(), OBTypeTable::ParseLine(), OBIsotopeTable::ParseLine(), OBBondTyper::ParseLine(), OBMol::PerceiveBondOrders(), OBChainsParser::PerceiveChains(), patty::read_rules(), OBMoleculeFormat::ReadChemObjectImpl(), OBConversion::ReadFile(), OBMoleculeFormat::ReadNameIndex(), OBDescriptor::ReadStringFromFilter(), OBConversion::RegisterOptionParam(), OBRotorList::RemoveSymVals(), OBMol::RenumberAtoms(), OBMol::Rotate(), OpenBabel::SafeOpen(), OBChiralData::SetAtom4Refs(), OBTypeTable::SetFromType(), OBAtom::SetHybAndGeom(), OBBond::SetLength(), OBMol::SetTorsion(), OBTypeTable::SetToType(), OBRotorList::Setup(), OpenBabel::SMARTSError(), OBMol::start_kekulize(), OBMol::StripSalts(), obLogBuf::sync(), OpenBabel::ThrowError(), OBMessageHandler::ThrowError(), OBMol::ToInertialFrame(), OBMol::Translate(), OBTypeTable::Translate(), patty::type_to_int(), OBMoleculeFormat::WriteChemObjectImpl(), OBConversion::WriteFile(), and FastSearchIndexer::~FastSearchIndexer().

void ThrowError ( const std::string &  method,
const std::string &  errorMsg,
obMessageLevel  level = obDebug,
errorQualifier  qualifier = always 
)

Throw an error in the specified method with an appropriate level.

std::vector< std::string > GetMessagesOfLevel ( const obMessageLevel  level  ) 

Returns:
all messages matching a specified level

void StartLogging (  )  [inline]

Start logging messages (default).

void StopLogging (  )  [inline]

Stop logging messages completely.

void SetMaxLogEntries ( unsigned int  max  )  [inline]

Set the maximum number of entries (or 0 for no limit).

unsigned int GetMaxLogEntries (  )  [inline]

Returns:
the current maximum number of entries (default = 0 for no limit)

void ClearLog (  )  [inline]

Clear the current message log entirely.

Referenced by OBConversion::FullConvert().

void SetOutputLevel ( const obMessageLevel  level  )  [inline]

Set the level of messages to output (i.e., messages with at least this priority will be output).

obMessageLevel GetOutputLevel (  )  [inline]

Returns:
the current output level

void SetOutputStream ( std::ostream *  os  )  [inline]

std::ostream* GetOutputStream (  )  [inline]

bool StartErrorWrap (  ) 

Start "wrapping" messages to cerr into ThrowError calls.

bool StopErrorWrap (  ) 

Turn off "wrapping" messages, restoring normal cerr use (default).

Referenced by OBMessageHandler::~OBMessageHandler().

unsigned int GetErrorMessageCount (  )  [inline]

Returns:
Count of messages received at the obError level

unsigned int GetWarningMessageCount (  )  [inline]

Returns:
Count of messages received at the obWarning level

unsigned int GetInfoMessageCount (  )  [inline]

Returns:
Count of messages received at the obInfo level

unsigned int GetAuditMessageCount (  )  [inline]

Returns:
Count of messages received at the obAuditMsg level

unsigned int GetDebugMessageCount (  )  [inline]

Returns:
Count of messages received at the obDebug level

string GetMessageSummary (  ) 

Returns:
Summary of messages received at all levels

Member Data Documentation

unsigned int _messageCount[5] [protected]

Count of messages at each message level.

Referenced by OBMessageHandler::GetMessageSummary(), OBMessageHandler::OBMessageHandler(), and OBMessageHandler::ThrowError().

std::deque<OBError> _messageList [protected]

Log of messages for later retrieval via GetMessagesOfLevel().

Referenced by OBMessageHandler::GetMessagesOfLevel(), and OBMessageHandler::ThrowError().

obMessageLevel _outputLevel [protected]

Filtering level for messages and logging (messages of lower priority will be ignored.

Referenced by OBMessageHandler::ThrowError().

std::ostream* _outputStream [protected]

Referenced by OBMessageHandler::ThrowError().

bool _logging [protected]

Whether messages will be logged into _messageList.

Referenced by OBMessageHandler::ThrowError().

unsigned int _maxEntries [protected]

The maximum size of _messageList log.

Referenced by OBMessageHandler::ThrowError().

std::streambuf* _inWrapStreamBuf [protected]

The default stream buffer for the output stream (saved if wrapping is ued).

Referenced by OBMessageHandler::StartErrorWrap(), and OBMessageHandler::StopErrorWrap().

std::streambuf* _filterStreamBuf [protected]

The filtered obLogBuf stream buffer to wrap error messages.

Referenced by OBMessageHandler::StartErrorWrap(), and OBMessageHandler::~OBMessageHandler().

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