# log4cpp::Category Class Reference

This is the central class in the log4j package. More...

`#include <Category.hh>`

Inheritance diagram for log4cpp::Category:

[legend]
Collaboration diagram for log4cpp::Category:

[legend]
List of all members.

## Public Member Functions

virtual | ~Category ()
| Destructor for Category.
virtual const std::string & | getName () const throw ()
| Return the category name.
virtual void | setPriority (Priority::Value priority) throw (std::invalid_argument)
| Set the priority of this Category.
virtual Priority::Value | getPriority () const throw ()
| Returns the assigned Priority, if any, for this Category.
virtual Priority::Value | getChainedPriority () const throw ()
| Starting from this Category, search the category hierarchy for a set priority and return it.
virtual bool | isPriorityEnabled (Priority::Value priority) const throw ()
| Returns true if the chained priority of the Category is equal to or higher than given priority.
virtual void | addAppender (Appender *appender) throw (std::invalid_argument)
| Adds an Appender to this Category.
virtual void | addAppender (Appender &appender)
| Adds an Appender for this Category.
void | setAppender (Appender *appender)
| Adds an Appender to this Category.
void | setAppender (Appender &appender)
| Adds an Appender for this Category.
virtual Appender * | getAppender () const
| Returns the first Appender for this Category, or NULL if no Appender has been set.
virtual Appender * | getAppender (const std::string &name) const
| Returns the specified Appender for this Category, or NULL if the Appender is not attached to this Category.
virtual AppenderSet | getAllAppenders () const
| Returns the set of Appenders currently attached to this Catogory.
virtual void | removeAllAppenders ()
| Removes all appenders for this Category.
virtual void | removeAppender (Appender *appender)
| Removes specified appender for this Category.
virtual bool | ownsAppender () const throw ()
| Returns true if the Category owns the first Appender in its Appender set.
virtual bool | ownsAppender (Appender *appender) const throw ()
| Returns true if the Category owns the Appender.
virtual void | callAppenders (const LoggingEvent &event) throw ()
| Call the appenders in the hierarchy starting at `this`.
virtual void | setAdditivity (bool additivity)
| Set the additivity flag for this Category instance.
virtual bool | getAdditivity () const throw ()
| Returns the additivity flag for this Category instance.
virtual Category * | getParent () throw ()
| Returns the parent category of this category, or NULL if the category is the root category.
virtual const Category * | getParent () const throw ()
| Returns the parent category of this category, or NULL if the category is the root category.
virtual void | log (Priority::Value priority, const char *stringFormat,...) throw ()
| Log a message with the specified priority.
virtual void | log (Priority::Value priority, const std::string &message) throw ()
| Log a message with the specified priority.
virtual void | logva (Priority::Value priority, const char *stringFormat, va_list va) throw ()
| Log a message with the specified priority.
void | debug (const char *stringFormat,...) throw ()
| Log a message with debug priority.
void | debug (const std::string &message) throw ()
| Log a message with debug priority.
bool | isDebugEnabled () const throw ()
| Return true if the Category will log messages with priority DEBUG.
CategoryStream | debugStream ()
| Return a CategoryStream with priority DEBUG.
void | info (const char *stringFormat,...) throw ()
| Log a message with info priority.
void | info (const std::string &message) throw ()
| Log a message with info priority.
bool | isInfoEnabled () const throw ()
| Return true if the Category will log messages with priority INFO.
CategoryStream | infoStream ()
| Return a CategoryStream with priority INFO.
void | notice (const char *stringFormat,...) throw ()
| Log a message with notice priority.
void | notice (const std::string &message) throw ()
| Log a message with notice priority.
bool | isNoticeEnabled () const throw ()
| Return true if the Category will log messages with priority NOTICE.
CategoryStream | noticeStream ()
| Return a CategoryStream with priority NOTICE.
void | warn (const char *stringFormat,...) throw ()
| Log a message with warn priority.
void | warn (const std::string &message) throw ()
| Log a message with warn priority.
bool | isWarnEnabled () const throw ()
| Return true if the Category will log messages with priority WARN.
CategoryStream | warnStream ()
| Return a CategoryStream with priority WARN.
void | error (const char *stringFormat,...) throw ()
| Log a message with error priority.
void | error (const std::string &message) throw ()
| Log a message with error priority.
bool | isErrorEnabled () const throw ()
| Return true if the Category will log messages with priority ERROR.
CategoryStream | errorStream ()
| Return a CategoryStream with priority ERROR.
void | crit (const char *stringFormat,...) throw ()
| Log a message with crit priority.
void | crit (const std::string &message) throw ()
| Log a message with crit priority.
bool | isCritEnabled () const throw ()
| Return true if the Category will log messages with priority CRIT.
CategoryStream | critStream ()
| Return a CategoryStream with priority CRIT.
void | alert (const char *stringFormat,...) throw ()
| Log a message with alert priority.
void | alert (const std::string &message) throw ()
| Log a message with alert priority.
bool | isAlertEnabled () const throw ()
| Return true if the Category will log messages with priority ALERT.
CategoryStream | alertStream () throw ()
| Return a CategoryStream with priority ALERT.
void | emerg (const char *stringFormat,...) throw ()
| Log a message with emerg priority.
void | emerg (const std::string &message) throw ()
| Log a message with emerg priority.
bool | isEmergEnabled () const throw ()
| Return true if the Category will log messages with priority EMERG.
CategoryStream | emergStream ()
| Return a CategoryStream with priority EMERG.
void | fatal (const char *stringFormat,...) throw ()
| Log a message with fatal priority.
void | fatal (const std::string &message) throw ()
| Log a message with fatal priority.
bool | isFatalEnabled () const throw ()
| Return true if the Category will log messages with priority FATAL.
CategoryStream | fatalStream ()
| Return a CategoryStream with priority FATAL.
virtual CategoryStream | getStream (Priority::Value priority)
| Return a CategoryStream with given Priority.
virtual CategoryStream | operator<< (Priority::Value priority)
| Return a CategoryStream with given Priority.

