log4cpp:NDC (3)

NAME

       log4cpp::NDC - The NDC class implements nested diagnostic contexts as
       defined by Neil Harrison in the article 'Patterns for Logging
       Diagnostic Messages' part of the book 'Pattern Languages of Program
       Design 3' edited by Martin et al.

SYNOPSIS

       #include <NDC.hh>

   Public Types
       typedef std::vector< DiagnosticContext > ContextStack

   Public Methods
       NDC ()
       virtual ~NDC ()
       virtual void _clear ()
       virtual ContextStack * _cloneStack ()
       virtual const std::string & _get () const
       virtual int _getDepth () const
       virtual void _inherit (ContextStack *stack)
       virtual std::string _pop ()
       virtual void _push (const std::string &message)
       virtual void _setMaxDepth (int maxDepth)

   Static Public Methods
       void clear ()
           Clear any nested disgnostic information if any.
       ContextStack * cloneStack ()
           Clone the diagnostic context for the current thread.
       const std::string & get ()
           Get the current diagnostic context string.
       int getDepth ()
           Get the current nesting depth of this diagnostic context.
       void inherit (ContextStack *stack)
       std::string pop ()
           Clients should call this method before leaving a diagnostic
           context.
       void push (const std::string &message)
           Push new diagnostic context information for the current thread.
       void setMaxDepth (int maxDepth)
           Set the maximum nesting depth for the current NDC.
       NDC & getNDC ()
           Return the NDC for the current thread.

   Public Attributes
       ContextStack _stack

DETAILED DESCRIPTION

       The NDC class implements nested diagnostic contexts as defined by Neil
       Harrison in the article 'Patterns for Logging Diagnostic Messages' part
       of the book 'Pattern Languages of Program Design 3' edited by Martin et
       al.

       Note that NDCs are managed on a per thread basis. NDC operations such
       as push,  pop, clear, getDepth and  setMaxDepth affect the NDC of the
       current thread only. NDCs of other threads remain unaffected.

       To build an NDC one uses the push operation.  Simply put,

       Contexts can be nested.

       When entering a context, call NDC.push. As a side effect, if there is
       no nested diagnostic context for the current thread, this method will
       create it.

       When leaving a context, call NDC.pop.

       There is no penalty for forgetting to match each push operation with a
       corresponding pop, except the obvious mismatch between the real
       application context and the context set in the NDC.

       Custom Layouts may include the nested diagnostic context for the
       current thread in log messages, without any user intervention. Hence,
       even if a server is serving multiple clients simultaneously, the logs
       emanating from the same code (belonging to the same category) can still
       be distinguished because each client request will have a different NDC
       tag.

       Unfortunately, unlike Java, C++ does not have platform  independent
       multithreading support. Therefore, currently log4cpp is  not
       multithread aware, it implicitly assumes only one thread exists,  the
       main process thread.

MEMBER TYPEDEF DOCUMENTATION

   typedef std::vector<DiagnosticContext> log4cpp::NDC::ContextStack

CONSTRUCTOR & DESTRUCTOR DOCUMENTATION

   log4cpp::NDC::NDC ()
   log4cpp::NDC::~NDC () [virtual]

MEMBER FUNCTION DOCUMENTATION

   void log4cpp::NDC::_clear () [virtual]
   NDC::ContextStack * log4cpp::NDC::_cloneStack () [virtual]
   const std::string & log4cpp::NDC::_get () [virtual]
   int log4cpp::NDC::_getDepth () [virtual]
   void log4cpp::NDC::_inherit (ContextStack * stack) [virtual]
   std::string log4cpp::NDC::_pop () [virtual]
   void log4cpp::NDC::_push (const std::string & message) [virtual]
   void log4cpp::NDC::_setMaxDepth (int maxDepth) [virtual]
   void log4cpp::NDC::clear () [static]
       Clear any nested disgnostic information if any.

       This method is useful in cases where the same thread can be potentially
       used over and over in different unrelated contexts.

       This method is equivalent to calling the setMaxDepth method with a zero
       maxDepth argument.

       diagnostic context.

       Returns:
           Stack A clone of the current thread's diagnostic context.

   const std::string & log4cpp::NDC::get () [static]
       Get the current diagnostic context string.

       Returns:
           the context string.

   int log4cpp::NDC::getDepth () [static]
       Get the current nesting depth of this diagnostic context.

       Returns:
           the nesting depth

   NDC & log4cpp::NDC::getNDC () [static]
       Return the NDC for the current thread.

       Returns:
           the NDC for the current thread

   void log4cpp::NDC::inherit (ContextStack * stack) [static]
   std::string log4cpp::NDC::pop () [static]
       Clients should call this method before leaving a diagnostic context.

       The returned value is the value that was pushed last. If no context is
       available, then the empty string '' is returned.

       Returns:
           String The innermost diagnostic context.

   void log4cpp::NDC::push (const std::string & message) [static]
       Push new diagnostic context information for the current thread.

       The contents of the message parameter is determined solely by the
       client.

       Parameters:

       message
              The new diagnostic context information.

   void log4cpp::NDC::setMaxDepth (int maxDepth) [static]
       Set the maximum nesting depth for the current NDC.

       Curently NDCs  do not enforce a maximum depth and consequentially this
       method has no effect.

       Parameters:

       the    maximum nesting depth

MEMBER DATA DOCUMENTATION