You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by sw...@apache.org on 2022/12/11 23:56:18 UTC
[logging-log4cxx] branch next_stable updated: Improve documentation of Logger methods (#158)
This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a commit to branch next_stable
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
The following commit(s) were added to refs/heads/next_stable by this push:
new eb5105ca Improve documentation of Logger methods (#158)
eb5105ca is described below
commit eb5105cab2edf5800e2609c0470e2ddfb13618b6
Author: Stephen Webb <st...@ieee.org>
AuthorDate: Mon Dec 12 10:56:12 2022 +1100
Improve documentation of Logger methods (#158)
* Improve documentation of Logger methods and add macro links onto the Logger page
* Add macro usage examples
---
src/main/include/log4cxx/logger.h | 675 +++++++++++++++++++++++++++-----------
1 file changed, 480 insertions(+), 195 deletions(-)
diff --git a/src/main/include/log4cxx/logger.h b/src/main/include/log4cxx/logger.h
index 27eb93d1..fb42bc64 100644
--- a/src/main/include/log4cxx/logger.h
+++ b/src/main/include/log4cxx/logger.h
@@ -106,7 +106,7 @@ class LOG4CXX_EXPORT Logger :
void closeNestedAppenders();
/**
- Log a message string with the DEBUG level.
+ Add a new logging event containing \c msg and \c location to attached appender(s) if this logger is enabled for <code>DEBUG</code> events.
<p>This method first checks if this logger is <code>DEBUG</code>
enabled by comparing the level of this logger with the
@@ -120,7 +120,7 @@ class LOG4CXX_EXPORT Logger :
*/
void debug(const std::string& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the DEBUG level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>DEBUG</code> events.
<p>This method first checks if this logger is <code>DEBUG</code>
enabled by comparing the level of this logger with the
@@ -130,11 +130,13 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_DEBUG.
*/
void debug(const std::string& msg) const;
#if LOG4CXX_WCHAR_T_API
/**
- Log a message string with the DEBUG level.
+ Add a new logging event containing \c msg and \c location to attached appender(s) if this logger is enabled for <code>DEBUG</code> events.
<p>This method first checks if this logger is <code>DEBUG</code>
enabled by comparing the level of this logger with the
@@ -145,10 +147,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_DEBUG.
*/
void debug(const std::wstring& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the DEBUG level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>DEBUG</code> events.
<p>This method first checks if this logger is <code>DEBUG</code>
enabled by comparing the level of this logger with the
@@ -158,12 +162,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_DEBUG.
*/
void debug(const std::wstring& msg) const;
#endif
#if LOG4CXX_UNICHAR_API
/**
- Log a message string with the DEBUG level.
+ Add a new logging event containing \c msg and \c location to attached appender(s) if this logger is enabled for <code>DEBUG</code> events.
<p>This method first checks if this logger is <code>DEBUG</code>
enabled by comparing the level of this logger with the
@@ -174,10 +180,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_DEBUG.
*/
void debug(const std::basic_string<UniChar>& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the DEBUG level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>DEBUG</code> events.
<p>This method first checks if this logger is <code>DEBUG</code>
enabled by comparing the level of this logger with the
@@ -187,12 +195,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_DEBUG.
*/
void debug(const std::basic_string<UniChar>& msg) const;
#endif
#if LOG4CXX_CFSTRING_API
/**
- Log a message string with the DEBUG level.
+ Add a new logging event containing \c msg and \c location to attached appender(s) if this logger is enabled for <code>DEBUG</code> events.
<p>This method first checks if this logger is <code>DEBUG</code>
enabled by comparing the level of this logger with the
@@ -203,10 +213,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_DEBUG.
*/
void debug(const CFStringRef& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the DEBUG level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>DEBUG</code> events.
<p>This method first checks if this logger is <code>DEBUG</code>
enabled by comparing the level of this logger with the
@@ -216,12 +228,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_DEBUG.
*/
void debug(const CFStringRef& msg) const;
#endif
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg and \c location to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -232,10 +246,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_ERROR.
*/
void error(const std::string& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -245,11 +261,13 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_ERROR.
*/
void error(const std::string& msg) const;
#if LOG4CXX_WCHAR_T_API
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -259,10 +277,12 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_ERROR.
*/
void error(const std::wstring& msg) const;
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg and \c location to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -273,12 +293,14 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_ERROR.
*/
void error(const std::wstring& msg, const log4cxx::spi::LocationInfo& location) const;
#endif
#if LOG4CXX_UNICHAR_API
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg and \c location to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -289,10 +311,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_ERROR.
*/
void error(const std::basic_string<UniChar>& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -302,12 +326,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_ERROR.
*/
void error(const std::basic_string<UniChar>& msg) const;
#endif
#if LOG4CXX_CFSTRING_API
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg and \c location to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -318,10 +344,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_ERROR.
*/
void error(const CFStringRef& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -331,12 +359,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_ERROR.
*/
void error(const CFStringRef& msg) const;
#endif
/**
- Log a message string with the FATAL level.
+ Add a new logging event containing \c msg and \c location to attached appender(s) if this logger is enabled for <code>FATAL</code> events.
<p>This method first checks if this logger is <code>FATAL</code>
enabled by comparing the level of this logger with the
@@ -347,10 +377,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_FATAL.
*/
void fatal(const std::string& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -360,11 +392,13 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_FATAL.
*/
void fatal(const std::string& msg) const;
#if LOG4CXX_WCHAR_T_API
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg and \c location to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -375,10 +409,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_FATAL.
*/
void fatal(const std::wstring& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -388,12 +424,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_FATAL.
*/
void fatal(const std::wstring& msg) const;
#endif
#if LOG4CXX_UNICHAR_API
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg and \c location to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -404,10 +442,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_FATAL.
*/
void fatal(const std::basic_string<UniChar>& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -417,12 +457,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_FATAL.
*/
void fatal(const std::basic_string<UniChar>& msg) const;
#endif
#if LOG4CXX_CFSTRING_API
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg and \c location to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -433,10 +475,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_FATAL.
*/
void fatal(const CFStringRef& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the ERROR level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>ERROR</code> events.
<p>This method first checks if this logger is <code>ERROR</code>
enabled by comparing the level of this logger with the
@@ -446,12 +490,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_FATAL.
*/
void fatal(const CFStringRef& msg) const;
#endif
/**
- This method creates a new logging event and logs the event
+ Add a new logging event containing \c message and \c location to attached appender(s).
without further checks.
@param level the level to log.
@param message message.
@@ -460,7 +506,7 @@ class LOG4CXX_EXPORT Logger :
void forcedLog(const LevelPtr& level, const std::string& message,
const log4cxx::spi::LocationInfo& location) const;
/**
- This method creates a new logging event and logs the event
+ Add a new logging event containing \c message to attached appender(s).
without further checks.
@param level the level to log.
@param message message.
@@ -469,7 +515,7 @@ class LOG4CXX_EXPORT Logger :
#if LOG4CXX_WCHAR_T_API
/**
- This method creates a new logging event and logs the event
+ Add a new logging event containing \c message and \c location to attached appender(s).
without further checks.
@param level the level to log.
@param message message.
@@ -478,7 +524,7 @@ class LOG4CXX_EXPORT Logger :
void forcedLog(const LevelPtr& level, const std::wstring& message,
const log4cxx::spi::LocationInfo& location) const;
/**
- This method creates a new logging event and logs the event
+ Add a new logging event containing \c message to attached appender(s).
without further checks.
@param level the level to log.
@param message message.
@@ -487,7 +533,7 @@ class LOG4CXX_EXPORT Logger :
#endif
#if LOG4CXX_UNICHAR_API || LOG4CXX_CFSTRING_API
/**
- This method creates a new logging event and logs the event
+ Add a new logging event containing \c message and \c location to attached appender(s).
without further checks.
@param level the level to log.
@param message message.
@@ -496,7 +542,7 @@ class LOG4CXX_EXPORT Logger :
void forcedLog(const LevelPtr& level, const std::basic_string<UniChar>& message,
const log4cxx::spi::LocationInfo& location) const;
/**
- This method creates a new logging event and logs the event
+ Add a new logging event containing \c message to attached appender(s).
without further checks.
@param level the level to log.
@param message message.
@@ -505,7 +551,7 @@ class LOG4CXX_EXPORT Logger :
#endif
#if LOG4CXX_CFSTRING_API
/**
- This method creates a new logging event and logs the event
+ Add a new logging event containing \c message and \c location to attached appender(s).
without further checks.
@param level the level to log.
@param message message.
@@ -514,7 +560,7 @@ class LOG4CXX_EXPORT Logger :
void forcedLog(const LevelPtr& level, const CFStringRef& message,
const log4cxx::spi::LocationInfo& location) const;
/**
- This method creates a new logging event and logs the event
+ Add a new logging event containing \c message to attached appender(s).
without further checks.
@param level the level to log.
@param message message.
@@ -522,7 +568,7 @@ class LOG4CXX_EXPORT Logger :
void forcedLog(const LevelPtr& level, const CFStringRef& message) const;
#endif
/**
- This method creates a new logging event and logs the event
+ Add a new logging event containing \c message and \c location to attached appender(s).
without further checks.
@param level the level to log.
@param message the message string to log.
@@ -532,7 +578,7 @@ class LOG4CXX_EXPORT Logger :
const log4cxx::spi::LocationInfo& location) const;
/**
- Get the additivity flag for this Logger instance.
+ Get the additivity flag for this logger.
*/
bool getAdditivity() const;
@@ -574,34 +620,34 @@ class LOG4CXX_EXPORT Logger :
const LogString& getName() const;
/**
- * Get logger name in current encoding.
+ * Put name of this logger into \c name in current encoding.
* @param name buffer to which name is appended.
*/
void getName(std::string& name) const;
#if LOG4CXX_WCHAR_T_API
/**
- * Get logger name.
+ * Put name of this logger into \c name.
* @param name buffer to which name is appended.
*/
void getName(std::wstring& name) const;
#endif
#if LOG4CXX_UNICHAR_API
/**
- * Get logger name.
+ * Put name of this logger into \c name.
* @param name buffer to which name is appended.
*/
void getName(std::basic_string<UniChar>& name) const;
#endif
#if LOG4CXX_CFSTRING_API
/**
- * Get logger name.
+ * Put name of this logger into \c name.
* @param name buffer to which name is appended.
*/
void getName(CFStringRef& name) const;
#endif
/**
- Returns the parent of this logger. Note that the parent of a
+ The parent of this logger. Note that the parent of a
given logger may change during the lifetime of the logger.
<p>The root logger will return <code>0</code>.
@@ -610,7 +656,7 @@ class LOG4CXX_EXPORT Logger :
/**
- Returns the assigned Level, if any, for this Logger.
+ The assigned Level, if any, for this logger.
@return Level - the assigned Level, can be null.
*/
@@ -758,7 +804,7 @@ class LOG4CXX_EXPORT Logger :
protected:
/**
- Returns the string resource coresponding to <code>key</code> in this
+ Returns the string resource corresponding to <code>key</code> in this
logger's inherited resource bundle.
If the resource cannot be found, then an {@link #error error} message
@@ -770,7 +816,7 @@ class LOG4CXX_EXPORT Logger :
public:
/**
- Log a message string with the INFO level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>INFO</code> events.
<p>This method first checks if this logger is <code>INFO</code>
enabled by comparing the level of this logger with the
@@ -781,12 +827,28 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
- */
+
+ See also #LOG4CXX_INFO.
+ */
void info(const std::string& msg, const log4cxx::spi::LocationInfo& location) const;
+ /**
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>INFO</code> events.
+
+ <p>This method first checks if this logger is <code>INFO</code>
+ enabled by comparing the level of this logger with the
+ INFO level. If this logger is
+ <code>INFO</code> enabled, it proceeds to call all the
+ registered appenders in this logger and also higher in the
+ hierarchy depending on the value of the additivity flag.
+
+ @param msg the message string to log.
+
+ See also #LOG4CXX_INFO.
+ */
void info(const std::string& msg) const;
#if LOG4CXX_WCHAR_T_API
/**
- Log a message string with the INFO level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>INFO</code> events.
<p>This method first checks if this logger is <code>INFO</code>
enabled by comparing the level of this logger with the
@@ -797,10 +859,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
- */
+
+ See also #LOG4CXX_INFO.
+ */
void info(const std::wstring& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the INFO level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>INFO</code> events.
<p>This method first checks if this logger is <code>INFO</code>
enabled by comparing the level of this logger with the
@@ -810,12 +874,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
- */
+
+ See also #LOG4CXX_INFO.
+ */
void info(const std::wstring& msg) const;
#endif
#if LOG4CXX_UNICHAR_API
/**
- Log a message string with the INFO level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>INFO</code> events.
<p>This method first checks if this logger is <code>INFO</code>
enabled by comparing the level of this logger with the
@@ -829,7 +895,7 @@ class LOG4CXX_EXPORT Logger :
*/
void info(const std::basic_string<UniChar>& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the INFO level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>INFO</code> events.
<p>This method first checks if this logger is <code>INFO</code>
enabled by comparing the level of this logger with the
@@ -839,12 +905,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
- */
+
+ See also #LOG4CXX_INFO.
+ */
void info(const std::basic_string<UniChar>& msg) const;
#endif
#if LOG4CXX_CFSTRING_API
/**
- Log a message string with the INFO level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>INFO</code> events.
<p>This method first checks if this logger is <code>INFO</code>
enabled by comparing the level of this logger with the
@@ -855,10 +923,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
- */
+
+ See also #LOG4CXX_INFO.
+ */
void info(const CFStringRef& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the INFO level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>INFO</code> events.
<p>This method first checks if this logger is <code>INFO</code>
enabled by comparing the level of this logger with the
@@ -868,138 +938,222 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
- */
+
+ See also #LOG4CXX_INFO.
+ */
void info(const CFStringRef& msg) const;
#endif
/**
- Is the appender passed as parameter attached to this logger?
+ Is \c appender attached to this logger?
*/
bool isAttached(const AppenderPtr appender) const override;
/**
- * Check whether this logger is enabled for the <code>DEBUG</code>
- * Level.
- *
- * <p> This function is intended to lessen the computational cost of
- * disabled log debug statements.
- *
- * <p> For some <code>logger</code> Logger object, when you write,
- * <pre>
- * logger->debug("debug message");
- * </pre>
+ * Is this logger is enabled for <code>DEBUG</code> level logging events?
*
- * <p>You incur the cost constructing the message, concatenation in
- * this case, regardless of whether the message is logged or not.
- *
- * <p>If you are worried about speed, then you should write
+ * <p>By writing
* <pre>
* if(logger->isDebugEnabled()) {
- * logger->debug("debug message");
+ * logger->debug("Component: " + std::to_string(componentNumber));
* }
+ * </pre>you will not incur the cost of parameter construction
+ * (integer to string conversion plus string concatonation in this case)
+ * if debugging is disabled for <code>logger</code>.
+ * You avoid the cost constructing the message
+ * when the message is not logged.
+ *
+ * <p>This function allows you to reduce the computational cost of
+ * disabled log debug statements compared to writing:
+ * <pre>
+ * logger->debug("Component: " + std::to_string(componentNumber));
* </pre>
*
- * <p>This way you will not incur the cost of parameter
- * construction if debugging is disabled for <code>logger</code>. On
- * the other hand, if the <code>logger</code> is debug enabled, you
- * will incur the cost of evaluating whether the logger is debug
- * enabled twice. Once in <code>isDebugEnabled</code> and once in
- * the <code>debug</code>. This is an insignificant overhead
- * since evaluating a logger takes about 1%% of the time it
- * takes to actually log.
+ * <p>On the other hand, if the <code>logger</code> is enabled for <code>DEBUG</code> logging events,
+ * you will incur the cost of evaluating whether the logger is
+ * enabled twice, once in <code>isDebugEnabled</code> and once in
+ * the <code>DEBUG</code>. This really is an insignificant overhead
+ * since evaluating a the enabled status takes about 1% of the time it
+ * takes to send the message to the appender.
+
+ * See also #isDebugEnabledFor.
+ * See also #LOG4CXX_DEBUG.
*
* @return bool - <code>true</code> if this logger is debug
* enabled, <code>false</code> otherwise.
- * */
+ **/
bool isDebugEnabled() const;
+
+ /**
+ * Is \c logger is enabled for <code>DEBUG</code> level logging events?
+ *
+ * <p>By writing
+ * <pre>
+ * if(log4cxx::Logger::isDebugEnabledFor(logger)) {
+ * logger->forcedLog(log4cxx::Level::getDebug(), "Component: " + std::to_string(componentNumber));
+ * }
+ * </pre>you minimise the computational cost
+ * when \c logger is not enabled for <code>DEBUG</code> logging events.
+ * This function may be inlined thereby avoiding a function call
+ * as well as the cost constructing the message
+ * when \c logger is not enabled for <code>DEBUG</code> events.
+ *
+ * See also #LOG4CXX_DEBUG.
+ *
+ * @return bool - <code>false</code> if \c logger is <code>null</code>
+ * or <code>DEBUG</code> logging events are disabled for \c logger,
+ * <code>true</code> otherwise.
+ **/
inline static bool isDebugEnabledFor(const LoggerPtr& logger)
{
return logger && logger->m_threshold <= Level::DEBUG_INT && logger->isDebugEnabled();
}
/**
- Check whether this logger is enabled for a given
- Level passed as parameter.
+ Is this logger is enabled for logging events at \c level?
- See also #isDebugEnabled.
-
- @return bool True if this logger is enabled for <code>level</code>.
+ @return bool True if this logger is enabled for <code>level</code> logging events.
*/
bool isEnabledFor(const LevelPtr& level) const;
/**
- Check whether this logger is enabled for the info Level.
- See also #isDebugEnabled.
+ Is this logger is enabled for <code>INFO</code> level logging events?
+
+ See #isDebugEnabled.
+ See also #LOG4CXX_INFO.
@return bool - <code>true</code> if this logger is enabled
for level info, <code>false</code> otherwise.
*/
bool isInfoEnabled() const;
+
+ /**
+ Is \c logger is enabled for <code>INFO</code> level logging events?
+
+ See #isDebugEnabledFor.
+ See also #LOG4CXX_INFO.
+
+ @return bool - <code>false</code> if \c logger is <code>null</code>
+ or <code>INFO</code> logging events are disabled for \c logger,
+ <code>true</code> otherwise.
+ */
inline static bool isInfoEnabledFor(const LoggerPtr& logger)
{
return logger && logger->m_threshold <= Level::INFO_INT && logger->isInfoEnabled();
}
/**
- Check whether this logger is enabled for the warn Level.
+ Is this logger is enabled for <code>WARN</code> level logging events?
+
See also #isDebugEnabled.
+ See also #LOG4CXX_WARN.
@return bool - <code>true</code> if this logger is enabled
for level warn, <code>false</code> otherwise.
*/
bool isWarnEnabled() const;
+
+ /**
+ Is \c logger is enabled for <code>WARN</code> level logging events?
+
+ See #isDebugEnabledFor.
+ See also #LOG4CXX_WARN.
+
+ @return bool - <code>false</code> if \c logger is <code>null</code>
+ or <code>WARN</code> logging events are disabled for \c logger,
+ <code>true</code> otherwise.
+ */
inline static bool isWarnEnabledFor(const LoggerPtr& logger)
{
return logger && logger->m_threshold <= Level::WARN_INT && logger->isWarnEnabled();
}
/**
- Check whether this logger is enabled for the error Level.
+ Is this logger is enabled for <code>ERROR</code> level logging events?
+
See also #isDebugEnabled.
+ See also #LOG4CXX_ERROR.
@return bool - <code>true</code> if this logger is enabled
for level error, <code>false</code> otherwise.
*/
bool isErrorEnabled() const;
+
+ /**
+ Is \c logger is enabled for <code>ERROR</code> level logging events?
+
+ See #isDebugEnabledFor.
+ See also #LOG4CXX_ERROR.
+
+ @return bool - <code>false</code> if \c logger is <code>null</code>
+ or <code>ERROR</code> logging events are disabled for \c logger,
+ <code>true</code> otherwise.
+ */
inline static bool isErrorEnabledFor(const LoggerPtr& logger)
{
return logger && logger->m_threshold <= Level::ERROR_INT && logger->isErrorEnabled();
}
/**
- Check whether this logger is enabled for the fatal Level.
+ Is this logger is enabled for <code>FATAL</code> level logging events?
+
See also #isDebugEnabled.
+ See also #LOG4CXX_FATAL.
@return bool - <code>true</code> if this logger is enabled
for level fatal, <code>false</code> otherwise.
*/
bool isFatalEnabled() const;
+
+ /**
+ Is \c logger is enabled for <code>FATAL</code> level logging events?
+
+ See #isDebugEnabledFor.
+ See also #LOG4CXX_FATAL.
+
+ @return bool - <code>false</code> if \c logger is <code>null</code>
+ or <code>FATAL</code> logging events are disabled for \c logger,
+ <code>true</code> otherwise.
+ */
inline static bool isFatalEnabledFor(const LoggerPtr& logger)
{
return logger && logger->m_threshold <= Level::FATAL_INT && logger->isFatalEnabled();
}
/**
- Check whether this logger is enabled for the trace level.
+ Is this logger is enabled for <code>TRACE</code> level logging events?
+
See also #isDebugEnabled.
+ See also #LOG4CXX_FATAL.
@return bool - <code>true</code> if this logger is enabled
for level trace, <code>false</code> otherwise.
*/
bool isTraceEnabled() const;
+
+ /**
+ Is \c logger is enabled for <code>TRACE</code> level logging events?
+
+ See #isDebugEnabledFor.
+ See also #LOG4CXX_TRACE.
+
+ @return bool - <code>false</code> if \c logger is <code>null</code>
+ or <code>TRACE</code> logging events are disabled for \c logger,
+ <code>true</code> otherwise.
+ */
inline static bool isTraceEnabledFor(const LoggerPtr& logger)
{
return logger && logger->m_threshold <= Level::TRACE_INT && logger->isTraceEnabled();
}
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key using \c values for parameter substitution
+ to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@@ -1008,51 +1162,56 @@ class LOG4CXX_EXPORT Logger :
<code>{1}</code> etc. within the pattern.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG1.
*/
void l7dlog(const LevelPtr& level, const LogString& key,
const log4cxx::spi::LocationInfo& locationInfo,
const std::vector<LogString>& values) const;
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@param locationInfo The location info of the logging request.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG.
*/
void l7dlog(const LevelPtr& level, const std::string& key,
const log4cxx::spi::LocationInfo& locationInfo) const;
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key using parameter \c val to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method with the
+ supplied parameters in a string array.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@param locationInfo The location info of the logging request.
- @param val1 The first value for the placeholders within the pattern.
+ @param val The first value for the placeholders within the pattern.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG1.
*/
void l7dlog(const LevelPtr& level, const std::string& key,
const log4cxx::spi::LocationInfo& locationInfo,
- const std::string& val1) const;
+ const std::string& val) const;
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key using parameters \c val1 and \c val2 to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method with the
+ supplied parameters in a string array.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@@ -1061,17 +1220,19 @@ class LOG4CXX_EXPORT Logger :
@param val2 The second value for the placeholders within the pattern.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG2.
*/
void l7dlog(const LevelPtr& level, const std::string& key,
const log4cxx::spi::LocationInfo& locationInfo,
const std::string& val1, const std::string& val2) const;
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key using parameters \c val1, \c val2 and \c val3 to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method with the
+ supplied parameters in a string array.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@@ -1081,6 +1242,8 @@ class LOG4CXX_EXPORT Logger :
@param val3 The value for the third placeholder within the pattern.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG3.
*/
void l7dlog(const LevelPtr& level, const std::string& key,
const log4cxx::spi::LocationInfo& locationInfo,
@@ -1088,28 +1251,29 @@ class LOG4CXX_EXPORT Logger :
#if LOG4CXX_WCHAR_T_API
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method .
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@param locationInfo The location info of the logging request.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG.
*/
void l7dlog(const LevelPtr& level, const std::wstring& key,
const log4cxx::spi::LocationInfo& locationInfo) const;
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key using parameter \c val to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method with the
+ supplied parameter in a string array.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@@ -1117,17 +1281,19 @@ class LOG4CXX_EXPORT Logger :
@param val1 The value for the first placeholder within the pattern.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG1.
*/
void l7dlog(const LevelPtr& level, const std::wstring& key,
const log4cxx::spi::LocationInfo& locationInfo,
- const std::wstring& val1) const;
+ const std::wstring& val) const;
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key using parameters \c val1 and \c val2 to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method with the
+ supplied parameters in a string array.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@@ -1136,17 +1302,19 @@ class LOG4CXX_EXPORT Logger :
@param val2 The value for the second placeholder within the pattern.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG2.
*/
void l7dlog(const LevelPtr& level, const std::wstring& key,
const log4cxx::spi::LocationInfo& locationInfo,
const std::wstring& val1, const std::wstring& val2) const;
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key using parameters \c val1, \c val2 and \c val3 to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method with the
+ supplied parameters in a string array.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@@ -1156,6 +1324,8 @@ class LOG4CXX_EXPORT Logger :
@param val3 The value for the third placeholder within the pattern.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG3.
*/
void l7dlog(const LevelPtr& level, const std::wstring& key,
const log4cxx::spi::LocationInfo& locationInfo,
@@ -1163,28 +1333,29 @@ class LOG4CXX_EXPORT Logger :
#endif
#if LOG4CXX_UNICHAR_API
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@param locationInfo The location info of the logging request.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG.
*/
void l7dlog(const LevelPtr& level, const std::basic_string<UniChar>& key,
const log4cxx::spi::LocationInfo& locationInfo) const;
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key using parameter \c val to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method with the
+ supplied parameter in a string array.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@@ -1192,17 +1363,19 @@ class LOG4CXX_EXPORT Logger :
@param val1 The value for the first placeholder within the pattern.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG1.
*/
void l7dlog(const LevelPtr& level, const std::basic_string<UniChar>& key,
const log4cxx::spi::LocationInfo& locationInfo,
- const std::basic_string<UniChar>& val1) const;
+ const std::basic_string<UniChar>& val) const;
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key using parameters \c val1 and \c val2 to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method with the
+ supplied parameters in a string array.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@@ -1211,17 +1384,19 @@ class LOG4CXX_EXPORT Logger :
@param val2 The value for the second placeholder within the pattern.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG2.
*/
void l7dlog(const LevelPtr& level, const std::basic_string<UniChar>& key,
const log4cxx::spi::LocationInfo& locationInfo,
const std::basic_string<UniChar>& val1, const std::basic_string<UniChar>& val2) const;
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key using parameters \c val1, \c val2 and \c val3 to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method with the
+ supplied parameters in a string array.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@@ -1231,6 +1406,8 @@ class LOG4CXX_EXPORT Logger :
@param val3 The value for the third placeholder within the pattern.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG3.
*/
void l7dlog(const LevelPtr& level, const std::basic_string<UniChar>& key,
const log4cxx::spi::LocationInfo& locationInfo,
@@ -1239,28 +1416,29 @@ class LOG4CXX_EXPORT Logger :
#endif
#if LOG4CXX_CFSTRING_API
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@param locationInfo The location info of the logging request.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG.
*/
void l7dlog(const LevelPtr& level, const CFStringRef& key,
const log4cxx::spi::LocationInfo& locationInfo) const;
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key using parameter \c val to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method with the
+ supplied parameter in a string array.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@@ -1268,17 +1446,19 @@ class LOG4CXX_EXPORT Logger :
@param val1 The value for the first placeholder within the pattern.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG1.
*/
void l7dlog(const LevelPtr& level, const CFStringRef& key,
const log4cxx::spi::LocationInfo& locationInfo,
const CFStringRef& val1) const;
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key using parameters \c val1 and \c val2 to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method with the
+ supplied parameters in a string array.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@@ -1287,17 +1467,19 @@ class LOG4CXX_EXPORT Logger :
@param val2 The value for the second placeholder within the pattern.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG2.
*/
void l7dlog(const LevelPtr& level, const CFStringRef& key,
const log4cxx::spi::LocationInfo& locationInfo,
const CFStringRef& val1, const CFStringRef& val2) const;
/**
- Log a localized and parameterized message.
+ Add a new logging event containing \c locationInfo and the localized message \c key using parameters \c val1, \c val2 and \c val3 to attached appender(s) if this logger is enabled for \c level events.
First, the user supplied
<code>key</code> is searched in the resource bundle. Next, the resulting
- pattern is formatted using helpers::StringHelper::format method with the user
- supplied string array <code>params</code>.
+ pattern is formatted using helpers::StringHelper::format method with the
+ supplied parameters in a string array.
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@@ -1307,6 +1489,8 @@ class LOG4CXX_EXPORT Logger :
@param val3 The value for the third placeholder within the pattern.
@see #setResourceBundle
+
+ See also #LOG4CXX_L7DLOG3.
*/
void l7dlog(const LevelPtr& level, const CFStringRef& key,
const log4cxx::spi::LocationInfo& locationInfo,
@@ -1315,6 +1499,7 @@ class LOG4CXX_EXPORT Logger :
#endif
/**
+ Add a new logging event containing \c message and \c location to the appenders attached to this logger if this logger is enabled for \c level events.
This is the most generic printing method. It is intended to be
invoked by <b>wrapper</b> classes.
@@ -1324,6 +1509,7 @@ class LOG4CXX_EXPORT Logger :
void log(const LevelPtr& level, const std::string& message,
const log4cxx::spi::LocationInfo& location) const;
/**
+ Add a new logging event containing \c message to the appenders attached to this logger if this logger is enabled for \c level events.
This is the most generic printing method. It is intended to be
invoked by <b>wrapper</b> classes.
@@ -1333,6 +1519,7 @@ class LOG4CXX_EXPORT Logger :
void log(const LevelPtr& level, const std::string& message) const;
#if LOG4CXX_WCHAR_T_API
/**
+ Add a new logging event containing \c message and \c location to the appenders attached to this logger if this logger is enabled for \c level events.
This is the most generic printing method. It is intended to be
invoked by <b>wrapper</b> classes.
@@ -1342,6 +1529,7 @@ class LOG4CXX_EXPORT Logger :
void log(const LevelPtr& level, const std::wstring& message,
const log4cxx::spi::LocationInfo& location) const;
/**
+ Add a new logging event containing \c message to the appenders attached to this logger if this logger is enabled for \c level events.
This is the most generic printing method. It is intended to be
invoked by <b>wrapper</b> classes.
@@ -1352,6 +1540,7 @@ class LOG4CXX_EXPORT Logger :
#endif
#if LOG4CXX_UNICHAR_API
/**
+ Add a new logging event containing \c message and \c location to the appenders attached to this logger if this logger is enabled for \c level events.
This is the most generic printing method. It is intended to be
invoked by <b>wrapper</b> classes.
@@ -1361,6 +1550,7 @@ class LOG4CXX_EXPORT Logger :
void log(const LevelPtr& level, const std::basic_string<UniChar>& message,
const log4cxx::spi::LocationInfo& location) const;
/**
+ Add a new logging event containing \c message to the appenders attached to this logger if this logger is enabled for \c level events.
This is the most generic printing method. It is intended to be
invoked by <b>wrapper</b> classes.
@@ -1371,6 +1561,7 @@ class LOG4CXX_EXPORT Logger :
#endif
#if LOG4CXX_CFSTRING_API
/**
+ Add a new logging event containing \c message and \c location to the appenders attached to this logger if this logger is enabled for \c level events.
This is the most generic printing method. It is intended to be
invoked by <b>wrapper</b> classes.
@@ -1380,6 +1571,7 @@ class LOG4CXX_EXPORT Logger :
void log(const LevelPtr& level, const CFStringRef& message,
const log4cxx::spi::LocationInfo& location) const;
/**
+ Add a new logging event containing \c message to the appenders attached to this logger if this logger is enabled for \c level events.
This is the most generic printing method. It is intended to be
invoked by <b>wrapper</b> classes.
@@ -1389,6 +1581,7 @@ class LOG4CXX_EXPORT Logger :
void log(const LevelPtr& level, const CFStringRef& message) const;
#endif
/**
+ Add a new logging event containing \c message and \c location to the appenders attached to this logger if this logger is enabled for \c level events.
This is the most generic printing method. It is intended to be
invoked by <b>wrapper</b> classes.
@@ -1419,23 +1612,35 @@ class LOG4CXX_EXPORT Logger :
void removeAppender(const LogString& name) override;
/**
- Set the additivity flag for this Logger instance.
+ Set the additivity flag for this logger.
*/
void setAdditivity(bool additive);
protected:
friend class Hierarchy;
/**
- Only the Hierarchy class can set the hierarchy of a logger.*/
+ Only the Hierarchy class can remove the hierarchy of a logger.
+ */
void removeHierarchy();
+ /**
+ Only the Hierarchy class can set the hierarchy of a logger.
+ */
void setHierarchy(spi::LoggerRepository* repository);
+ /**
+ Only the Hierarchy class can set the parent of a logger.
+ */
void setParent(LoggerPtr parentLogger);
- spi::LoggerRepository* getHierarchy() const;
+ /**
+ Only the Hierarchy class can change the threshold of a logger.
+ */
void updateThreshold();
+ private:
+ spi::LoggerRepository* getHierarchy() const;
+
public:
/**
- Set the level of this Logger.
+ Set the level of this logger.
<p>As in <pre> logger->setLevel(Level::getDebug()); </pre>
@@ -1449,7 +1654,7 @@ class LOG4CXX_EXPORT Logger :
#if LOG4CXX_WCHAR_T_API
/**
- Log a message string with the WARN level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>WARN</code> events.
<p>This method first checks if this logger is <code>WARN</code>
enabled by comparing the level of this logger with the
@@ -1460,10 +1665,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_WARN.
*/
void warn(const std::wstring& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the WARN level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>WARN</code> events.
<p>This method first checks if this logger is <code>WARN</code>
enabled by comparing the level of this logger with the
@@ -1473,12 +1680,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_WARN.
*/
void warn(const std::wstring& msg) const;
#endif
#if LOG4CXX_UNICHAR_API
/**
- Log a message string with the WARN level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>WARN</code> events.
<p>This method first checks if this logger is <code>WARN</code>
enabled by comparing the level of this logger with the
@@ -1489,10 +1698,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_WARN.
*/
void warn(const std::basic_string<UniChar>& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the WARN level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>WARN</code> events.
<p>This method first checks if this logger is <code>WARN</code>
enabled by comparing the level of this logger with the
@@ -1502,12 +1713,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_WARN.
*/
void warn(const std::basic_string<UniChar>& msg) const;
#endif
#if LOG4CXX_CFSTRING_API
/**
- Log a message string with the WARN level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>WARN</code> events.
<p>This method first checks if this logger is <code>WARN</code>
enabled by comparing the level of this logger with the
@@ -1518,10 +1731,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_WARN.
*/
void warn(const CFStringRef& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the WARN level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>WARN</code> events.
<p>This method first checks if this logger is <code>WARN</code>
enabled by comparing the level of this logger with the
@@ -1531,11 +1746,13 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_WARN.
*/
void warn(const CFStringRef& msg) const;
#endif
/**
- Log a message string with the WARN level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>WARN</code> events.
<p>This method first checks if this logger is <code>WARN</code>
enabled by comparing the level of this logger with the
@@ -1546,10 +1763,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_WARN.
*/
void warn(const std::string& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the WARN level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>WARN</code> events.
<p>This method first checks if this logger is <code>WARN</code>
enabled by comparing the level of this logger with the
@@ -1559,12 +1778,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_WARN.
*/
void warn(const std::string& msg) const;
#if LOG4CXX_WCHAR_T_API
/**
- Log a message string with the TRACE level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>TRACE</code> events.
<p>This method first checks if this logger is <code>TRACE</code>
enabled by comparing the level of this logger with the
@@ -1575,10 +1796,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_TRACE.
*/
void trace(const std::wstring& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the TRACE level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>TRACE</code> events.
<p>This method first checks if this logger is <code>TRACE</code>
enabled by comparing the level of this logger with the
@@ -1588,12 +1811,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_TRACE.
*/
void trace(const std::wstring& msg) const;
#endif
#if LOG4CXX_UNICHAR_API
/**
- Log a message string with the TRACE level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>TRACE</code> events.
<p>This method first checks if this logger is <code>TRACE</code>
enabled by comparing the level of this logger with the
@@ -1604,10 +1829,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_TRACE.
*/
void trace(const std::basic_string<UniChar>& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the TRACE level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>TRACE</code> events.
<p>This method first checks if this logger is <code>TRACE</code>
enabled by comparing the level of this logger with the
@@ -1617,12 +1844,14 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_TRACE.
*/
void trace(const std::basic_string<UniChar>& msg) const;
#endif
#if LOG4CXX_CFSTRING_API
/**
- Log a message string with the TRACE level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>TRACE</code> events.
<p>This method first checks if this logger is <code>TRACE</code>
enabled by comparing the level of this logger with the
@@ -1633,10 +1862,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_TRACE.
*/
void trace(const CFStringRef& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the TRACE level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>TRACE</code> events.
<p>This method first checks if this logger is <code>TRACE</code>
enabled by comparing the level of this logger with the
@@ -1646,11 +1877,13 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_TRACE.
*/
void trace(const CFStringRef& msg) const;
#endif
/**
- Log a message string with the TRACE level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>TRACE</code> events.
<p>This method first checks if this logger is <code>TRACE</code>
enabled by comparing the level of this logger with the
@@ -1661,10 +1894,12 @@ class LOG4CXX_EXPORT Logger :
@param msg the message string to log.
@param location location of source of logging request.
+
+ See also #LOG4CXX_TRACE.
*/
void trace(const std::string& msg, const log4cxx::spi::LocationInfo& location) const;
/**
- Log a message string with the TRACE level.
+ Add a new logging event containing \c msg to attached appender(s) if this logger is enabled for <code>TRACE</code> events.
<p>This method first checks if this logger is <code>TRACE</code>
enabled by comparing the level of this logger with the
@@ -1674,6 +1909,8 @@ class LOG4CXX_EXPORT Logger :
hierarchy depending on the value of the additivity flag.
@param msg the message string to log.
+
+ See also #LOG4CXX_TRACE.
*/
void trace(const std::string& msg) const;
@@ -1720,7 +1957,7 @@ LOG4CXX_LIST_DEF(LoggerList, LoggerPtr);
/**
-Logs a message to a specified logger with a specified level.
+Add a new logging event containing \c message to attached appender(s) if this logger is enabled for \c events..
@param logger the logger to be used.
@param level the level to log.
@@ -1732,7 +1969,7 @@ Logs a message to a specified logger with a specified level.
logger->forcedLog(level, oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
/**
-Logs a message to a specified logger with a specified level, formatting utilizing libfmt
+Add a new logging event containing libfmt formatted <code>...</code> to attached appender(s) if this logger is enabled for \c events.
@param logger the logger to be used.
@param level the level to log.
@@ -1743,7 +1980,7 @@ Logs a message to a specified logger with a specified level, formatting utilizin
logger->forcedLog(level, fmt::format( __VA_ARGS__ ), LOG4CXX_LOCATION); }} while (0)
/**
-Logs a message to a specified logger with a specified level.
+Add a new logging event containing \c message to attached appender(s) if this logger is enabled for \c events..
@param logger the logger to be used.
@param level the level to log.
@@ -1756,10 +1993,22 @@ Logs a message to a specified logger with a specified level.
#if !defined(LOG4CXX_THRESHOLD) || LOG4CXX_THRESHOLD <= 10000
/**
-Logs a message to a specified logger with the DEBUG level.
-
-@param logger the logger to be used.
-@param message the message string to log.
+Add a new logging event containing \c message to attached appender(s) if \c logger is enabled for <code>DEBUG</code> events.
+
+@param logger the logger that has the enabled status.
+@param message a valid r-value expression of an <code>operator<<(std::basic::ostream&. ...)</code> overload.
+
+<p>Example:
+<pre>
+LOG4CXX_DEBUG(m_log, "AddMesh:"
+ << " name " << meshName
+ << " type 0x" << std:: hex << traits.Type
+ << " materialName " << meshObject.GetMaterialName()
+ << " visible " << traits.IsDefaultVisible
+ << " at " << obj->getBoundingBox().getCenter()
+ << " +/- " << obj->getBoundingBox().getHalfSize()
+ );
+</pre>
*/
#define LOG4CXX_DEBUG(logger, message) do { \
if (LOG4CXX_UNLIKELY(::log4cxx::Logger::isDebugEnabledFor(logger))) {\
@@ -1767,7 +2016,7 @@ Logs a message to a specified logger with the DEBUG level.
logger->forcedLog(::log4cxx::Level::getDebug(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
/**
-Logs a message to a specified logger with the DEBUG level, formatting with libfmt
+Add a new logging event containing libfmt formatted <code>...</code> to attached appender(s) if \c logger is enabled for <code>DEBUG</code> events.
@param logger the logger to be used.
@param ... The format string and message to log
@@ -1782,10 +2031,16 @@ Logs a message to a specified logger with the DEBUG level, formatting with libfm
#if !defined(LOG4CXX_THRESHOLD) || LOG4CXX_THRESHOLD <= 5000
/**
-Logs a message to a specified logger with the TRACE level.
+Add a new logging event containing \c message to attached appender(s) if \c logger is enabled for <code>TRACE</code> events.
+
+@param logger the logger that has the enabled status.
+@param message a valid r-value expression of an <code>operator<<(std::basic::ostream&. ...)</code> overload.
+
+<p>Example:
+<pre>
+ LOG4CXX_TRACE(m_log, "AddVertex:" << " p " << p[j] << " n " << n << ' ' << color);
+</pre>
-@param logger the logger to be used.
-@param message the message string to log.
*/
#define LOG4CXX_TRACE(logger, message) do { \
if (LOG4CXX_UNLIKELY(::log4cxx::Logger::isTraceEnabledFor(logger))) {\
@@ -1793,7 +2048,7 @@ Logs a message to a specified logger with the TRACE level.
logger->forcedLog(::log4cxx::Level::getTrace(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
/**
-Logs a message to a specified logger with the TRACE level, formatting with libfmt.
+Add a new logging event containing libfmt formatted <code>...</code> to attached appender(s) if \c logger is enabled for <code>TRACE</code> events.
@param logger the logger to be used.
@param ... The format string and message to log
@@ -1808,10 +2063,20 @@ Logs a message to a specified logger with the TRACE level, formatting with libfm
#if !defined(LOG4CXX_THRESHOLD) || LOG4CXX_THRESHOLD <= 20000
/**
-Logs a message to a specified logger with the INFO level.
-
-@param logger the logger to be used.
-@param message the message string to log.
+Add a new logging event containing \c message to attached appender(s) if \c logger is enabled for <code>INFO</code> events.
+
+@param logger the logger that has the enabled status.
+@param message a valid r-value expression of an <code>operator<<(std::basic::ostream&. ...)</code> overload.
+
+<p>Example:
+<pre>
+LOG4CXX_INFO(m_log, surface->GetName()
+ << " successfully planned " << std::fixed << std::setprecision(1) << ((plannedArea / (plannedArea + unplannedArea)) * 100.0) << "%"
+ << " planned area " << std::fixed << std::setprecision(4) << plannedArea << "m^2"
+ << " unplanned area " << unplannedArea << "m^2"
+ << " planned segments " << surface->GetSegmentPlanCount() << " of " << surface->GetSegmentCount()
+ );
+</pre>
*/
#define LOG4CXX_INFO(logger, message) do { \
if (::log4cxx::Logger::isInfoEnabledFor(logger)) {\
@@ -1819,10 +2084,9 @@ Logs a message to a specified logger with the INFO level.
logger->forcedLog(::log4cxx::Level::getInfo(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
/**
-Logs a message to a specified logger with the INFO level, formatting with libfmt.
+Add a new logging event containing libfmt formatted <code>...</code> to attached appender(s) if \c logger is enabled for <code>INFO</code> events.
@param logger the logger to be used.
-@param message the message string to log.
@param ... The format string and message to log
*/
#define LOG4CXX_INFO_FMT(logger, ...) do { \
@@ -1835,10 +2099,18 @@ Logs a message to a specified logger with the INFO level, formatting with libfmt
#if !defined(LOG4CXX_THRESHOLD) || LOG4CXX_THRESHOLD <= 30000
/**
-Logs a message to a specified logger with the WARN level.
+Add a new logging event containing \c message to attached appender(s) if \c logger is enabled for <code>WARN</code> events.
@param logger the logger to be used.
@param message the message string to log.
+
+<p>Example:
+<pre>
+catch (const std::exception& ex)
+{
+ LOG4CXX_WARN(m_log, ex.what() << ": in " << m_task->GetParamFilePath());
+}
+</pre>
*/
#define LOG4CXX_WARN(logger, message) do { \
if (::log4cxx::Logger::isWarnEnabledFor(logger)) {\
@@ -1846,7 +2118,7 @@ Logs a message to a specified logger with the WARN level.
logger->forcedLog(::log4cxx::Level::getWarn(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
/**
-Logs a message to a specified logger with the WARN level, formatting with libfmt
+Add a new logging event containing libfmt formatted <code>...</code> to attached appender(s) if \c logger is enabled for <code>WARN</code> events.
@param logger the logger to be used.
@param ... The format string and message to log
@@ -1861,10 +2133,18 @@ Logs a message to a specified logger with the WARN level, formatting with libfmt
#if !defined(LOG4CXX_THRESHOLD) || LOG4CXX_THRESHOLD <= 40000
/**
-Logs a message to a specified logger with the ERROR level.
+Add a new logging event containing \c message to attached appender(s) if \c logger is enabled for <code>ERROR</code> events.
@param logger the logger to be used.
@param message the message string to log.
+
+<p>Example:
+<pre>
+catch (std::exception& ex)
+{
+ LOG4CXX_ERROR(m_log, ex.what() << " in AddScanData");
+}
+</pre>
*/
#define LOG4CXX_ERROR(logger, message) do { \
if (::log4cxx::Logger::isErrorEnabledFor(logger)) {\
@@ -1872,7 +2152,7 @@ Logs a message to a specified logger with the ERROR level.
logger->forcedLog(::log4cxx::Level::getError(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
/**
-Logs a message to a specified logger with the ERROR level, formatting with libfmt
+Add a new logging event containing libfmt formatted <code>...</code> to attached appender(s) if \c logger is enabled for <code>ERROR</code> events.
@param logger the logger to be used.
@param ... The format string and message to log
@@ -1882,7 +2162,7 @@ Logs a message to a specified logger with the ERROR level, formatting with libfm
logger->forcedLog(::log4cxx::Level::getError(), fmt::format( __VA_ARGS__ ), LOG4CXX_LOCATION); }} while (0)
/**
-Logs a error if the condition is not true.
+If \c condition is not true, add a new logging event containing \c message to attached appender(s) if \c logger is enabled for <code>ERROR</code> events.
@param logger the logger to be used.
@param condition condition
@@ -1894,7 +2174,7 @@ Logs a error if the condition is not true.
logger->forcedLog(::log4cxx::Level::getError(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
/**
-Logs a error if the condition is not true, formatting with libfmt
+If \c condition is not true, add a new logging event containing libfmt formatted \c message to attached appender(s) if \c logger is enabled for <code>ERROR</code> events.
@param logger the logger to be used.
@param condition condition
@@ -1913,10 +2193,15 @@ Logs a error if the condition is not true, formatting with libfmt
#if !defined(LOG4CXX_THRESHOLD) || LOG4CXX_THRESHOLD <= 50000
/**
-Logs a message to a specified logger with the FATAL level.
+Add a new logging event containing \c message to attached appender(s) if \c logger is enabled for <code>FATAL</code> events.
@param logger the logger to be used.
@param message the message string to log.
+
+<p>Example:
+<pre>
+LOG4CXX_FATAL(m_log, m_renderSystem->getName() << " is not supported");
+</pre>
*/
#define LOG4CXX_FATAL(logger, message) do { \
if (::log4cxx::Logger::isFatalEnabledFor(logger)) {\
@@ -1924,7 +2209,7 @@ Logs a message to a specified logger with the FATAL level.
logger->forcedLog(::log4cxx::Level::getFatal(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
/**
-Logs a message to a specified logger with the FATAL level, formatting with libfmt
+Add a new logging event containing libfmt formatted <code>...</code> to attached appender(s) if \c logger is enabled for <code>FATAL</code> events.
@param logger the logger to be used.
@param ... The format string and message to log
@@ -1938,7 +2223,7 @@ Logs a message to a specified logger with the FATAL level, formatting with libfm
#endif
/**
-Logs a localized message with no parameter.
+Add a new logging event containing the localized message \c key to attached appender(s) if \c logger is enabled for \c level events.
@param logger the logger to be used.
@param level the level to log.
@@ -1949,7 +2234,7 @@ Logs a localized message with no parameter.
logger->l7dlog(level, key, LOG4CXX_LOCATION); }} while (0)
/**
-Logs a localized message with one parameter.
+Add a new logging event containing the localized message \c key to attached appender(s) if \c logger is enabled for \c level events with one parameter.
@param logger the logger to be used.
@param level the level to log.
@@ -1961,7 +2246,7 @@ Logs a localized message with one parameter.
logger->l7dlog(level, key, LOG4CXX_LOCATION, p1); }} while (0)
/**
-Logs a localized message with two parameters.
+Add a new logging event containing the localized message \c key to attached appender(s) if \c logger is enabled for \c level events with two parameters.
@param logger the logger to be used.
@param level the level to log.
@@ -1974,7 +2259,7 @@ Logs a localized message with two parameters.
logger->l7dlog(level, key, LOG4CXX_LOCATION, p1, p2); }} while (0)
/**
-Logs a localized message with three parameters.
+Add a new logging event containing the localized message \c key to attached appender(s) if \c logger is enabled for \c level events with three parameters.
@param logger the logger to be used.
@param level the level to log.