## Static Public Member Functions

static Category & | getRoot ()
| Return the root of the Category hierarchy.
static void | setRootPriority (Priority::Value priority)
| Set the priority of the root Category.
static Priority::Value | getRootPriority () throw ()
| Get the priority of the `root` Category.
static Category & | getInstance (const std::string &name)
| Instantiate a Category with name `name`.
static Category * | exists (const std::string &name)
| If the named category exists (in the default hierarchy) then it returns a reference to the category, otherwise it returns NULL.
static std::vector< Category * > * | getCurrentCategories ()
| Returns all the currently defined categories as a vector of Category pointers.
static void | shutdown ()
| This method will remove all Appenders from Categories.XXX.

## Protected Member Functions

| Category (const std::string &name, Category *parent, Priority::Value priority=Priority::NOTSET)
| Constructor.
virtual void | _logUnconditionally (Priority::Value priority, const char *format, va_list arguments) throw ()
virtual void | _logUnconditionally2 (Priority::Value priority, const std::string &message) throw ()
| Unconditionally log a message with the specified priority.

## Friends

class | HierarchyMaintainer

## Detailed Description

This is the central class in the log4j package.

One of the distintive features of log4j (and hence log4cpp) are hierarchal categories and their evaluation.

## Constructor & Destructor Documentation

log4cpp::Category::~Category | ( |  | ) | `[virtual]`

Destructor for Category.

log4cpp::Category::Category | ( | const std::string & | name,
|  | Category * | parent,
|  | Priority::Value | priority = `Priority::NOTSET` |
| ) |  |  | `[protected]`

Constructor.

Parameters:

  | name | the fully qualified name of this Category
  | parent | the parent of this parent, or NULL for the root Category
  | priority | the priority for this Category. Defaults to Priority::NOTSET

## Member Function Documentation

Category & log4cpp::Category::getRoot | ( |  | ) | `[static]`

Return the root of the Category hierarchy.

The root category is always instantiated and available. It's name is the empty string.

Unlike in log4j, calling `Category.getInstance("")` does retrieve the root category and not a category just under root named "".

Returns:
  The root category

void log4cpp::Category::setRootPriority | ( | Priority::Value | priority | ) | `[static]`

Set the priority of the root Category.

Parameters:

  | priority | The new priority for the root Category

