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 2024/07/25 00:16:36 UTC
(logging-log4cxx) branch master updated: Improve reference documentation (#398)
This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
The following commit(s) were added to refs/heads/master by this push:
new 824563dc Improve reference documentation (#398)
824563dc is described below
commit 824563dce998d93d11ec32c618cdbda2834c41ac
Author: Stephen Webb <st...@ieee.org>
AuthorDate: Thu Jul 25 10:16:31 2024 +1000
Improve reference documentation (#398)
---
src/main/include/log4cxx/spi/loggingevent.h | 139 +++++++++++++---------------
1 file changed, 65 insertions(+), 74 deletions(-)
diff --git a/src/main/include/log4cxx/spi/loggingevent.h b/src/main/include/log4cxx/spi/loggingevent.h
index 29cf78b6..cd0b81c8 100644
--- a/src/main/include/log4cxx/spi/loggingevent.h
+++ b/src/main/include/log4cxx/spi/loggingevent.h
@@ -29,20 +29,16 @@
namespace LOG4CXX_NS
{
-namespace helpers
-{
-class ObjectOutputStream;
-}
namespace spi
{
LOG4CXX_LIST_DEF(KeySet, LogString);
/**
-The internal representation of logging events. When an affirmative
-decision is made to log then a <code>LoggingEvent</code> instance
-is created. This instance is passed around to the different log4cxx
-components.
+The data recorded for each logging request.
+Each logging request instantiates a <code>LoggingEvent</code> instance,
+which Log4cxx provides to [filters](@ref log4cxx.spi.Filter),
+[layouts](@ref log4cxx.Layout) and [appenders](@ref log4cxx.Appender).
<p>This class is of concern to those wishing to extend log4cxx.
*/
@@ -57,150 +53,145 @@ class LOG4CXX_EXPORT LoggingEvent :
typedef spi::KeySet KeySet;
- /** For serialization only
+ /** An empty event.
*/
LoggingEvent();
/**
- Instantiate a LoggingEvent from the supplied parameters.
+ An event composed using the supplied parameters.
- <p>Except timeStamp all the other fields of
- <code>LoggingEvent</code> are filled when actually needed.
- <p>
- @param logger The logger of this event.
- @param level The level of this event.
+ @param logger The logger used to make the logging request.
+ @param level The severity of this event.
@param location The source code location of the logging request.
@param message The text to add to this event.
*/
LoggingEvent
( const LogString& logger
, const LevelPtr& level
- , const spi::LocationInfo& location
+ , const LocationInfo& location
, LogString&& message
);
/**
- Instantiate a LoggingEvent from the supplied parameters.
+ An event composed using the supplied parameters.
- <p>Except timeStamp all the other fields of
- <code>LoggingEvent</code> are filled when actually needed.
- <p>
- @param logger The logger of this event.
- @param level The level of this event.
+ @param logger The logger used to make the logging request.
+ @param level The severity of this event.
@param message The text to add to this event.
@param location The source code location of the logging request.
*/
- LoggingEvent(const LogString& logger,
- const LevelPtr& level, const LogString& message,
- const LOG4CXX_NS::spi::LocationInfo& location);
+ LoggingEvent
+ ( const LogString& logger
+ , const LevelPtr& level
+ , const LogString& message
+ , const LocationInfo& location
+ );
~LoggingEvent();
- /** Return the level of this event. */
+ /** The severity level of the logging request that generated this event. */
const LevelPtr& getLevel() const;
- /** Return the name of the logger. */
+ /** The name of the logger used to make the logging request. */
const LogString& getLoggerName() const;
- /** Return the message for this logging event. */
+ /** The message provided in the logging request. */
const LogString& getMessage() const;
- /** Return the message for this logging event. */
+ /** The message provided in the logging request. */
const LogString& getRenderedMessage() const;
- /**Returns the time when the application started,
- in microseconds elapsed since 01.01.1970.
- */
+ /** The number of microseconds elapsed since 1970-01-01
+ * at the time the application started.
+ */
static log4cxx_time_t getStartTime();
- /** Return the threadName of this event. */
+ /** The identity of the thread in which this logging event was created. */
const LogString& getThreadName() const;
/**
- * Get the user name of the thread. The default name is (noname) if
- * Log4cxx is unable to retrieve the name using a platform-specific call.
+ * The name you gave to the thread in which this logging event was created.
+ * You can create a named thread using log4cxx::helpers::ThreadUtility::createThread.
+ * If Log4cxx is unable to retrieve the thread name using a platform-specific call,
+ * the value is the same as the thread identity.
*/
const LogString& getThreadUserName() const;
- /** The number of microseconds elapsed from 01.01.1970 until logging event
- was created. */
+ /** The number of microseconds elapsed since 1970-01-01
+ * at the time this logging event was created.
+ */
log4cxx_time_t getTimeStamp() const;
+ /** The value of the system clock at the time this logging event was created.
+ */
std::chrono::time_point<std::chrono::system_clock> getChronoTimeStamp() const;
- /* Return the file where this log statement was written. */
- const LOG4CXX_NS::spi::LocationInfo& getLocationInformation() const;
+ /** The source code location where the logging request was made. */
+ const LocationInfo& getLocationInformation() const;
/**
- * This method appends the NDC for this event to passed string. It will return the
- * correct content even if the event was generated in a different
- * thread or even on a different machine. The NDC#get method
- * should <em>never</em> be called directly.
+ * Add the current nested diagnostic context to the end of \c dest.
+ * The diagnostic context must have been loaded into this LoggingEvent using LoadDC,
+ * to obtain the correct content if the event was generated in a different thread.
*
- * @param dest destination for NDC, unchanged if NDC is not set.
- * @return true if NDC is set.
+ * @param dest the string to be added to.
+ * @return true if \c dest is changed.
*/
bool getNDC(LogString& dest) const;
/**
- * Appends the the context corresponding to the <code>key</code> parameter.
- * If there is a local MDC copy, possibly because we are in a logging
- * server or running inside AsyncAppender, then we search for the key in
- * MDC copy, if a value is found it is returned. Otherwise, if the search
- * in MDC copy returns an empty result, then the current thread's
- * <code>MDC</code> is used.
+ * Add the value associated with \c key to the end of \c dest.
+ * The diagnostic context must have been loaded into this LoggingEvent using LoadDC,
+ * to obtain the correct content if the event was generated in a different thread.
*
- * <p>
- * Note that <em>both</em> the local MDC copy and the current thread's MDC
- * are searched.
- * </p>
- * @param key key.
- * @param dest string to which value, if any, is appended.
- * @return true if key had a corresponding value.
+ * @param key mapped diagnostic context key value.
+ * @param dest the string to be added to.
+ * @return true if \c dest is changed.
*/
bool getMDC(const LogString& key, LogString& dest) const;
/**
- * Returns the set of of the key values in the MDC for the event.
- * The returned set is unmodifiable by the caller.
+ * The keys in the mapped diagnostic context for the event.
*
- * @return Set an unmodifiable set of the MDC keys.
+ * @return the mapped diagnostic context keys.
*
*/
KeySet getMDCKeySet() const;
#if LOG4CXX_ABI_VERSION <= 15
/**
- Obtain a copy of this thread's MDC prior to serialization
- or asynchronous logging.
+ Obtain a copy of the current thread's diagnostic context data.
*/
[[ deprecated( "Use LoadDC instead" ) ]]
void getMDCCopy() const;
#endif
/**
- Obtain a copy of this thread's diagnostic context prior to serialization
- or asynchronous logging.
+ * Obtain a copy of the current thread's diagnostic context data.
+ * The diagnostic context must be loaded to ensure the
+ * correct diagnostic context data is available
+ * when the event is stored for later use
+ * (for example, when the appender uses a different thread to process this event).
*/
void LoadDC() const;
/**
- * Return a previously set property.
- * @param key key.
- * @param dest string to which value, if any, is appended.
- * @return true if key had a corresponding value.
+ * Append onto \c dest the value associated with the property \c key.
+ * @param key the property name.
+ * @param dest the string onto which to associated value is appended.
+ * @return true if \c dest was changed.
*/
bool getProperty(const LogString& key, LogString& dest) const;
+
/**
- * Returns the set of of the key values in the properties
- * for the event. The returned set is unmodifiable by the caller.
- *
- * @return Set an unmodifiable set of the property keys.
+ * The set of of the key values in the properties
+ * for the event.
+ * @return the keys from properties in this event.
*/
KeySet getPropertyKeySet() const;
/**
- * Set a string property using a key and a string value. since 1.3
+ * Associate \c value with the property \c key.
*/
void setProperty(const LogString& key, const LogString& value);