Priority::Value log4cpp::Category::getRootPriority | ( |  | ) | throw ()`[static]`

Get the priority of the `root` Category.

Returns:
  the priority of the root category

Category & log4cpp::Category::getInstance | ( | const std::string & | name | ) | `[static]`

Instantiate a Category with name `name`.

This method does not set priority of the category which is by default `Priority::NOTSET`.

Parameters:

  | name | The name of the category to retrieve.

Category * log4cpp::Category::exists | ( | const std::string & | name | ) | `[static]`

If the named category exists (in the default hierarchy) then it returns a reference to the category, otherwise it returns NULL.

Since:
  0.2.7

std::vector< Category * > * log4cpp::Category::getCurrentCategories | ( |  | ) | `[static]`

Returns all the currently defined categories as a vector of Category pointers.

Note: this function does not pass ownership of the categories in the vector to the caller, only the ownership of the vector. However vector<Category&>* is not legal C++, so we can't follow the default ownership conventions.

Unlike in log4j, the root category is included in the returned set.

Since:
  0.3.2. Before 0.3.2 this method returned a std::set

void log4cpp::Category::shutdown | ( |  | ) | `[static]`

This method will remove all Appenders from Categories.XXX.

const std::string & log4cpp::Category::getName | ( |  | ) | const throw ()`[virtual]`

Return the category name.

Returns:
  The category name.

void log4cpp::Category::setPriority | ( | Priority::Value | priority | ) | throw (std::invalid_argument)`[virtual]`

Set the priority of this Category.

Parameters:

  | priority | The priority to set. Use Priority::NOTSET to let the category use its parents priority as effective priority.

Exceptions:

  | std::invalid_argument | if the caller tries to set Priority::NOTSET on the Root Category.

Priority::Value log4cpp::Category::getPriority | ( |  | ) | const throw ()`[virtual]`

Returns the assigned Priority, if any, for this Category.

Returns:
  Priority - the assigned Priority, can be Priority::NOTSET

Reimplemented in log4cpp::FixedContextCategory.

Priority::Value log4cpp::Category::getChainedPriority | ( |  | ) | const throw ()`[virtual]`

Starting from this Category, search the category hierarchy for a set priority and return it.

Otherwise, return the priority of the root category.

The Category class is designed so that this method executes as quickly as possible.

Reimplemented in log4cpp::FixedContextCategory.

bool log4cpp::Category::isPriorityEnabled | ( | Priority::Value | priority | ) | const throw ()`[virtual]`

Returns true if the chained priority of the Category is equal to or higher than given priority.

Parameters:

  | priority | The priority to compare with.

Returns:
  whether logging is enable for this priority.

void log4cpp::Category::addAppender | ( | Appender * | appender | ) | throw (std::invalid_argument)`[virtual]`

Adds an Appender to this Category.

This method passes ownership from the caller to the Category.

Since:
  0.2.7

Parameters:

  | appender | The Appender to wich this category has to log.

Exceptions:

  | std::invalid_argument | if the appender is NULL.

Reimplemented in log4cpp::FixedContextCategory.

void log4cpp::Category::addAppender | ( | Appender & | appender | ) | `[virtual]`

Adds an Appender for this Category.

This method does not pass ownership from the caller to the Category.

Since:
  0.2.7

Parameters:

  | appender | The Appender this category has to log to.

Reimplemented in log4cpp::FixedContextCategory.

void log4cpp::Category::setAppender | ( | Appender * | appender | ) | `[inline]`

Adds an Appender to this Category.

This method passes ownership from the caller to the Category.

Deprecated:
  use addAppender(Appender*) or removeAllAppenders() instead.

Parameters:

  | appender | The Appender this category has to log to or NULL to remove the current Appenders.

void log4cpp::Category::setAppender | ( | Appender & | appender | ) | `[inline]`

Adds an Appender for this Category.

This method does not pass ownership from the caller to the Category.

Deprecated:
  use addAppender(Appender&) instead.

Parameters:

  | appender | The Appender this category has to log to.

Appender * log4cpp::Category::getAppender | ( |  | ) | const`[virtual]`

Returns the first Appender for this Category, or NULL if no Appender has been set.

Deprecated:
  use getAppender(const std::string&)

Returns:
  The Appender.

Reimplemented in log4cpp::FixedContextCategory.

Appender * log4cpp::Category::getAppender | ( | const std::string & | name | ) | const`[virtual]`

Returns the specified Appender for this Category, or NULL if the Appender is not attached to this Category.

Since:
  0.2.7

Returns:
  The Appender.

Reimplemented in log4cpp::FixedContextCategory.

AppenderSet log4cpp::Category::getAllAppenders | ( |  | ) | const`[virtual]`

Returns the set of Appenders currently attached to this Catogory.

Since:
  0.3.1

Returns:
  The set of attached Appenders.

Reimplemented in log4cpp::FixedContextCategory.

void log4cpp::Category::removeAllAppenders | ( |  | ) | `[virtual]`

Removes all appenders for this Category.

Reimplemented in log4cpp::FixedContextCategory.

void log4cpp::Category::removeAppender | ( | Appender * | appender | ) | `[virtual]`

Removes specified appender for this Category.

Since:
  0.2.7

virtual bool log4cpp::Category::ownsAppender | ( |  | ) | const throw ()`[inline, virtual]`

Returns true if the Category owns the first Appender in its Appender set.

In that case the Category destructor will delete the Appender.

Deprecated:
  use ownsAppender(Appender*)

Reimplemented in log4cpp::FixedContextCategory.

bool log4cpp::Category::ownsAppender | ( | Appender * | appender | ) | const throw ()`[virtual]`

Returns true if the Category owns the Appender.

In that case the Category destructor will delete the Appender.

Since:
  0.2.7

Reimplemented in log4cpp::FixedContextCategory.

void log4cpp::Category::callAppenders | ( | const LoggingEvent & | event | ) | throw ()`[virtual]`

Call the appenders in the hierarchy starting at `this`.

If no appenders could be found, emit a warning.

This method always calls all the appenders inherited form the hierracy circumventing any evaluation of whether to log or not to log the particular log request.

Parameters:

  | event | the LogginEvent to log.

Reimplemented in log4cpp::FixedContextCategory.

void log4cpp::Category::setAdditivity | ( | bool | additivity | ) | `[virtual]`

Set the additivity flag for this Category instance.

Reimplemented in log4cpp::FixedContextCategory.

bool log4cpp::Category::getAdditivity | ( |  | ) | const throw ()`[virtual]`

Returns the additivity flag for this Category instance.

Reimplemented in log4cpp::FixedContextCategory.

Category * log4cpp::Category::getParent | ( |  | ) | throw ()`[virtual]`

Returns the parent category of this category, or NULL if the category is the root category.

Returns:
  the parent category.

const Category * log4cpp::Category::getParent | ( |  | ) | const throw ()`[virtual]`

Returns the parent category of this category, or NULL if the category is the root category.

Returns:
  the parent category.

void log4cpp::Category::log | ( | Priority::Value | priority,
|  | const char * | stringFormat,
|  |  | ... |
| ) |  |  | throw ()`[virtual]`

Log a message with the specified priority.

Parameters:

  | priority | The priority of this log message.
  | stringFormat | Format specifier for the string to write in the log file.
  | ... | The arguments for stringFormat

void log4cpp::Category::log | ( | Priority::Value | priority,
|  | const std::string & | message |
| ) |  |  | throw ()`[virtual]`

Log a message with the specified priority.

Parameters:

  | priority | The priority of this log message.
  | message | string to write in the log file

void log4cpp::Category::logva | ( | Priority::Value | priority,
|  | const char * | stringFormat,
|  | va_list | va |
| ) |  |  | throw ()`[virtual]`

Log a message with the specified priority.

Since:
  0.2.7

Parameters:

  | priority | The priority of this log message.
  | stringFormat | Format specifier for the string to write in the log file.
  | va | The arguments for stringFormat.

void log4cpp::Category::debug | ( | const char * | stringFormat,
|  |  | ... |
| ) |  |  | throw ()

Log a message with debug priority.

Parameters:

  | stringFormat | Format specifier for the string to write in the log file.
  | ... | The arguments for stringFormat

void log4cpp::Category::debug | ( | const std::string & | message | ) | throw ()

Log a message with debug priority.

Parameters:

  | message | string to write in the log file

bool log4cpp::Category::isDebugEnabled | ( |  | ) | const throw ()`[inline]`

Return true if the Category will log messages with priority DEBUG.

Returns:
  Whether the Category will log.

CategoryStream log4cpp::Category::debugStream | ( |  | ) | `[inline]`

Return a CategoryStream with priority DEBUG.

Returns:
  The CategoryStream.

void log4cpp::Category::info | ( | const char * | stringFormat,
|  |  | ... |
| ) |  |  | throw ()

Log a message with info priority.

Parameters:

  | stringFormat | Format specifier for the string to write in the log file.
  | ... | The arguments for stringFormat

void log4cpp::Category::info | ( | const std::string & | message | ) | throw ()

Log a message with info priority.

Parameters:

  | message | string to write in the log file

bool log4cpp::Category::isInfoEnabled | ( |  | ) | const throw ()`[inline]`

Return true if the Category will log messages with priority INFO.

Returns:
  Whether the Category will log.

CategoryStream log4cpp::Category::infoStream | ( |  | ) | `[inline]`

Return a CategoryStream with priority INFO.

Returns:
  The CategoryStream.

void log4cpp::Category::notice | ( | const char * | stringFormat,
|  |  | ... |
| ) |  |  | throw ()

Log a message with notice priority.

Parameters:

  | stringFormat | Format specifier for the string to write in the log file.
  | ... | The arguments for stringFormat

void log4cpp::Category::notice | ( | const std::string & | message | ) | throw ()

Log a message with notice priority.

Parameters:

  | message | string to write in the log file

bool log4cpp::Category::isNoticeEnabled | ( |  | ) | const throw ()`[inline]`

Return true if the Category will log messages with priority NOTICE.

Returns:
  Whether the Category will log.

CategoryStream log4cpp::Category::noticeStream | ( |  | ) | `[inline]`

Return a CategoryStream with priority NOTICE.

Returns:
  The CategoryStream.

void log4cpp::Category::warn | ( | const char * | stringFormat,
|  |  | ... |
| ) |  |  | throw ()

Log a message with warn priority.

Parameters:

  | stringFormat | Format specifier for the string to write in the log file.
  | ... | The arguments for stringFormat

void log4cpp::Category::warn | ( | const std::string & | message | ) | throw ()

Log a message with warn priority.

Parameters:

  | message | string to write in the log file

bool log4cpp::Category::isWarnEnabled | ( |  | ) | const throw ()`[inline]`

Return true if the Category will log messages with priority WARN.

Returns:
  Whether the Category will log.

CategoryStream log4cpp::Category::warnStream | ( |  | ) | `[inline]`

Return a CategoryStream with priority WARN.

Returns:
  The CategoryStream.

void log4cpp::Category::error | ( | const char * | stringFormat,
|  |  | ... |
| ) |  |  | throw ()

Log a message with error priority.

Parameters:

  | stringFormat | Format specifier for the string to write in the log file.
  | ... | The arguments for stringFormat

void log4cpp::Category::error | ( | const std::string & | message | ) | throw ()

Log a message with error priority.

Parameters:

  | message | string to write in the log file

bool log4cpp::Category::isErrorEnabled | ( |  | ) | const throw ()`[inline]`

Return true if the Category will log messages with priority ERROR.

Returns:
  Whether the Category will log.

CategoryStream log4cpp::Category::errorStream | ( |  | ) | `[inline]`

Return a CategoryStream with priority ERROR.

Returns:
  The CategoryStream.

void log4cpp::Category::crit | ( | const char * | stringFormat,
|  |  | ... |
| ) |  |  | throw ()

Log a message with crit priority.

Parameters:

  | stringFormat | Format specifier for the string to write in the log file.
  | ... | The arguments for stringFormat

void log4cpp::Category::crit | ( | const std::string & | message | ) | throw ()

Log a message with crit priority.

Parameters:

  | message | string to write in the log file

bool log4cpp::Category::isCritEnabled | ( |  | ) | const throw ()`[inline]`

Return true if the Category will log messages with priority CRIT.

Returns:
  Whether the Category will log.

CategoryStream log4cpp::Category::critStream | ( |  | ) | `[inline]`

Return a CategoryStream with priority CRIT.

Returns:
  The CategoryStream.

void log4cpp::Category::alert | ( | const char * | stringFormat,
|  |  | ... |
| ) |  |  | throw ()

Log a message with alert priority.

Parameters:

  | stringFormat | Format specifier for the string to write in the log file.
  | ... | The arguments for stringFormat

void log4cpp::Category::alert | ( | const std::string & | message | ) | throw ()

Log a message with alert priority.

Parameters:

  | message | string to write in the log file

bool log4cpp::Category::isAlertEnabled | ( |  | ) | const throw ()`[inline]`

Return true if the Category will log messages with priority ALERT.

Returns:
  Whether the Category will log.

CategoryStream log4cpp::Category::alertStream | ( |  | ) | throw ()`[inline]`

Return a CategoryStream with priority ALERT.

Returns:
  The CategoryStream.

void log4cpp::Category::emerg | ( | const char * | stringFormat,
|  |  | ... |
| ) |  |  | throw ()

Log a message with emerg priority.

Parameters:

  | stringFormat | Format specifier for the string to write in the log file.
  | ... | The arguments for stringFormat

void log4cpp::Category::emerg | ( | const std::string & | message | ) | throw ()

Log a message with emerg priority.

Parameters:

  | message | string to write in the log file

bool log4cpp::Category::isEmergEnabled | ( |  | ) | const throw ()`[inline]`

Return true if the Category will log messages with priority EMERG.

Returns:
  Whether the Category will log.

CategoryStream log4cpp::Category::emergStream | ( |  | ) | `[inline]`

Return a CategoryStream with priority EMERG.

Returns:
  The CategoryStream.

void log4cpp::Category::fatal | ( | const char * | stringFormat,
|  |  | ... |
| ) |  |  | throw ()

Log a message with fatal priority.

NB. priority 'fatal' is equivalent to 'emerg'.

Since:
  0.2.7

Parameters:

  | stringFormat | Format specifier for the string to write in the log file.
  | ... | The arguments for stringFormat

void log4cpp::Category::fatal | ( | const std::string & | message | ) | throw ()

Log a message with fatal priority.

NB. priority 'fatal' is equivalent to 'emerg'.

Since:
  0.2.7

Parameters:

  | message | string to write in the log file

bool log4cpp::Category::isFatalEnabled | ( |  | ) | const throw ()`[inline]`

Return true if the Category will log messages with priority FATAL.

NB. priority 'fatal' is equivalent to 'emerg'.

Since:
  0.2.7

Returns:
  Whether the Category will log.

CategoryStream log4cpp::Category::fatalStream | ( |  | ) | `[inline]`

Return a CategoryStream with priority FATAL.

NB. priority 'fatal' is equivalent to 'emerg'.

Since:
  0.2.7

Returns:
  The CategoryStream.

CategoryStream log4cpp::Category::getStream | ( | Priority::Value | priority | ) | `[virtual]`

Return a CategoryStream with given Priority.

Parameters:

  | priority | The Priority of the CategoryStream.

Returns:
  The requested CategoryStream.

CategoryStream log4cpp::Category::operator<< | ( | Priority::Value | priority | ) | `[virtual]`

Return a CategoryStream with given Priority.

Parameters:

  | priority | The Priority of the CategoryStream.

Returns:
  The requested CategoryStream.

void log4cpp::Category::_logUnconditionally | ( | Priority::Value | priority,
|  | const char * | format,
|  | va_list | arguments |
| ) |  |  | throw ()`[protected, virtual]`

void log4cpp::Category::_logUnconditionally2 | ( | Priority::Value | priority,
|  | const std::string & | message |
| ) |  |  | throw ()`[protected, virtual]`

Unconditionally log a message with the specified priority.

Parameters:

  | priority | The priority of this log message.
  | message | string to write in the log file

Reimplemented in log4cpp::FixedContextCategory.

## Friends And Related Function Documentation

friend class HierarchyMaintainer`[friend]`

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

- Category.hh
- Category.cpp